public inbox for gcc@gcc.gnu.org
 help / color / mirror / Atom feed
From: "Martin Liška" <mliska@suse.cz>
To: Gavin Smith <gavinsmith0123@gmail.com>, gcc@gcc.gnu.org
Subject: Re: Benefits of using Sphinx documentation format
Date: Mon, 9 Aug 2021 14:04:28 +0200	[thread overview]
Message-ID: <2c3670ab-19d8-0e3d-e70e-a76de0cc4ec8@suse.cz> (raw)
In-Reply-To: <CAKPWYQ35WRTauhVa5yhq9KurQMuxOon2ycDWTNrt7A95oysauw@mail.gmail.com>

On 7/12/21 7:49 PM, Gavin Smith via Gcc wrote:
> (Sending mail again, without attachments this time in the hope it gets through.)
> 
> I had the discussion about moving documentation of gcc from Sphinx to
> Texinfo brought to my attention.
> 
> https://gcc.gnu.org/pipermail/gcc/2021-July/236731.html
> 
> Speaking as the Texinfo maintainer, I hope to add my views and
> understandings of things to this discussion to improve your
> understanding of the facts and possibilities, although of course it's
> up to you whether you use Texinfo or not.

Hello.

Appreciate your time spent working on the tool and I'm going to briefly reply
your points.

> 
> I will work through the points made in that email but haven't read any
> of the subsequent discussion yet - I'll follow up on anything else
> afterwards.
> 
>> Benefits:
>> 1) modern looking HTML output (before: [1], after: [2]):
> 
>>     a) syntax highlighting for examples (code, shell commands, etc.)
> 
> Syntax highlighting has been achieved with Texinfo before. See
> 
> https://guix.gnu.org/manual/devel/en/html_node/Using-the-Configuration-System.html
> 
> and
> 
> https://lists.gnu.org/archive/html/bug-texinfo/2019-11/msg00004.html
> 
> With Texinfo 6.8, syntax highlighting in multiple languages is easier
> to achieve by giving an argument to the @example command
> (https://www.gnu.org/software/texinfo/manual/texinfo/html_node/_0040example.html).
> This puts a class attribute on the HTML element which can then be
> picked up by a post-processor. It might also be possible to achieve
> syntax highlighting with a customization file used by the Texinfo
> tools themselves: see
> https://lists.gnu.org/archive/html/bug-texinfo/2021-01/msg00031.html.

If I understand correctly, that would need a further post-processing of the HTML
elements. Sphinx works out of the box and the same output is achieved also for PDF output.

> 
>>     b) precise anchors, the current Texinfo anchors are not displayed (start with first line of an option)
>>     c) one can easily copy a link to an anchor (displayed as ¶)
> 
> Similar anchors were implemented in Texinfo 6.8. See
> https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Invoking-texi2any.html
> and hover any of the options there with your mouse; you will see the
> pilcrow sign appear.

Good.

> 
>>     e) left menu navigation provides better orientation in the manual
> 
> Left menu navigation is possible with the new JavaScript interface, in
> Texinfo 6.8. There is still a demo at
> 
> https://per.bothner.com/tmp/Kawa-txjs-plain/Community.html
> 
> and
> 
> https://per.bothner.com/tmp/Kawa-txjs/Community.html

To be honest, it looks still quite legacy and I don't want to spend more working
on a custom CSS template and reasonable JS functionality. I would like to take
an existing theme that looks nice and provides reasonable capability. That's for me
https://github.com/readthedocs/sphinx_rtd_theme

> 
> However, I would say that it isn't necessarily always an improvement,
> if it is going to be buggy. When I click on the link
> https://splichal.eu/gccsphinx-final/html/gcc/gcc-command-options/options-that-control-optimization.html#cmdoption-fstrict-aliasing
> the browser doesn't scroll the sidebar so to show the active ToC entry
> (although it
> is displayed correctly when I refresh the page).

If I open a new tab, a browser correctly scrolls to the option documentation.

> 
> The more sophisticated the HTML/JS becomes the more likely there are
> these little nits.
> 
>>     f) Sphinx provides internal search capability: [3]
> 
> There is a global search facility with the JavaScript interface
> although different to that provided by Sphinx, only showing one match
> at a time.

As said, it's a limitation to me.

> 
> Try
> 
> https://per.bothner.com/tmp/Kawa-txjs/index.html
> 
> and then press "s" on your keyboard, type in your search string (e.g.
> "composable") and it will search through the manual for that string.
> To go to the next match, press "s" then Return.
> 
> The proviso about "sophisticated" HTML still applies here, though.
> 
>> 2) internal links are also provided in PDF version of the manual
> 
> Links already work when viewing a PDF on a computer.
> 
> If you want to add additional links that only appear in PDF and HTML
> and not in Info, this is easily achieved with a conditional macro,
> like
> 
> @ifset morelinks
> @macro link{arg}
> @ref{\arg\}
> @end macro
> @end ifset
> @ifclear morelinks
> @macro link{arg}
> \arg\
> @end macro
> @end ifclear
> 
> followed by "@set morelinks" or "@clear morelinks" as required.

All right, that would likely require providing more anchors in the existing GCC
documentation.

> 
>> 5) Sphinx is using RST which is quite minimal semantic markup language
> 
> This is really an ineffable question of taste on which it is hard to
> be convinced, but I have to point out that Texinfo is minimalistic,
> with only three special characters (@, { and }).
> 
>> 6) TOC is automatically generated - no nee6d for manual navigation like seen here: [5]
>> 5] @comment node-name,     next,          previous, up
>>      @node    Installing GCC, Binaries, , Top
> 
> This is a completely bogus point with these explicit "pointers" being
> optional. I couldn't find out easily how long ago these pointers
> became optional, but it is at least twenty years ago.

