Benefits of using Sphinx documentation format

[Martin Liška]

On 7/12/21 4:12 PM, Eli Zaretskii wrote:
>> From: Jonathan Wakely <jwakely.gcc@gmail.com>
>> Date: Mon, 12 Jul 2021 14:53:44 +0100
>> Cc: Martin Liška <mliska@suse.cz>,
>> 	"gcc@gcc.gnu.org" <gcc@gcc.gnu.org>, gcc-patches <gcc-patches@gcc.gnu.org>,
>> 	"Joseph S. Myers" <joseph@codesourcery.com>
>>
>> For me, these items are enough justification to switch away from
>> texinfo, which produces crap HTML pages with crap anchors.
> 
> If we want to have a serious discussion with useful conclusions, I
> suggest to avoid "loaded" terminology.
> 
> 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.

Please follow my 1) from Benefits and *read* bullet points a) to f). That will
give you an answer.

> 
>> You can't find out the anchors without inspecting (and searching)
>> the HTML source. That's utterly stupid.
> 
> I don't think I follow: find out the anchors with which means and for
> what purposes?

Benefits, 1c).

> 
>> And even after you do that, the anchor
>> is at the wrong place:
>> https://gcc.gnu.org/onlinedocs/gcc/Overall-Options.html#index-c
> 
> IME, the anchor is where you put it.  If you show me the source of
> that HTMl, maybe we can have a more useful discussion of the issue.

Problem is that Texinfo emits poor HTML where # link points to a wrong place.
Open the given page, view source and search for <dd><a name="index-c"></a>.

> 
>> As somebody who spends a lot of time helping users on the mailing
>> list, IRC, stackoverflow, and elsewhere, this "feature" of the texinfo
>> HTML has angered me for many years.
> 
> As somebody who spends a lot of time helping users on every possible
> forum, and as someone who has wrote a lot of Texinfo, I don't
> understand what angers you.  Please elaborate.

You can't point to an option documentation.

> 
>> Yes, some people like texinfo, but some people also dislike it and
>> there are serious usability problems with the output. I support
>> replacing texinfo with anything that isn't texinfo.
> 
> "Anything"?  Even plain text?  I hope not.
> 
> See, such "arguments" don't help to have a useful discussion.
> 
>>>   4) The need to learn yet another markup language.
>>>      While this is not a problem for simple text, it does require a
>>>      serious study of RST and Sphinx to use the more advanced features.
>>
>> This is a problem with texinfo too.
> 
> Not for someone who already knows Texinfo.  We are talking about
> switching away of it, so I'm thinking about people who contributed
> patches for the manual in the past.  They already know Texinfo, at
> least to some extent, and some of them know it very well.

Yes, people will have to learn a new syntax. Similarly to transition of SVN,
people also had to learn with a more modern tool.

> 
>>>   5) Lack of macros.
>>>      AFAIK, only simple textual substitution is available, no macros
>>>      with arguments.
>>
>> Is this a problem for GCC docs though?
> 
> I don't know.  It could be, even if it isn't now.

Then it's not an argument, sorry.

Martin