Re: Benefits of using Sphinx documentation format

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

On Mon, Jul 12, 2021 at 7:20 PM Jonathan Wakely via Gcc <gcc@gcc.gnu.org> wrote:
>
> On Mon, 12 Jul 2021 at 18:04, Eli Zaretskii via Gcc <gcc@gcc.gnu.org> wrote:
> >
> > > From: Matthias Kretz <m.kretz@gsi.de>
> > > Date: Mon, 12 Jul 2021 16:54:50 +0200
> > >
> > > On Monday, 12 July 2021 16:30:23 CEST Martin Liška wrote:
> > > > On 7/12/21 4:12 PM, Eli Zaretskii wrote:
> > > > > I get it that you dislike the HTML produced by Texinfo, but without
> > > > > some examples of such bad HTML it is impossible to know what exactly
> > > > > do you dislike and why.
> > >
> > > I believe Martin made a really good list.
> >
> > Gavin Smith, the GNU Texinfo maintainer, responded in detail to that
> > list.  However, his message didn't get through to the list, for some
> > reason.
>
> It did:
> https://gcc.gnu.org/pipermail/gcc/2021-July/236744.html
> https://gcc.gnu.org/pipermail/gcc-patches/2021-July/574987.html
>
> The HTML attachment has been stripped though. The relevant part of the
> HTML looks like this:
>
> <dt id='index-_002d_002dgreeting'><span><samp>--greeting=<var>text</var></samp><a
> href='#index-_002d_002dgreeting' class='copiable-anchor'>
> &para;</a></span></dt>
> <dt><span><samp>-g <var>text</var></samp></span></dt>
> <dd><span id="index-_002dg"></span>
> <p>Output <var>text</var> instead of the default greeting.
> </p>
> </dd>
>
> Note the <a ...> &para; </a> anchor that is part of the <dt> element,
> not the <dd> (where the index-__002d anchor is still located).
>
>
> >  Can someone please see why, and release his message?  I think
> > he makes some important points, and his message does deserve being
> > posted and read as part of this discussion.
>
> He shows that some of the linking issues are addressed in the latest
> texinfo release, which is great. But it doesn't negate all Martin's
> other points.
>
> GCC devs and users who frequently modify or refer to the HTML docs
> want to replace texinfo. One vocal objector who just keeps repeating
> that texinfo is fine should not block that progress.

You mean one very vocal and one active developers want to replace it?
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 ...).

But then I'm mostly of the who-does-the-work-decides attitude - so if there
are people driving a transition to sphinx because they want to improve sth
and they don't manage to do that with texinfo (for whatever reason) then OK.
As long as it doesn't regress my personal usecase (I hope the sphinx
docs are still
digestable in source form, which I understand they are).

Just I really suggest to not claim its texinfos fault.  It's likely
not.  It's likely
the fault of GCCs manual being "old" and hasn't catched up with new
texinfo features.  And where texinfo has bugs they likely can be fixed.

Just my (final) 2c to this discussion.

Richard.