Documentation format

[Werner Koch]

On Sat,  6 Feb 2016 22:11, rjh at sixdemonbag.org said:

> 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

I don't have any problems creating PDF via Latex from org-mode.  As a
German I use non-ASCII quite often and it just works.  Depending on your
TeX distribution you may run in some problems with some UTF-8 characters
but M-x org-entity-help shows you the entities you can use to avoid
these problems.

If you notice problems with some characters, please add a fixme and
briefly mention this in the commit log and I will go and fix it.

> 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

I would actually like to drop Texinfo in favor of org-mode but there are
two problems:

 - There is no replacement for @deftypefun and I had no success to
   emulate this with macros.

 - There is no support indices in org-mode yet.

> Open Document is just XML, so it meets your requirement of a

XML is for machines and not for humans.  We used to use Docbook in the
90ies but it was too hard to properly render it to get an output similar
in quality to a TeX based document.  A proper SGML DTD would have been
okay for writing documents.  With the stripped down XML version of
Docbook you spend most of your time fixing the markup and rendering.


Shalom-Salam,

   Werner



p.s.
re. Markdown: There is no proper syntax and using the common comment
character to indicate headers is at best a joke.

-- 
Die Gedanken sind frei.  Ausnahmen regelt ein Bundesgesetz.