Re: Org mode and Emacs (was: Convert README.org to plain text README while installing package)

[Ihor Radchenko <yantar92@gmail.com>]

I am CCing Org ML from now signifying that this branch of the thread is
directly relevent to Org mode and might be of interest for other Org
contributors.

Richard Stallman <rms@gnu.org> writes:

>   > So, now we have our manual written in Org mode and we never had reasons
>   > to come back to texi.
>
> I suspect that it doesn't fully follow the markup conventions
> for GNU manuals.  That's because we designed Texinfo to have markup commands
> to make all the proper semantic distinctions.  If the manual source
> is written in a language which doesn't have the full gamut of markup
> distinctions, there is no way to do the markup correctly.
>
> It would be useful for someone who understands these conventions
> to check the Org manual and see.

Yes, it would certainly help!
The work on manual has been done a long time ago and we also extended
our texinfo exported to suit the manual at that time. Assumingly, just
enough to handle the Org manual use-cases.

Note that we have doc/Documentation_Standards.org explaining some of the
conventions.

Here is a possibly relevant note inside it:

 - Only two of the standard Texinfo indexes are used; those for
   concepts and keys.  This has some implications:

   + The preference is to document commands by key rather than by name

   + 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}"
 
   + Entries in the concept index are normally all lower case unless
     some other rule dictates otherwise.

Without knowing texinfo, the above paragraphs do not make a whole lot of
sense for me. So, if someone points out any omissions, it would be
helpful for future Org contributors.

> I don't think the slowness of processing nowadays is the crucial issue
> here.  Computers are much faster now than in the 1990s.  It used
> to take a long time for TeX to process the Emacs Lisp Reference Manual.
> Now it is perhaps 10 times as fast.

Generally, there is no way Org export to .info gets any faster than
texinfo. Org is only able to export to other text formats: org->texi;
org->tex; org->html; etc. Convertion to more low-level formats is left
to the external tools like texinfo and pdflatex.

As for reports on the slow performance, they are still useful as long as
they reveal some bottlenecks in Org exporter. Org is being used to
export large documents and whole websites. Hence, improving performance
in this area is generally helpful, even if it is not strictly a critical
blocking issue.

What I want to say is: do not expect Org export to be faster than native
binary tools, but do not hesitate to report performance issues either.

Best,
Ihor