Documentation format

[Sam Pablo Kuper]

On 06/02/16 21:11, Robert J. Hansen wrote:
>> 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.

Thanks for clarifying. I wasn't aware of these issues.

> (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.)

Do you happen to have links to the relevant bug reports, or other
documentation of the issues?

Also, have you explored alternative pipelines from Org-mode to PDF?
Maybe via ODT or Markdown, etc?

>>> [Texinfo] produces
>>> high-quality print output.  It actually looks like a book when you print
>>> it off. [...]
> 
> I don't like the way Texinfo looks on the page.  It has a very 1970s
> textbook feel to it.

Hm, you think it produces high-quality print output, but you don't like
the way it looks on the page. Not a *direct* contradiction, maybe... ;)

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.

I take your point here, but I'd suggest it isn't a priority. People come
to GnuPG for the cryptography, not the typography.

So, Texinfo still seems a reasonable candidate.

>>> 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"?  :)

I've spent enough time hand-editing XML documents in text editors and
specialised XML editors that I've come to regard many XML languages as
not significantly more human-readable than binaries. Compared to Org,
ReST CommonMark, MediaWiki mark-up, etc, they require much more mental
overhead and/or editor configuration.

Getting clean plain-text diffs from these languages, including from
OpenDocument Text, can be a pain, which complicates revision control.

Support for editing documents like this in non-graphical free software
environments was poor, last time I checked.

It's up to you, of course - and maybe you like that sort of thing - but
I would generally encourage you not to inflict this upon yourself, let
alone anyone else :)

Thanks again,

- spk