Lacking Natural Simplicity (Posts about asciidoc)https://tkurtbond.github.io/categories/asciidoc.atom2024-01-23T18:49:34ZT. Kurt BondNikolaPlain Text Markuphttps://tkurtbond.github.io/posts/2008/07/08/plain-text-markup/2008-07-08T17:39:48-05:002008-07-08T17:39:48-05:00T. Kurt Bond<aside class="admonition note">
<p class="admonition-title">Note</p>
<p>This is unfinished.</p>
</aside>
<p>I still like plain text. Almost <em>none</em> of the e-mail that I get that
uses HTML formatting actually gains anything from the additional
complexity.</p>
<p>Most of my writing doesn't require a 200 mebibyte word processor
installation that still can't do reasonable <em>intra</em>-document linking,
much less <em>inter</em>-document linking. Moreover, whenever I have to use
such a beast, the conceptual overhead always gets in the way. I
realize these may just be my own quirks, but they really make a
difference to me.</p>
<p>So, I like to do my writing in plain (or very nearly plain) text. But
I also like having nicely printed documents, plus some hope of being
able to move from the plain text documents to something more
sophisticated on those occasions where it is warranted. So, what do I
do?</p>
<p>I use <a class="reference external" href="http://www.methods.co.nz/asciidoc/">AsciiDoc</a> and <a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> (aka ReST) for writing.</p>
<p>Why both? Well, they both have pluses and minuses.</p>
<section id="restructuredtext">
<h2>reStructuredText</h2>
<p>Pros: I found reStructuredText first. It looks pretty good as plain
text, and produces clean HTML and PDF. It can handle deeper
structures off the bat than AsciiDoc, which is occasionally important
to me. (Some document formats require absurdly deep levels of nested
sections.) It can be turned into PDF using LaTeX fairly easily.</p>
<p>Cons: some of the systems I use regularly don't have good packages for
<a class="reference external" href="http://docutils.sourceforge.net/">docutils</a>, the underlying toolset. This may be in part because
although docutils has a long history and is pretty solid, it's still
not considered version 1.0 material. I get the surface impression
that there are still some things that the developers are thinking
about. And there isn't a supported <a class="reference external" href="https://tkurtbond.github.io/posts/2008/07/08/docbook/">DocBook</a> output format. That's a
real shame.</p>
</section>
<section id="asciidoc">
<h2>AsciiDoc</h2>
<p>Pros: AsciiDoc, just like reStructuredText, can go straight to HTML.
And AsciiDoc's HTML looks nicer straight out of the box.</p>
<p>AsciiDoc is also explicitly a plain-text encoding of DocBook. This
lets you be sure you can convert it to something widely used and well
understood, which can then be converted by well-known tools into
various other formats including PDF and HTML.</p>
<p>It has better package support amongst the environments I use.</p>
<p>Cons: not as pretty looking in source form as reStructuredText.</p>
</section>
<section id="conclusions">
<h2>Conclusions</h2>
<p>I wish it was easier to add special purpose structure to both AsciiDoc
and reStructuredText that can easily added to all the output formats,
for special purpose things like RPG stats or other complicated
technical documentation.</p>
<p>So, what do I do when I need something more sophisticated? Use
<a class="reference external" href="https://tkurtbond.github.io/posts/2008/07/08/docbook/">DocBook</a>, of course.</p>
</section>