Re: Org mode and Emacs

[Ihor Radchenko <yantar92@posteo.net>]

Philip Kaludercic <philipk@posteo.net> writes:

>> If a .texi expert can report such flaws in the Org manual, we can then
>> fix them and, if needed, implement the necessary constructs.
>
> I don't know if this is of any use, but the initial manual for Compat
> (https://elpa.gnu.org/packages/compat.html) was written using Org and
> ox-texinfo and I later switched to writing .texi directly.  This commit
> here documents the switch that includes a partial rewrite.
>
> https://git.sr.ht/~pkal/compat/commit/dd48603a136881a5321de4419be95ea873496172
>
> Some things here might be difficult to map, such as the proper usage of
> reference macros or the different kinds of markup from (texinfo) Indicating.

ox-texinfo certainly misses some specialalized Texinfo syntax, like
@defn, @var, etc:

doc/Documentation_Standards.org:

   + Texinfo commands such as @var and @defoption are not used.  The
     preference for this type of thing is that the user browses the
     customize groups.  If you want or need to refer to, say, a
     variable then document it as "the variable
     @code{org-startup-folded}"

It is not export backend fault per se - Org markup simply does not
define specialized markups more granular than ~code~.
So, users have to use macros like {{{kbd(C-c SPC)}}} that expands to
direct texinfo export snippet @@texinfo:@kbd{@@C-c SPC@@texinfo:}@@

Though we do not provide similar macros for @var/@env/etc. We might.
Or we might allow custom inline special markup as I suggested in
https://orgmode.org/list/87bkqx4jyg.fsf@localhost

Another limitation, I can see in the commit is using @xref, which Org
does not do. ox-texinfo now transforms <info:#node> links into @ref
only.

On the other hand, Org provides a powerful citation syntax
[cite:see @citation-key], which may be also utilized if we support
info files as bibliography source. This will be a superset of what
@xref/@ref/@pxref does as cite/variant is an equivalent of \autocite in
LaTeX.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>