Add the command line used to create the HTML

[brentfraser]

What is the asciidoc command line used to produce the HTML version of the Reference Manual? We may want to include that as a file in this repo.

[moovida]

It is not exactly simple, but we can find the best way. It would indeed be good if someone could provide also the compiled update, that way it could be merged even while travelling.

The command I use is:

asciidoctor -r asciidoctor-diagram -r $ASCIIDOCTOR_FOLDER/asciidoctor-extensions-lab/lib/tree-block-macro.rb

with ASCIIDOCTOR_FOLDER being the folder I keep the installation in.

The installation requires some extension:

• asciidoctor-diagram
• tree-block-macro.rb

[brentfraser]

To those interested in contributing to the Geopaparazzi doc, AsciiDoc is the format of the .adoc files, but asciidoctor is used to convert the .adoc files to .html (and .pdf?). While you can simply use a text editor to edit the .adoc files, to see the results in html you need to run them through asciidoctor.

I installed and ran asciidoctor on Windows by:

1. Install Ruby with the RubyInstaller (https://rubyinstaller.org/)

2. From the Windows Start Menu: Ruby -> "Command prompt with Ruby"

3. On the command line: gem install asciidoctor gem install asciidoctor-diagram asciidoctor --version

4. On the command line change dir to your location of Geopaparazzi's userguide index.adoc and run asciidoctor:

   asciidoctor -r asciidoctor-diagram index.adoc

This will create index.html in the same directory.

[brentfraser]

Oh, and also install coderay:

gem install coderay

[brentfraser]

The sections on "A small handbook for developers" (development.adoc) and the Appendix require additional s/w (plantUML/Graphviz) to render diagrams.

[brentfraser]

Rendering Folders in development.adoc:

To get the two folder blocks ("Contents of the Geopaparazzi git root folder", "Contents of plugins folder") in development.adoc to render properly, you need to:

• install tree-block-macro.rb: Create a folder called "asciidoctor-extensions-lab" somewhere (under your Ruby folder is good), and copy the file from https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/tree-block-macro.rb. Also create a sub-folder in the new folder above called "tree-block-macro" and copy the file from https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/tree-block-macro/extension.rb

• point to your Geopaparazzi code folder: edit the the two lines in development.adoc starting with "tree::" to reference your Geopaparazzi code folder. For example: tree::/Android/geopaparazzi/[maxdepth=1]

• render the doc with: asciidoctor -r asciidoctor-diagram -r C:\programs\Ruby25-x64\asciidoctor-extensions-lab\lib\tree-block-macro.rb index.adoc

For some reason it will render properly from the command line, but not in the AsciidocFX editor. And on Windows it shows the hidden files and folders.