Re: Integration of Info manuals in programming modes, Re: Integration of Info manuals in programming modes

[Björn Bidar]

IMHO this discussion should be moved to the texinfo mailinglist as it
only tangentially related to Emacs.

Richard Stallman <rms@gnu.org> writes:

> [[[ 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. ]]]
>
>   > We can for example also export from Org Mode to info, and that also does
>   > not replace texinfo but rather extends the possibilities we have to
>   > generate well-usable manuals.
>
>   > Ideally all the different code documentation tools could export either
>   > to texinfo or to info, and pandoc[1] can already convert most manual
>   > formats to info.
>
> It is posible to convert from any format to Texinfo and make some sort
> of a manual in Texinfo.  That is presumably an advance compared with
> no Texinfo version at all.

I don't know but the closer the input format follows the structure of a
classic manual the better are the chances I think.

> But if that other format cannot express the distinctions that are
> standard for Texinfo, the output of this conversion won't be a very
> good Texinfo manual.  It will be an inferior Texinfo manual, compared
> with the ones natively written in Texinfo.
>
> That might be better than what we have now, but it is not good.
>
> To get a _good_ Texinfo manual requires people to manually convert the
> manual into Texinfo, or into some possible future format which can
> makes those distinctions.


Possibly but you have to ask your self.

1. Is that a sustainable effort?
2. Having a manual conversion vs. having a sorta working version which
   is up to date

> So the question is how we can stimulate work to produce the _best_
> result, rather than accepting forever an inferior result.

>From my point of view long term solutions would be:

1. Make Texinfo a more accessible and competitive format.

   Some projects want or care more about good HTML based output.
   While GNU itself doesn't encourage the use of HTML based manuals
   compared to Info based manuals they none the less are very important
   for many projects. Trying to appease to the needs of projects who
   potentially want to use Texinfo should be a goal to drive adoption.

   This for example would also include adopt more modern output of
   Texinfo manuals in HTML. emacsdocs.org is a good example how
   something like this could look like. [1]
   Emacsdocs is a dual GPL-3.0 and GDFL licensed website.
   While the website employs a conversion of the Texinfo HTML output
   to Markdown to then create built the website it is none the less
   a good example who something like it could look like.

   For formats where the output is very similar to Info manuals
   automatic or partially manual conversion could be employed.
   IMHO it makes little sense to convert something which uses a tool
   like Doxygen into Texinfo, while for manuals created using Sphinx
   that seems to make much more sense.

   Maybe provide other ways to create Info manuals then directly
   using Texinfo, e.g. the org-mode manual would be a good example.
   Sphinx uses Rst - Restructed Text which looks very similar to
   Org-Mode as an input format.

2. Fund development for improvements in existing Info viewers or
   create new ones. A related thing would be to make it possible
   to Info format in existing manuals reader or IDE's.
   More ways to read Info manuals will not only help Info but
   also the whole GNU project.

[1] https://github.com/tefkah/emacs-docs