Re: Benefits of using Sphinx documentation format

[Richard Biener <richard.guenther@gmail.com>]

On Tue, Jul 13, 2021 at 1:52 PM Eli Zaretskii <eliz@gnu.org> wrote:
>
> > From: Richard Biener <richard.guenther@gmail.com>
> > Date: Tue, 13 Jul 2021 08:24:17 +0200
> > Cc: Eli Zaretskii <eliz@gnu.org>, "gcc@gcc.gnu.org" <gcc@gcc.gnu.org>
> >
> > I actually like texinfo (well, because I know it somewhat, compare to sphinx).
> > I think it produces quite decent PDF manuals.  I never use the html
> > output (in fact I read our manual using grep & vim in the original
> > .texi form ...).
>
> FTR, I almost exclusively use the (Emacs) Info reader to read the
> manuals in Info format.  I never understood those who prefer reading
> HTML-formatted docs in a Web browser.  The advanced features of Info:
> the index-search with powerful completion built-in, seamless
> cross-references between manuals, the ability to search all of the
> manuals installed on my system and then browse the results, the
> ability to have Emacs land me at the documentation of the symbol under
> the cursor regardless of its language/package/library, no dependency
> on connectivity, to mention just a few -- all those are tremendous
> productivity boosters.  I rarely spend more than a few seconds to find
> the piece of documentation I need (not including reading it, of
> course).  (And yes, grep-style regexp search through the entire manual
> is also available, although I only need to use it in rare and
> exceptional circumstances.)
>
> So I never understood people, let alone developers, who are willing to
> throw such power out the window and use HTML.  I only do that when
> there's a manual I don't have installed in the Info format (a rare
> phenomenon) or some other similarly exceptional cases.  But I get it
> that there are strange people who prefer HTML nonetheless.  More
> importantly, the Texinfo developers understand that, and actively work
> towards making the Texinfo HTML better, with some impressive progress
> already there, see the latest release 6.8 of Texinfo (Gavin mentioned
> some of the advances).

I can very well understand the use of the html manual when you want
to share pointers to specific parts of the documentation in communications.
I think that's the main motivation here - users are nowadays familiar with
mouse-clicking and the web, not so much with emacs or any other way
to consume texinfo documentation.  I'm also not sure if there's some
texinfo URI that could be used to share documentation pointers.

Richard.