Commit 3a309875 authored by admuc's avatar admuc
Browse files

update 2020-09-26

parent a85ccc94
......@@ -16,3 +16,4 @@ blog/*
!blog/content/
blog/content/output/
readme.txt
download_files/
= Howto Validate AsciiDoc3 DocBook 5.1
:date: 2020-08-06
DocBook is the de-facto standard for technical documentation; AsciiDoc3 uses DocBook version 4.5 by default - and this is sufficient for many (or the most) use cases. But 4.5 is 'feature frozen', the current version is DocBook 5.1. If you want to use the flexibility and the more modern conception of DocBook51, AsciiDoc3 supports you - probably the only software that comes with this feature: AsciiDoc Markup -> DocBook51!
To obtain a docbook51 xml document, just compute:
---------------------------------
asciidoc3 -b docbook51 test.txt
---------------------------------
The 'text.xml' file should be (highly recommended) validated before further processing. That means, a tool checks if all rules of the DocBook5.1 definition written in RelaxNG and Schematron have been included. We have to go two steps with two different tools: first to ensure the Relax Schema, second, the Schematron Schema.
You find the RelaxNG Schema and the tools in your distribution +
'./tests/docbook_validation/rng-docbook51.rng' and online:
-------------------
https://gitlab.com/asciidoc3/asciidoc3/-/tree/master/tests/docbook_validation
- ...
- asciidoc3_docbook51_relaxng_validation.py
- asciidoc3_docbook51_schematron_validation.py
- ...
-------------------
The tools name show its purpose. You can validate just one file or all files in a distinct directory:
-----------------------------
python3 ./tests/docbook_validation/asciidoc3_docbook51_relaxng_validation.py path/to/docbook_file.xml
python3 ./tests/docbook_validation/asciidoc3_docbook51_relaxng_validation.py
-----------------------------
The tools refer to the following 'third party' tools (you don't need all of them):
- xmllint
- jing
- sun java msv
- lxml
- xmlstarlet
Probably the easiest to handle are 'xmllint' and 'lxml' - see the docstring of the tools for more inormation. You can disable a program that is not present.
Find more information about AsciiDoc3's full support of DocBook 5.1 in your distribution
../doc/readme_docbook51.txt
or read online:
https://gitlab.com/asciidoc3/asciidoc3/-/blob/master/doc/readme_docbook51.txt
Keywords: AsciiDoc3 3.2.0 DocBook v5.1 Validator RelaxNG Schematron Standalone HowTo
= New Release 3.2.0 is in
:date: 2020-04-16
The new release is out: +
AsciiDoc3-3.2.0
You'll see some new features:
- Full DocBook v5.1 support,
- DocBook45 and DocBook51 validator (RelaxNG *and* Schematron included!),
- Full support for installing via a Windows virtual envronment (venv),
- Faster than ever,
- ...
To obtain the new version look https://asciidoc3.org/download.html[here]
Keywords: AsciiDoc3 3.2.0 DocBook v5.1 Validator Schematron Windows venv PyPI
= Transition to New Release Starts
:date: 2020-04-14
Good news right now as the Easter holiday begins: the transition to the new AsciiDoc3 release 3.2.0 starts today. From now on you can download the release candidate on our server. This is not a beta, all of our tests look good - but we want to be sure and wait for a second battery of tests to run. +
A shortened list of the new features:
- Full (!) DocBook v5.1 support,
- DocBook45 and DocBook51 validator (RelaxNG *and* Schematron included!),
- Faster than ever,
- ...
In the next days the deb/rpm/zip/pypi files will follow ...
------------------
wget https://asciidoc3.org/asciidoc3-3.2.0rc.tar.gz
------------------
(Edited 2020-04-11: md5sum asciidoc3-3.2.0rc.tar.gz a0cbef0ecaf9e9957a6adf284da9817a)
(Update 2020-04-14): New version 3.2.0 available via PyPI. This is not a beta, it's the release candidate.
.No virtual environment (venv)
-----------------------------
pip3 install --index-url https://test.pypi.org/simple --user asciidoc3==3.2.0b1
-----------------------------
.With virtual environment (venv)
----------------------------
pip3 install --index-url https://test.pypi.org/simple asciidoc3==3.2.0b1
----------------------------
Keywords: AsciiDoc3 New Release DocBook v5.1 Validator Schematron Tarball PyPI
#!/bin/sh
VERS="3.1.0"
DATE="2020-03-20"
VERS="3.2.0"
DATE="2020-04-10"
# Leave the desired layout uncommented.
#LAYOUT=layout1 # Tables based layout.
#LAYOUT=layout2 # CSS based layout.
LAYOUT=responsivelayout # CSS responsive.
#LAYOUT=responsivelayout # CSS responsive.
LAYOUT=responsive_menu # CSS responsive menu.
ASCIIDOC3_HTML="asciidoc3 --backend=xhtml11 --conf-file=${LAYOUT}.conf --attribute icons --attribute iconsdir=../../images/icons --attribute=badges --attribute=revision=$VERS --attribute=date=$DATE"
......
......@@ -24,7 +24,7 @@ image:empty.png["empty",height=25]
Please take note of the <<end,annotation>> at the end of this document. To generate a html-file: 'asciidoc3 -n -a icons -a latexmath cheatsheet.txt'.
Do *not* try 'a2x3 -f pdf cheatsheet.txt', because the plain source yields just an (html-)example and not valid DocBook.
Download a PDF [line-through]*https://asciidoc3.org/cheatsheet.pdf[here]* (pending) (with missing pics and damaged formulae, but effectual). This document will be updated from time to time.
Download a PDF https://asciidoc3.org/cheatsheet.pdf[here]. This document will be updated from time to time.
image:logo_asciidoc3.png["AsciiDoc3 Logo",height=10]
......@@ -799,6 +799,12 @@ Some example 'LaTeXMathML' formulas, see './doc/latexmathml.txt' for more infos
image:latexmathexample.png["latexmath",height=300]
.AsciiDoc3 source
image:latexmath_source.png["latexmath_source",height=325]
image:empty.png["empty",height=25]
image:logo_asciidoc3.png["AsciiDoc3 Logo",height=10]
......
= AsciiDoc3 Download
On this page you can download the AsciiDoc3 files. +
The 'tarball' is recommended for Unix, GNU/Linux, and other POSIX OS. +
'Packages' are available for Debian / RPM Systems. +
The 'zipped file' is specific to Windows-users - no symlinks here. +
'PyPI / pip' should work with GNU/Linux and Windows.
On this page you can download the AsciiDoc3 files you need for installing. +
Take a look link:install.html[here] to learn more about the different ways to install AsciiDoc3.
== GNU/Linux
.'System wide', superuser (sudo/su/root) rights required
[width="70%",cols=">s,^m,^m",frame="topbot"]
|==========================
| | *Files* | *Distro*
|Generic | Tarball: <<Tarb,asciidoc3-3.x.y.tar.gz>> | All
|Debian | Package: <<Dpack,asciidoc3.deb>> | Debian, Ubuntu, Mint, ...
|RedHat/openSuse | Package: <<Rpack,asciidoc3.rpm>> | Centos, RHEL, Leap, Tumbleweed, Fedora, ...
|==========================
.'Local', users home directory only, no superuser (sudo/su/root) rights required (*)
[width="70%",cols=">s,^m,^m",frame="topbot"]
|==========================
| | *Files* | *Info*
|Pip/PyPI | PyPI Project Page: https://pypi.org/project/asciidoc3[PyPI] | See link:pypi.html[here]
|Git | GitLab https://gitlab.com/asciidoc3/asciidoc3[AsciiDoc3] | See <<Ginfo,here>>
|Generic | Tarball: <<Tarb,asciidoc3-3.x.y.tar.gz>> | All
|==========================
(*) Python3 should be present, of course - that's a given in all major distros. And probably you'll need some extra software like dblatex, Apache FOP etc...
[TIP]
It's a good idea to make use of Python's https://docs.python.org/3/library/venv.html['venv'] (virtual environment), especially when working with link:pypi.html[pip].
== Windows
Windows user look link:windows.html[here] and/or link:pypi.html[here].
== Current Version (Latest)
The current version (the latest) is
*AsciiDoc3-3.1.0*
*AsciiDoc3-3.2.0*
Day of release: 2019-04-12
Day of release: 2020-04-16
[[Tarb]]
=== Tarball
You can download the distribution tarball here: +
Updated: 2019-05-10
[subs="none"]
++++++++++++++++++++++++
<a href="asciidoc3-3.1.0.tar.gz">asciidoc3-3.1.0.tar.gz</a>
<a href="asciidoc3-3.2.0.tar.gz">asciidoc3-3.2.0.tar.gz</a>
++++++++++++++++++++++++
GNU/Linux md5sum +
12a57a365e3b6f503e1ed00d8afc5bf8
7d88835ffbfe30fa896977a983f64c62
You may use wget as well
------------
wget https://asciidoc3.org/asciidoc3-3.1.0.tar.gz
wget https://asciidoc3.org/asciidoc3-3.2.0.tar.gz
------------
[[Dpack]]
=== Debian deb Package
Use this for Debian / Ubuntu / Lubuntu / Mint +
and all Debian-based distros. +
Updated: 2019-05-11
and all Debian-based distros.
[subs="none"]
++++++++++++++++++++++++
......@@ -45,71 +74,67 @@ Updated: 2019-05-11
++++++++++++++++++++++++
GNU/Linux md5sum +
f35cc02693bae43de6a32a8e0dd27cf8
60136a33f0558450018ae56d146cf3fb
You may use wget as well
------------
wget https://asciidoc3.org/asciidoc3.deb
------------
[[Rpack]]
=== RPM rpm Package
Use this for openSUSE Leap / Tumbleweed / Fedora / CentOS / RHEL +
and all other rpm-based distros. +
Updated: 2019-05-11
and all other rpm-based distros.
[subs="none"]
++++++++++++++++++++++++
<a href="asciidoc3-3.1.0-2.noarch.rpm">asciidoc3-3.1.0-2.noarch.rpm</a>
<a href="asciidoc3-3.2.0-2.noarch.rpm">asciidoc3-3.2.0-2.noarch.rpm</a>
++++++++++++++++++++++++
GNU/Linux md5sum +
25d6a2ee69c214fa6d103ab3beb07f1c
aade6ddf96c959ce84765c90d56ce921
You may use wget as well
------------
wget https://asciidoc3.org/asciidoc3-3.1.0-2.noarch.rpm
wget https://asciidoc3.org/asciidoc3-3.2.0-2.noarch.rpm
------------
[[Ginfo]]
=== GIT
You can download, fork or clone the repo here: +
https://gitlab.com/asciidoc3/asciidoc3
Be careful: +
*not* github.com/asciidoc/asciidoc +
(this is the outdated Python2 version).
=== ZIP-File
You can download the distribution zip-file here: +
Use this for Windows OS. +
Updated: 2019-05-10
This file contains no symlinks, this may be useful especially for Windows.
[subs="none"]
++++++++++++++++++++++++
<a href="asciidoc3-3.1.0.zip">asciidoc3-3.1.0.zip</a>
<a href="asciidoc3-3.2.0.zip">asciidoc3-3.2.0.zip</a>
++++++++++++++++++++++++
GNU/Linux md5sum +
d41085d65a2d36972ed38445d1d3d5f4
25de8e67aba8e01ff25b8c89233857b9
Windows md5sum (to check you may download the free tool here: 'winmd5.com') +
d41085d65a2d36972ed38445d1d3d5f4
25de8e67aba8e01ff25b8c89233857b9
Yes, the md5sums are of course identical :-)
You may use wget as well
------------
wget https://asciidoc3.org/asciidoc3-3.1.0.zip
wget https://asciidoc3.org/asciidoc3-3.2.0.zip
------------
=== GitLab
Please feel free to download/fork AsciiDoc3 on GitLab:
https://gitlab.com/asciidoc3/asciidoc3
Be careful: +
*not* github.com/asciidoc/asciidoc +
(this is the outdated Python2 version).
=== PyPI
The files can be found https://pypi.org/project/asciidoc3/[here]. +
Before you 'pip install --user asciidoc3' see the information given link:pypi.html[here].
......@@ -128,66 +153,17 @@ Do *not* use older versions of AsciiDoc3 any more! +
Do so only if you know what you are doing.
'AsciiDoc3-3.0.3 (Day of release: January-07-2019)'
[subs="none"]
++++++++++++++++++++++++
<a href="asciidoc3-3.0.3.tar.gz">asciidoc3-3.0.3.tar.gz</a>
++++++++++++++++++++++++
.Previous Versions of AsciiDoc3
[width="60%",cols=">s,^m,^m,^m",frame="topbot"]
|==========================
| | *Release Date* | *Link* | *md5sum*
|AsciiDoc3-3.1.0 | April-04-2019 | https://asciidoc3.org/asciidoc3-3.1.0.tar.gz[asciidoc3-3.1.0.tar.gz] | 12a57a365e3b6f503e1ed00d8afc5bf8
|AsciiDoc3-3.0.3 | January-07-2019 | https://asciidoc3.org/asciidoc3-3.0.3.tar.gz[asciidoc3-3.0.3.tar.gz] | 6f7fc7427da4ad22ffbeabe1362e1c46
| ditto zip | January-07-2019 | https://asciidoc3.org/asciidoc3-3.0.3.zip[asciidoc3-3.0.3.zip] | 69f1f5ce78c6050b27f26b01f4e32c5d
|AsciiDoc3-3.0.2 | June-15-2018 | https://asciidoc3.org/asciidoc3-3.0.2.tar.gz[asciidoc3-3.0.2.tar.gz] | 2b71b4848f2a7d03569612d100626996
|AsciiDoc3-3.0.1 | May-16-2018 | https://asciidoc3.org/asciidoc3-3.0.1.tar.gz[asciidoc3-3.0.1.tar.gz] | ae15f9553d783a054ecfc356921f15fc
|AsciiDoc3-3.0.1rc | April-13-2018 | https://asciidoc3.org/asciidoc3-3.0.1rc.tar.gz[asciidoc3-3.0.1rc.tar.gz] | e4d28390c36aedd3dca6e2a7b1a44075
GNU/Linux md5sum +
6f7fc7427da4ad22ffbeabe1362e1c46
|==========================
image:empty.png["empty", height=30, width=30]
[subs="none"]
++++++++++++++++++++++++
<a href="asciidoc3-3.0.3.zip">asciidoc3-3.0.3.zip</a>
++++++++++++++++++++++++
69f1f5ce78c6050b27f26b01f4e32c5d
image:empty.png["empty", height=30, width=30]
image:empty.png["empty", height=30, width=30]
'AsciiDoc3-3.0.2 (Day of release: June-15-2018)'
[subs="none"]
++++++++++++++++++++++++
<a href="asciidoc3-3.0.2.tar.gz">asciidoc3-3.0.2.tar.gz</a>
++++++++++++++++++++++++
GNU/Linux md5sum +
2b71b4848f2a7d03569612d100626996
image:empty.png["empty", height=30, width=30]
image:empty.png["empty", height=30, width=30]
'AsciiDoc3-3.0.1 (Day of release: May-16-2018)'
[subs="none"]
++++++++++++++++++++++++
<a href="asciidoc3-3.0.1.tar.gz">asciidoc3-3.0.1.tar.gz</a>
++++++++++++++++++++++++
GNU/Linux md5sum +
ae15f9553d783a054ecfc356921f15fc
image:empty.png["empty", height=30, width=30]
image:empty.png["empty", height=30, width=30]
'AsciiDoc3-3.0.1rc (Day of release: April-13-2018)'
[subs="none"]
++++++++++++++++++++++++
<a href="asciidoc3-3.0.1rc.tar.gz">asciidoc3-3.0.1rc.tar.gz</a>
++++++++++++++++++++++++
GNU/Linux md5sum +
e4d28390c36aedd3dca6e2a7b1a44075
AsciiDoc3 Home Page
==================
// Web page meta data.
:keywords: AsciiDoc3, AsciiDoc, Python3, DocBook, EPUB, PDF, ebooks, slideshow, slidy, man page
:keywords: AsciiDoc3, Windows, AsciiDoc, Python3, DocBook 5.1, EPUB, PDF, ebooks, slideshow, slidy, man page
:description: AsciiDoc3 is a text document format for writing notes, +
documentation, articles, books, ebooks, slideshows, +
web pages, man pages and blogs. AsciiDoc3 files can be +
......@@ -12,15 +12,27 @@ AsciiDoc3 Home Page
//.{revdate}: AsciiDoc3 {revnumber} Released
[WARNING]
There is a new version on PyPI.org -> AsciiDoc3 3.2.1 +
This is a bugfix release - in some cases, and when not using venv, asciidoc3_postinstall failed. This happened only on Windows. +
GNU/Linux systems are not affected, so the deb/rpm/gz files are for now unchanged and you do not need to update anyhow. +
If you install 'pip install asciidoc3' or update 'pip install asciidoc3 -U' (see link:pypi.html[here]), the fixed version is loaded automatically for you.
************************************************************************
The new release *AsciiDoc3-3.2.0* waits in the wings! +
Please have patience with us until the end of March '20.
Latest: *AsciiDoc3 3.2.0* +
Highlights: +
- Full (!) support of DocBook v5.1,
- Works with Windows (yes!) in a Python virtual environment (venv) - recommended, available via PyPI.org / pip,
- A lot of tested templates to use,
- Faster than ever,
- ...,
- See Changelog link:releasenotes.html#_changelog[here].
Current version: +
AsciiDoc3-3.1.0 +
GNU/Linux: Unified Installer (Tarball) / Debian-Package / RPM-Package / PyPI. +
Windows: zip-File / PyPI. +
Windows: zip-File (no symlinks) / PyPI. +
Works seamlessly system-wide, local, or in a Python https://docs.python.org/3/library/venv.html[virtual environment]! +
No admin rights necessary when running local. +
https://getpelican.com/[Pelican] plugin for AsciiDoc3 is available, too. See our https://asciidoc3.org/blog/pelican-plugin-for-asciidoc3-available.html[blog].
......@@ -71,15 +83,10 @@ I thank all the contributors for their awesome work.
On this page, in all related documents, and all the stuff around I make heavy use of the documents given on asciidoc.org (the 'end of live' Python2.x implementation)
************************************************************************
AsciiDoc3 is not asciidoc-py3 +
The 'offical community' of AsciiDoc makes a point of the following statement: the AsciiDoc3 implementation (which you can find on this website) is a personal project. The only official port of AsciiDoc Py to Python 3 is https://github.com/asciidoc/asciidoc-py3. It was done with support from the AsciiDoc Py leadership and by following a procedure that honored the copyright and license and was in the spirit of open source. (see link:https://github.com/asciidoc/asciidoc-py3/issues/11[here]) +
.AsciiDoc3 is not asciidoc-py3
The 'offical community' of AsciiDoc makes a point of the following statement: the AsciiDoc3 implementation (which you can find on this website asciidoc3.org) is a personal project. You can find another port of AsciiDoc to Python 3 https://github.com/asciidoc/asciidoc-py3[here]. +
Commentary: AsciiDoc (Python 2) is open source under the terms of the GPLv2+. So are both AsciiDoc3 (Python 3) and asciidoc-py3. Every user may choose what he/she/div likes to run. As far as I can see any of the two programs cover all requested features.
************************************************************************
=== Bug reports
- When reporting problems please illustrate the problem with the
......
= AsciiDoc3 Installation
TIP: AsciiDoc3 requires *Python 3.5* (or higher)
TIP: AsciiDoc3 requires 'Python 3.5' or higher
to run, it will definitely crash when using Python2.x. Probably there are
few systems in the real world running with Python 3.0, 3.1, 3.2, 3.3 or 3.4 any more - these versions have reached their end of live. Please consider updating to a newer version! Python 3.5 / 3.6 / 3.7 /3.8 is a good choice - you don't need the most recent branch at all. Python is installed by
few systems in the real world running with Python < 3.5 any more - these versions have reached their end of live. Please consider updating to a newer version! You don't need the most recent branch at all, everything greater or even 3.5 works fine. Python is installed by
default in most Unix and GNU/Linux distributions. If you don't find an up-to-date version
of Python installed it can be downloaded from the official Python website https://www.python.org/.
of Python installed it can be downloaded from the official Python website https://www.python.org/. +
Windows users please look link:windows.html[here].
[WARNING]
Command line 'python3' obligatory! Please note: To run AsciiDoc3, the executable command 'python3' is a must-have. That means, typing 'python3' at the command line starts the Python3 executable and you see something like +
To run AsciiDoc3 the executable command 'python3' is a must-have. That means, typing 'python3' at the command line starts the Python3 executable and you see something like +
'$ python3' +
'$ Python 3.7.3 (default, Apr 3 2019, 05:39:12) [GCC 8.3.0] on linux' +
'Type "help", "copyright", "credits" or "license" for more information.' +
'>>>' +
In almost every Unix and GNU/Linux distribution this is a given. When not, you can easily add a symlink python3 -> python3.7 (please take your current version) and add python3 to your PATH ... +
Windows users need probably a 'windows alias for python 3'. For further information about AsciiDoc3 and Windows see link:windows.html[here].
In (almost) every Unix and GNU/Linux distribution this is a given. If not, you can easily add a symlink python3 -> python3.7 (please take your current version). Be sure that 'python3' is in your PATH. +
Windows users need in many cases an alias for python3 -> python. This is 'not' necessary when installing via the recommended Python virtual environment https://docs.python.org/3/library/venv.html[venv]. For further information about AsciiDoc3 and Windows see link:windows.html[here].
== Which way to install?
AsciiDoc3 is available in a few different flavors (which work all the same, naturally). Please choose the appropriate files for downloading and installing. +
Some hints follow, hope they help - but you are of course free to check out whatever you like.
- "Normal" users (normal means, you are an unique user who wants AsciiDoc3 work for your personal projects) may install local, ideally via https://pip.pypa.io/en/stable/[pip] and https://docs.python.org/3/library/venv.html[venv]. It's easy, works right out of the box and is safe (no interdependency with the system and you can delete the entire directory with one click!). Of course you need some knowledge about pip and venv, but this should be no problem at all. Or you use pip local without venv, that is almost the same.
- And, yes, if you are an experienced user, we recommend pip/venv, too. There are a lot of advantages, see the lines above.
- The system wide installing via tarball/deb/rpm is ok for the "long time" user who needs AsciiDoc3 every day and in different projects. Or you are an Admin and want to provide the software for all users.
- Windows users are strongly advised to install via pip/venv!
- Developers may take a look at the Git repo at https://gitlab.com/asciidoc3/asciidoc3[GitLab].
== Obtaining AsciiDoc3
You may download the files link:download.html[here]. +
The PyPI source is https://pypi.org/project/asciidoc3/[here], please visit the link:pypi.html[distinct page] before installing.
== Installation
.Unix, GNU/Linux, BSD, OS X
......@@ -28,59 +44,58 @@ This page covers GNU/Linux and other POSIX systems (Unix, BSD, and assumably OS
Windows users go link:windows.html[here], - except link:pypi.html[PyPI].
*********************
You have a bundle of options to install AsciiDoc3: +
- 'System wide' (you need su/sudo/admin rights): Tarball or deb/rpm-package. +
- 'Local' in your home directory, no admin rights required (if Python3 is already installed ...). Doing so, you have to use the 'python3 asciidoc3.py ...' syntax to execute AsciiDoc3.
- Experienced users may consider to run AsciiDoc3 via 'link:pypi.html[pip]' in a virtual environment created with link:https://docs.python.org/3/library/venv.html[venv]. +
=== System Wide (Tarball)
==== Install
- Download the tarball in any directory with read-write access, e.g. ~/download.
- Open a terminal and change to \~/download ('cd ~/download').
- Deflate the tarball to a new dir, say asciidoc3-3.1.0: 'tar -xzf asciidoc3-3.1.0.tar.gz'.
- You see a new directory ~/download/asciidoc3-3.1.0
- Recommended (but optional): Copy this new directory to your home directory
and rename it to something like ~/ad3 (so you have less typing labour ...).
- In the terminal: change to the new directory, e.g. ~/ad3.
- Run 'installscript' as root/superuser:
Ubuntu-like systems: 'sudo ./installscript' (don't forget the dot-slash)
Other POSIX os like Debian, Fedora, BSD: 'su <password> ./installscript' (don't forget the dot-slash)
- AsciiDoc3 is ready to use ... continue link:quickstart.html[here].
- 1. Create a new directory where AsciiDoc3 shall live in, say 'mkdir ~/ad3'
- 2. Download the tarball in any directory with read-write access, e.g. ~/Downloads.
- 3. Open a terminal and change to \~/Downloads ('cd ~/Downloads').
- 4. Deflate the tarball to the new dir: 'tar -xzf asciidoc3-3.2.0.tar.gz --directory ~/ad3'
- 5. Change to the new directory 'cd ~/ad3'.
- 6. You'll find the AsciiDoc3 files in ~/ad3. Run 'installscript' as root/superuser.
Ubuntu-like systems: 'sudo ./installscript' (don't forget the dot-slash);
other POSIX os like Debian, Fedora, BSD: 'su <password> ./installscript' (don't forget the dot-slash).
- 7. AsciiDoc3 is ready to use ... continue link:quickstart.html[here].
==== Update
If you want to install a newer version of AsciiDoc3, it is strongly recommended to uninstall first - see next section. This is to avoid the survival of any 'zombie file' belonging to the older version. +
In the next step just install the new version as described above. +
You may in an alternative way install the new tarball via installscript just over the previous version - the executable files like /usr/bin/asciidoc3 will be replaced as requested. Check this with 'asciidoc3 --version'. Take a look in your ~/asciidoc3 directory to keep a check on the new files - almost always everything's ok.
==== Uninstall
If you ran the AsciiDoc3 'installscript' as root/superuser - see above (that means, you have directories/files like /etc/asciidoc3/\*.* or /usr/share/asciidoc3/ et al.)
If you ran the AsciiDoc3 'installscript' as root/superuser - that means, you have
directories/files like /etc/asciidoc3/\*.* or /usr/share/asciidoc3/ et al.
(you have used 'asciidoc3 -a toc -a icons -n mytext.txt' or so): +
1. make uninstallscript executable: 'chmod u+x uninstallscript', +
2. 'su/sudo ./uninstallscript', +
3. delete your local files, e.g. in '~/asciidoc3'.
- 1. Backup your personal files.
- 2. Change to your AsciiDoc3 directory, say ad3: 'cd ~/ad3'
- 3 Make uninstallscript executable: 'chmod u+x uninstallscript'
- 4. 'su/sudo ./uninstallscript'
- 5. Uninstallscript removes the files in /etc and /usr, but does not know anything about your local directory layout, so you have to delete your local files manually:
- 6. 'rm ~/ad3'
=== Local (Tarball)
You may use the tarball to install 'local' without having superuser rights. Precondition is of course, Python is already installed (and also the other software like dblatex, FOP, highlighter, ...).
==== Install
- Download the tarball in any directory with read-write access, e.g. ~/download.
- Open a terminal and change to \~/download (cd ~/download).
- Deflate the tarball to a new dir, say asciidoc3-3.1.0: 'tar -xzf asciidoc3-3.1.0.tar.gz'
- You see a new directory ~/download/asciidoc3-3.1.0
- Optional: Copy this directory and rename it to ~/ad3 (so you have less typing labour ...)
- In the terminal: change to the new directory, e.g. ~/ad3.
- Start using AsciiDoc3 by using 'python3 asciidoc3.py -a toc -a icons -n doc/test.txt' ... continue link:quickstart.html[here].
- 1. Steps 1. - 5. like above section 'System Wide (Tarball) -> Install'.
- ...
- 6. Do not run 'installscript' (you may delete this file and 'uninstallscript', too)
- 7. Yes, it's already done, please fasten seat belts and start:
- 8. 'python3 asciidoc3.py -a toc -a icons -n doc/test.txt'. From now on you have to replace 'asciidoc3' / 'a2x3' by 'python3 asciidoc3.py' and 'python3 a2x3.py' ... continue link:quickstart.html[here].
==== Uninstall
To uninstall 'local' as described before makes it easy to uninstall: just delete ~/ad3. Do not forget to backup your private data.
==== Update
If you like to install a newer version of AsciiDoc3, it is recommended to uninstall first - see next section. Or you install in another directory, so you'll have two different versions of AsciiDoc3.
If you have AsciiDoc3 installed local - that means, you have all files in one
directory (e.g., \~/asciidoc3) and never ran 'installscript'
(you have used 'python3 asciidoc3.py -a toc -a icons -n mytext.txt' or so):
just delete the directory '~/asciidoc3' (or wherever you have installed the distribution).
==== Uninstall
To uninstall 'local' as described before makes it easy to uninstall: just delete ~/ad3. Do not forget to backup your private data.
=== Debian-like Systems
......@@ -92,10 +107,16 @@ just delete the directory '~/asciidoc3' (or wherever you have installed the dist
- You see a new directory ~/asciidoc3.
- If this directory already exists the old directory is saved to ~/asciidoc3_<random_number>.
- You may also use tools like 'GDebi' or so to install the downloaded file asciidoc3.deb (rightclick in your FileManager).
- You may also use tools like 'GDebi' to install the downloaded file asciidoc3.deb (rightclick in your filemanager).
==== Update
If you want to go the 'safety first' way, uninstall the previous version - see section below. Do not forget to backup your personal files. +
But uninstalling is not really necessary, you may just 'apt install ./asciidoc3.deb' - with the new version, of course. apt will backup the former directory ./asciidoc3 to ./asciidoc3_<random_number>. You can ignore the message here and there 'ln was not able to symlink, because the file already exists'. +
To verify update installation type 'asciidoc3 --version'
==== Uninstall
To uninstall open a terminal, change to root and 'apt remove asciidoc3' or 'sudo apt remove asciidoc3'. You can use the well-known graphical interfaces, too. +
To uninstall open a terminal, change to root (su/sudo) and run 'apt remove asciidoc3'. You can use the well-known graphical interfaces, too. +
[TIP]
Please keep in mind, that the folder ~/asciidoc3 will *not* be removed. Do that by yourself to make everything gone. Do not forget to backup your private data.
......@@ -111,7 +132,13 @@ Please keep in mind, that the folder ~/asciidoc3 will *not* be removed. Do that
- There is a new directory ~/asciidoc3.
- If this directory already exists the old directory is saved to ~/asciidoc3_<random_number>.
- You may also use tools like 'yast' or so to install the downloaded file asciidoc3-3.1.0-2.noarch.rpm (rightclick in your FileManager).
- You may also use tools like 'yast' or so to install the downloaded file asciidoc3-3.1.0-2.noarch.rpm (rightclick in your filemanager).
==== Update
If you want to go the 'safety first' way, uninstall the previous version - see section below. Do not forget to backup your personal files. +
But uninstalling is not really necessary, you may just 'rpm --install ./asciidoc3-3.2.0-noarch.rpm' - with the new version, of course.
This will backup the former directory ./asciidoc3 to ./sciidoc3_<random_number>. +
To verify update installation type 'asciidoc3 --version'
==== Uninstall
......@@ -127,7 +154,7 @@ Please keep in mind, that the folder ~/asciidoc3 will *not* be removed. Do that