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