-
Notifications
You must be signed in to change notification settings - Fork 1
AsciiDoc love hate
When I first wrote this page, where I first linked to it, I said:
- AsciiDoc is supposedly the RISC-V standard documentation forward going forward. And rather snarkily I added
- Too bad.
(As of 5/15 I still say that.) (Still bitching 6/17.)
Let me be fair: every tech pubs system has problems. AsciiDoc is better than many of the alternatives. But still, it frustrates me. And I am rather sick and tired of a proliferation of different tech pubs and markup languages, all of which are slightly different, none of which have all the features I want in one place.
AsciiDoc can create large documents, better than various wiki oriented markup languages like Markdown.
See separate page.
AsciiDoc blocks are delimited by things like ***.
The same delimiter is used to open and close a block.
It is very annoying when you accidentally mismatch - the rest of the document is rendered out-of-phase.
Syntaxes that have matching open and close delimiters of opposite polarity catch such errors.
One of the most general such is XML's ... but asciidoc considers that too verbose.
still, something like '' ... '/' or ".****" might help.
Provide both, for those who do not care about efficient errors...
The example below does not work, taken from https://asciidoctor.org/docs/user-manual/#discrete-headings
(this is probably just cygwin having an old version of asciidoctor. recording nevertheless for me to verify in future.)
Discrete headings are useful for making headings inside of other blocks, like this sidebar.
[discrete] == Discrete Heading
Discrete headings can be used where sections are not permitted.
Although GitHub's wiki allows wiki pages to be written in AsciiDoc as well as several other formats of markup like Markdown, AsciiDoc is the ugliest and clumsiness of those flavors.
AsciiDoc link syntax is obviously designed primarily for links inside the current document or page: <>. GOOD, this is reasonably compact.
https://asciidoctor.org/docs/user-manual/#customizing-the-cross-reference-text
[reftext="Installation Procedure"] === Installation
takes an internal cross reference <> and expands it to "Installation Procedure:.
This is good - better than the standard wiki practice of having alternate text at the use site, but only at the use site.
With ascii doc you can use the original text, eg the section name, overriode at the user site, or have a standard expansion distinct from the section name
AsciiDoc indented list syntax is
* H1
** H2
*** H3
i.e. numbers of *s is heading level.
Compare to MarkDown's use of indentation
* H1
* H2
* H3
although at least AsciiDoc tolerates such indentation
* H1
** H2
*** H3
Still, I hate having to count asterisks.
The standard answer the problems in AsciiDoc is to add a blank line. E.g. a blank line between a sentence fronting a list:
sentence
* item1
* item2
rather than note
sentence
* item1
* item2
which latter is
sentence
- item1
- item2
(Although I do wish there was a space between the sentence and the beginning of a list, but that's an output formatting, and is often just the property of the HTML browser or CSS.)
Many, many wikis use double square brackets to create a [[link]] to create a link whose page is derived from the link text - either exactly, or by a simple transformation such as blanks->_ or -, URL encoding, etc.
AsciiDoc does not seem to have any such compact link format
AsciiDoc uses double square brackets to define [[target-anchor]],
so there would need to be some other syntax.
AsciiDoc uses double angle brackets for <<link>>. But these links are cross reference only, in the same document.
GitHub Flavored Markdown (GFM) does not officially support the double square bracket syntax, per specs that I have been able to find, but on the actual github wiki it is supported. Unfortunately, the cramdown tool that converts GFM to AsciiDoc does not understand double square bracket links.
Per https://asciidoctor.org/docs/user-manual/#conditional-preprocessor-directives AsciiDoctor supports preprocessor directives ifdef/ifndef/ifeval. But not else or elsif.
Nuff said. Shortsighted idiots.
I like using Dewey decimal section numbering, to help me understand structure my document. Sure, tech writers say that should not have any more than 3 or 4 levels of sections in a release document, but while you are refactoring ...
Because of this I feel compelled to flatten a logical tree structure to avoid overly deep sections.