Got that, thus we use unnecessary syntax right now.

> 
> A couple of other points, not mentioned in the original email:
> * One possible disadvantage of moving away from Texinfo which might be
> easily missed is support for reliable web links between different
> manuals. If you change format you should make sure that these work,
> e.g. if you reference the glibc manual the web link to that should
> work correctly (as well as the link working in the Info format).

Good point, I'm not aware of any cross links. If there are any, I'm willing
to update them.

> * A disadvantage of focusing on HTML output is that locally installed
> documentation gets sidelined: although locally installed HTML
> documentation is possible, it tends not to happen and people refer to
> the web version instead, with all of its disadvantages (slow speed,
> may be the wrong version or disappear off the web, lack of user
> privacy). Another disadvantage of HTML is that links can only go to
> one place, while with the Info format you can have manuals installed
> in several places, even more than one version of a manual installed at
> once.

Totally misleading. I don't see why would anybody install HTML documentation locally.
Our motivation is to have HTML documentation on our site, where we can update it
and Google can index it for people using full text search.

> 
> Some people don't realise that Texinfo is actively maintained and
> there is a mailing list at bug-texinfo@gnu.org
> (https://lists.gnu.org/mailman/listinfo/bug-texinfo); this is a place
> for people to discuss their needs as to what they need from the
> system. I wonder if some of the desiderata can be satisfied with
> existing facilities in Texinfo or if not if we could accommodate them
> with not too much difficulty.

As mentioned, I appreciate your work. On the other hand, Sphinx documentation community
is much bigger and the list of projects using the tool is pretty huge:
https://www.sphinx-doc.org/en/master/examples.html (include huge FOSS projects like
LLVM, or Linux kernel). That makes me believe the transition makes sense and we will
benefit from it as project.

Martin




  reply	other threads:[~2021-08-09 12:04 UTC|newest]

Thread overview: 32+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
     [not found] <CAKPWYQ0QEqE1v3kv_gvRXEEJOPd8j6FetAU_wh7Vssw81DTj4Q@mail.gmail.com>
     [not found] ` <CAKPWYQ3EobaPGskg9kq5gYtHFoGNXFLtCOcrcFouxg4skvJRxA@mail.gmail.com>
2021-07-12 17:49   ` Gavin Smith
2021-08-09 12:04     ` Martin Liška [this message]
     [not found] <1446990946.2994.192.camel@surprise>
2021-05-13 11:45 ` RFC: Sphinx for GCC documentation Martin Liška
2021-05-31 13:25   ` GCC documentation: porting to Sphinx Martin Liška
2021-06-02 17:27     ` Joseph Myers
2021-06-10 14:06       ` Martin Liška
2021-06-10 16:49         ` Joseph Myers
2021-06-11 14:33           ` Martin Liška
2021-06-11 15:50             ` Joseph Myers
2021-06-23 13:13               ` Martin Liška
2021-06-23 16:00                 ` Joseph Myers
2021-06-24 14:08                   ` Martin Liška
2021-06-25 13:11                     ` Martin Liška
2021-06-28 12:01                       ` [PATCH] Port GCC documentation " Martin Liška
2021-06-28 15:33                         ` Joseph Myers
2021-06-29 10:09                           ` Martin Liška
2021-06-29 16:57                             ` Eli Zaretskii
2021-06-30 10:11                               ` Martin Liška
2021-06-30 13:09                                 ` Eli Zaretskii
2021-07-02 23:53                                   ` Hans-Peter Nilsson
2021-07-12 13:25                                     ` Benefits of using Sphinx documentation format Martin Liška
2021-07-12 13:39                                       ` Eli Zaretskii
2021-07-12 13:53                                         ` Jonathan Wakely
2021-07-12 14:05                                           ` Jonathan Wakely
2021-07-12 14:16                                             ` Eli Zaretskii
2021-07-12 14:34                                               ` Martin Liška
2021-07-12 17:09                                                 ` Eli Zaretskii
2021-07-12 14:12                                           ` Eli Zaretskii
2021-07-12 14:30                                             ` Martin Liška
2021-07-12 14:54                                               ` Matthias Kretz
2021-07-12 17:03                                                 ` Eli Zaretskii
2021-07-12 17:15                                                   ` Jonathan Wakely
2021-07-12 17:23                                                     ` Eli Zaretskii
2021-07-12 17:33                                                       ` Jonathan Wakely
2021-07-13  6:24                                                     ` Richard Biener
2021-07-13 11:52                                                       ` Eli Zaretskii
2021-07-13 12:46                                                         ` Richard Biener
2021-07-13 12:55                                                           ` Eli Zaretskii
2021-08-09 12:12                                                         ` Martin Liška
2021-07-13 14:19                                                       ` Jonathan Wakely
2021-07-12 14:52                                             ` Jonathan Wakely
2021-07-12 14:54                                               ` Jonathan Wakely
2021-07-12 17:14                                                 ` Eli Zaretskii
2021-07-12 15:03                                               ` Jonathan Wakely
2021-07-12 16:00                                                 ` Gavin Smith
2021-07-12 16:15                                                   ` Jonathan Wakely
2021-07-12 14:37                                         ` Martin Liška
2021-07-12 17:12                                           ` Eli Zaretskii
2021-07-12 16:36                                       ` David Malcolm
2021-07-12 18:23                                         ` Koning, Paul

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=2c3670ab-19d8-0e3d-e70e-a76de0cc4ec8@suse.cz \
    --to=mliska@suse.cz \
    --cc=gavinsmith0123@gmail.com \
    --cc=gcc@gcc.gnu.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).