Using AsciiDoc instead of Asciidoctor to generate HTML documentation#1133
Conversation
The asciidoc command does not support certain syntax that is supported by asciidoctor command. Fortunately, we can use syntax that is compatible with both programs. Most notable changes are: - Do not use triple backquotes for monospaced text, use single backquotes that work in both programs. - Use ---- for source code listing everywhere because they are rendered differently in asciidoc than indented blocks, whereas in asciidoctor they looked the same as indented blocks. - Use explicit wrapping in source code listing because asciidoc doesn't wrap long lines implicitly in source code listings, which causes ugly overlows and extremely long lines that are hard to read. - Fix SSG link.
Asciidoc could be used instead of asciidoctor. Changed the command line to be compatible with both programs. Explicitely set the HTML5 backend because it is not default in asciidoc. We have to make the target directory before we call the program, because asciidoc doesn't create directories automatically. If both asciidoc and asciidoctor are found, asciidoc is preferred.
Codecov Report
@@ Coverage Diff @@
## master #1133 +/- ##
==========================================
- Coverage 63.98% 63.97% -0.01%
==========================================
Files 278 278
Lines 46247 46247
==========================================
- Hits 29589 29588 -1
- Misses 16658 16659 +1
Continue to review full report at Codecov.
|
|
I am going to change this PR to use only asciidoc, not asciidoctor. |
This will remove the possiblity of using asciidoctor in `make docs` build target. We will support only asciidoc, beacuse that command is available in many Linux distributions. Removed also a mention of asciidoctor from the Developer Manual.
jan-cerny
changed the title
|
I have updated the PR to use only |
|
These changes look good. :) I verified that all the code blocks look like code blocks, that it builds fine with asciidoc installed and that the new files look fine. One question: On line 71 of the changed file you add a I'm ACK-ing it anyways as the output file looks good, which is what matters. :P -- Alex |
|
@cipherboy That is a "List Item Continuation". That allows you to put a larger block as a list item which is well indented. See section 17.7 here: http://www.methods.co.nz/asciidoc/chunked/ch17.html |
|
Ahhh okie! :) (I missed that link the first time). Looks good then, thanks for your changes! :) ACK |
2 participants
We need to be able to generate HTML documentation using Asciidoc instead of Asciidoctor, because on some systems Asciidoctor is not available.
The asciidoc command does not support certain syntax that is
supported by asciidoctor command. Fortunately, we can use syntax
that is compatible with both programs. Most notable changes are:
backquotes that work in both programs.
are rendered differently in asciidoc than indented blocks,
whereas in asciidoctor they looked the same as indented blocks.
doesn't wrap long lines implicitly in source code listings,
which causes ugly overlows and extremely long lines that are
hard to read.
Then, we need to change CMakeLists to be able to use asciidoc.
Explicitely set the HTML5 backend because it is not default in asciidoc.
We have to make the target directory before we call the program,
because asciidoc doesn't create directories automatically.
Finally, we removed the mention of
asciidoctorfrom Developers Manual and provided instructions to installasciidoc.