On 7/12/21 4:12 PM, Eli Zaretskii wrote:
From: Jonathan Wakely <jwakely....@gmail.com>
Date: Mon, 12 Jul 2021 14:53:44 +0100
Cc: Martin Liška <mli...@suse.cz>,
"gcc@gcc.gnu.org" <gcc@gcc.gnu.org>, gcc-patches
<gcc-patc...@gcc.gnu.org>,
"Joseph S. Myers" <jos...@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
