Documentation format

[Robert J. Hansen]

I should preface this by saying that I'm not advocating we move away
from org-mode.  I don't have any aims in that direction.  I really
dislike org-mode's print output, but that's (IMO) insufficient reason to
throw the entire thing out.

I *do* think, though, that exploring other options is a good idea.  :)

>> The FAQ is currently written up in orgmode, which Werner is fond of.
>> What you see on the web is orgmode-text put through an HTML translator.
>>  But, it also produces lousy print output.
> 
> Please can you expand on what you mean by saying that Org "produces
> lousy print output"?

My big annoyance comes from how org-mode silently mangles i18n.  The FAQ
uses UTF-8 encoding so that we can do the Right Thing with respect to
languages.  Right now we only rely on it in two places (presenting the
Greek roots of the word 'cryptography'), but I can easily imagine it in
more; for instance, if I have to credit a GnuPG-Users contributor named
Aßman, or talk about Merkle-Damgård hash functions, or Vigenère ciphers,
or... etc.  Crypto is a truly international field, and so we need to
expect/prepare for internationalized text.

When org-mode exports to LaTeX, most internationalized text falls out
and goes boom.  The Greek that's currently in the FAQ gets silently
dropped, for instance.  This *really really annoys me*, because it means
that after I've done a detail read of the HTML version of the FAQ
looking for errors I now have to do a detail read of the print version
looking for errors introduced by org-mode's export filter.

(For the record: yes, I know why org-mode has trouble with i18n export
to LaTeX.  Yes, it's a hard problem.  Yes, fixing it might not be worth
the effort.  All of this is true.  None of it changes how annoyed I am
by the bug, though.)

>> The FSF is really fond of their own standard, texinfo, which they prefer
>> to be used for hardcopy and online documentation.  I personally don't
>> like texinfo; some people really like it.  In its favor, it produces
>> high-quality print output.  It actually looks like a book when you print
>> it off.
> 
> I'm not aware of any objections to Texinfo, except that it would mean
> switching away from Org. That could create hostages to fortune: people
> wanting to maintain GnuPG documentation in the future having to learn
> both mark-up formats; lack of clarity about which format they should use
> going forward, etc. If you dismiss Texinfo on that basis, fair enough.

I don't like the way Texinfo looks on the page.  It has a very 1970s
textbook feel to it.  It's also deeply married to very specific font
families, and I think we can do a lot better.  The world has mostly
abandoned Computer Modern Roman, even Knuth -- he's moved on to his
Concrete font family, for the most part.

>> Another option: Open Document.  For obvious reasons we can't choose
>> Microsoft Word, but there are no liberty-related reasons to avoid Open
>> Document.
> 
> Please don't pick a format whose documents do not begin life as
> human-readable plain-text files. That rules out DocBook, too.

Open Document is just XML, so it meets your requirement of a
human-readable plain text file.  Or do you really mean, "I don't like
XML, so please don't use an XML-based standard"?  :)