Documentation format

[Sam Pablo Kuper]

On 06/02/16 12:08, Robert J. Hansen wrote:
> Since I seem to have become the doyen of documentation, I figure I
> should ask: what markup language and/or output formats should we be
> pursuing for future documentation work?

Thanks for working on the documentation :)

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

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

However, if you dismiss it because you personally don't like it, it
might be helpful for you to at least state your objections to it.

> I'm a big fan of LaTeX and PDF output.  With a good layout package (like
> Tufte-Latex) you can get astonishing print quality and
> professional-looking layout.  However, this comes at the expense of good
> HTML support.  You'd have a hard time reading these docs on mobile
> devices, or at a text-only terminal that had no PDF reader.

Why not use LaTeX export for Org-mode, and get the best of both worlds?

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

As for other formats that *do* begin life as human-readable plain-text
files (e.g. ReStructuredText, Groff, CommonMark, etc.), they all share
the same problem as Texinfo. See above.

I vote for Org:

- GnuPG's lead developer likes Org & is, I would guess, more likely to
engage with the documentation if it is in Org.

- Org text is very human-readable in any decent text editor.

- Org has flexible output into LaTeX, HTML and ODT formats, among
others: http://orgmode.org/manual/Export-back_002dends.html .

- Org maintains consistency with the existing docs.


Thanks again :)

- spk

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 473 bytes
Desc: OpenPGP digital signature
URL: </pipermail/attachments/20160206/23d6543a/attachment.sig>