= AsciiDoc3 Quickstart


////////////////
// The links given in the next section point to https://asciidoc3.org
// So the link:install.html[here] means https://asciidoc3.org/install.html
////////////////


== Start with AsciiDoc3
- You don't need admin/root-access to run a complete AsciiDoc3 - install 'local' via venv/pip or the GitLab zip/tar.gz files
 (even without having git installed on your machine), see link:install.html[here]. 
- Download the tarball / zip-file of the current AsciiDoc3 distribution, see link:download.html[here].
- Deflate the tarball / zip-file in an appropriate directory, see link:install.html[here].
- Be sure 'python3' is in your PATH and starts Python3, see link:install.html[here].
- To uninstall, see link:install.html[here].


[NOTE]
Experienced AsciiDoc (Python2) users please note: +
The use of a file named 'asciidoc.conf' is not allowed in AsciiDoc3 - a file with this name will be ignored! +
Use 'asciidoc3.conf' instead.


== Testing your installation
In your new directory, e.g. 'asciidoc3', you'll find the following input files: +
- ./doc/test.txt: a small doc to see everything's ok (-> asciidoc3.py works ...), +
- ./doc/userguide.txt: this is nothing else than the 'AsciiDoc3' - User Guide.


=== First Test

Open a terminal, go to your directory and start

------------
$ cd ~/asciidoc3-3.0.1/doc

$ python3 ../asciidoc3.py -n -a icons -a toc -o test.html test.txt
------------

or, when you have installed AsciiDoc3 system wide (su ./installscript) 

------------
$ asciidoc3 -n -a icons -a toc -o test.html test.txt
------------

You'll find a new file test.html. It shows only a few features of AsciiDoc3. 

=== UserGuide

Open a terminal, go to your directory and start

------------
$ cd ~/asciidoc3-3.0.1/doc

$ python3 ../asciidoc3.py -a toc -n -a icons -o userguide.html userguide.txt
------------

or 

------------
$ asciidoc3 -a toc -n -a icons -o userguide.html userguide.txt
------------

The new file 'userguide.html' contains the current version of the user guide, find it online https://asciidoc3.org/userguide.html[here]. Processing 'userguide.txt' makes use of many AsciiDoc3-features. 

To make a "good-looking" pdf out of userguide.txt, try

------------
$ a2x3 -f pdf userguide.txt
------------

or

------------
$ python3 ../a2x3.py -f pdf userguide.txt
------------

To make an even better(?) looking pdf, you may use option 'fop' - this requires that you have installed 'fop'.

------------
$ a2x3 -f pdf --fop userguide.txt
------------

or

------------
$ python3 ../a2x3.py -f pdf --fop userguide.txt
------------


=== Verbose Option

To see what is going on when asciidoc3.py or a2x3.py works, add the option 'verbose':

------------
$ asciidoc3 -v -n -a icons -o test.html test.txt

$ a2x3 -f pdf -v --fop userguide.txt
------------



== More Examples and Further Information

In the directory /home/user/asciidoc3_dir/doc you find some more files you may use as examples to study the features of AsciiDoc3. +
Even more files and examples are provided here: /home/user/asciidoc3_dir/tests/data
