Re: Using Org as the source format to generate org.texi

[Nicolas Goaziou]

Hello,

Richard Stallman <address@hidden> writes:

> Texinfo has a number of overlapping constructs that look
> the same in certain output formats but different in others.
> Does Org have constructs 100% equivalent to
> @dfn, @emph, @strong, @code, @samp, @var, @kbd, @key?

Org has lightweight markup for @emph, @strong, @code and @samp out of
the box: /emph/, *strong*, ~code~ and =samp=.

@var, @kbd and @key are defined, in "org-manual.org", through
a one-liner mechanism called a macro. There, @var{foo} becomes
{{{var(foo)}}} and @address@hidden becomes {{{kbd(M-RET)}}} (the
"@key" part is automatically deduced from the contents of the macro).

However, "org-manual.org" doesn't define "@dfn" because it doesn't need
it. But if it did, it could use a {{{dfn(...)}}} macro as above.

> If not, would people like to add them?

At one point, I suggested to make the "kbd" macro readily available for
every export back-end. As such, the would be no need to define it in
each document making use of it. However there was little interest in the
Org ML. Also, there are some decisions to make. For example, the macro
needs to be useful in every format supported by Org, and there are
multiple ways to transcribe @address@hidden in LaTeX parlance. It is not clear
which one we should use and how configurable it should be.

I'm not sure about @dfn. Org has a lightweight markup, i.e., _this_,
which mean "underline" by default. Since it is ignored in the Texinfo
export back-end, we might use it for @dfn. It probably would not be
shocking if the term appeared as underlined in other formats.

Note that this is all for default Texinfo back-end, which needs to be,
as much as possible, compatible with other export back-ends (LaTeX,
ASCII, HTML, ODT...). However, there is always the possibility to write
another, dedicated, Texinfo back-end for Emacs manuals. This one could
ignore compatibility altogether and use more specific constructs. This
is, AFAIK, what the maintainer of Magit did for its manual. This could
be discussed with people that actually write or maintain Emacs manuals.

Regards,

-- 
Nicolas Goaziou                                                0x80A93738