Re: Translation of the Org mode manual (was: Translation of manuals (was: SES manual French translation))

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

> 1. Org mode manual itself, just like the other Emacs manuals may need to
>   be translated. However, Org mode manual source is written in Org mode
>   format, not texi. It is just transformed to texi as one of the export
>   options.

Using Org format for the source of a document, and converting it to
texi for processing (for instance, through TeX) would be a fine method
to use, if it worked.  But it doesn't actually work.

The problem is that it cannot work, given Org format as it exists now.
It cannot properly represent manuals that use the GNU standard style
because it does not have ways to represent all the distinctions that
are needed.

Texinfo implements semantic markup, and is designed for multiple
output formats, including Info, HTML, and DVI (whence also PDF).  Two
different markup constructs that look the same in one output format
may look different in another.  All these design decisions were the
result of long thought.

For instance, italic face can be the result of @dfn, @var, @emph,
@cite and @i.  Each of them has a meaning -- which one to use is not a
matter of taste.

@cite is used around the title of a book.
@dfn is used around the first use of a term, to say it is being defined.
@emph is used to indicate emphasis.
@var is used around a metasyntactic variable.

@i means "use italic for this" and does not say why.  It is a escape
for situations that Texinfo has no specific way to describe.

These five commands produce the same output in DVI/PDF, but different
output in Info.

I think there must be 15 different Texinfo commands to generate
fixed-width bold text in DVI/PDF.

To represent a manual source in Org format and do the job right is not
possible with Org format as it is now.  To make it possible requires
extending Org format so it can make all the distinctions Texinfo can
make.

I would like Org format to be extended in this way.

Texinfo format is often misunderstood.  People write GNU manuals
without knowing of all these constructs, so they use the wrong
construct.  If Org format were extended to do _the whole job_, we
could convert all manuals to Org format once and for all.

A few years ago I raised this idea, but nobody wanted to work on it.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)