Re: Benefits of using Sphinx documentation format

[Matthias Kretz <m.kretz@gsi.de>]

Hi.

I'm commenting as a long-time GCC user and reader of the manual (never via 
info reader, mostly via DuckDuckGo / Google -> HTML docs) who recently started 
contributing more than just PRs.

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.

But FWIW, when I reach the GCC HTML docs it's like a blast from the past. It 
looks more or less exactly like web pages looked in the 90ies. To me, that 
gives GCC an image of an old and sluggishly moving project. And to me that's a 
high priority issue.
I have to size down the browser window so that line lengths are bearable. I 
have to scroll to the top/bottom of the page for navigation. Navigating 
through the tree of pages requires you to learn how it works; it's not 
intuitive at all.

If the decision for how to write and read documentation places 'info' in 
higher priority than HTML then that would emphasize "the image of an old and 
sluggishly moving project" even more than the sight of the HTML pages. Who is 
the target audience?

> >>>   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.

Same issue. Is the goal to accommodate only seasoned GNU contributors? 
Basically everyone nowadays knows and uses Markdown. RST is not far from that. 
So it opens up the project for way more people to contribute. I wrote 
documentation patches recently. I found it really awkward to write. Markup 
languages have gotten better and I really hope we can move on!

> >>>   5) Lack of macros.
> >>>   
> >>>      AFAIK, only simple textual substitution is available, no macros
> >>>      with arguments.

I don't recall for sure, but I think I did that with RST at some point.

Best,
  Matthias

-- 
──────────────────────────────────────────────────────────────────────────
 Dr. Matthias Kretz                           https://mattkretz.github.io
 GSI Helmholtz Centre for Heavy Ion Research               https://gsi.de
 std::experimental::simd              https://github.com/VcDevel/std-simd
──────────────────────────────────────────────────────────────────────────