Digest #129 2020-12-29
Contributions
example - Should this reference the optional word sets where SOURCE-ID is changed
SOURCE-ID is changed by the optional FILES word set, a forward reference would be useful in that case i.e. if I was reading this definition on a system where the FILES word set was present, I would see a number other than -1 or 0 in SOURCE-ID and think the system was not compliant with the standard.
Should this make clear its relationship to the BLOCK word set i.e. if BLK is set, then should SOURCE return a caddr and length of the block, or should a user test BLK before calling SOURCE ?
Replies
proposal - XML Forth Standard - migration from LaTeX to DocBook
how to render (...) (that is shown as colon-sys<sup>1).
Asciidoctor source:
[.par]_colon-sys^1^_
By the way, the double (called unconstrained) underscores I used in my previous message were unnecessary. I used them because the parameter had an inner underscore, but the parsing works fine with ordinary single underscores to mark the emphasis.
Result in DocBook:
\<emphasis\><phrase role="par">colon-sys\<superscript\>1</superscript></phrase></emphasis>
In fact you can ommit the [.par] role, which is added only to identify the parameters in order to change their style.
nesting of different blocks,
You can have nested blocks by adjusting the length of their delimiters by a pair of extra characters. Example:
====
This is an example block.
====
****
This is a sidebar block.
****
====
This is an example block with a nested...
======
...example block.
======
====
Result in DocBook:
\<title\>Nested blocks</title>
\<informalexample\>
\<simpara\>This is an example block.</simpara>
</informalexample>
\<sidebar\>
\<simpara\>This is a sidebar block.</simpara>
</sidebar>
\<informalexample\>
\<simpara\>This is an example block with a nested…​</simpara>
\<informalexample\>
\<simpara\>…​example block.</simpara>
</informalexample>
</informalexample>
using indentation in the sources
Not sure what you mean, but indentation is parsed as a type of block:
----
This is a source code or keyboard input block.
----
....
This is an output text block.
....
This is an output text block as well.
Result in DocBook:
\<title\>Indentation</title>
\<screen\>This is a source code or keyboard input block.</screen>
<literallayout class="monospaced">This is an output text block.</literallayout>
<literallayout class="monospaced">This is an output text block as well.</literallayout>
I don't use indented blocks. I prefer explicit markup for clarity.
support of folding in text editors
I use Neovim and Vim, and I fold the Asciidoctor headings using the default folding marks of the editor. Unfortunately Asciidoctor doesn't allow comments at the end of a line, so I have to add a line comment above each heading, repeating the title in order to see it when the section is folded:
// My second-level heading {{{1
== My second-level heading
// My third-level heading {{{2
=== My third-level heading
In theory I could configure the editor to fold by other criteria, including the indentation of the source itself, but I don't need it and didn't try.
An XML editor can fold at any tag, I suppose. The nature of the markup makes it easy.
To me, XML for this purpose looks better than AsciiDoc. But my view perhaps is biased, since I use XML a lot, and never AsciiDoc (except sometimes Markdown that is similar to AsciiDoc).
Of course. XML provides powerful transformation capabilities and other advanced features, using specialized programs. With AsciiDoc you can obtain an equivalent result, with some limitations, but with a much simpler toolchain, and writting the documents easily with any text editor. I mentioned this alternative just in case. If you already use XML a lot and know it well, it seems the way to go.
proposal - XML Forth Standard - migration from LaTeX to DocBook
Actually the _1 is supposed to be a subscript, I got it wrong when I wrote the LaTeX to HTML translator. _1 should come out as <sub>1 _10 would translate as <sub>10 _{10} would translate as <sub>10 In LaTeX ^ is for superscripts.