public inbox for gcc@gcc.gnu.org
 help / color / mirror / Atom feed
From: Jonathan Wakely <jwakely.gcc@gmail.com>
To: Eli Zaretskii <eliz@gnu.org>
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>
Subject: Re: Benefits of using Sphinx documentation format
Date: Mon, 12 Jul 2021 16:03:29 +0100	[thread overview]
Message-ID: <CAH6eHdQnd9JQs9gKpXGZZabvkrWy-qeBQaoj7WYN0tg1y4_+ow@mail.gmail.com> (raw)
In-Reply-To: <CAH6eHdS7xAmFh+oR8ybY-ab_U4JKzoZuN-a7_jQP97WgtHfd4g@mail.gmail.com>

On Mon, 12 Jul 2021 at 15:52, Jonathan Wakely <jwakely.gcc@gmail.com> wrote:
>
> On Mon, 12 Jul 2021 at 15:13, Eli Zaretskii <eliz@gnu.org> 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.
> >
> > > 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?
>
> I want to point a user at the documentation for the -c option. I can't
> do that without examining the HTML source to find the anchor, then
> manually editing the URL to append the anchor. It's a tedious process,
> and the result is an anchor that doesn't even point to the option but
> to the text following it. The process is unnecessarily difficult and
> the results are bad.
>
> You participated in a discussion about this very topic previously:
> https://lists.gnu.org/archive/html/help-texinfo/2019-02/msg00000.html
>
> >
> > > 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.
>
> @item -c
> @opindex c
> Compile or assemble the source files, but do not link.  The linking
> stage simply is not done.  The ultimate output is in the form of an
> object file for each source file.
>
> Putting the @opindex before the @item causes the anchor to be placed
> on the previous item, which is not desirable.

GNU Hello has the same problem with its docs:
https://www.gnu.org/software/hello/manual/hello.html#index-_002dg
That URL is garbage because of the URL-encoded %2d character, and the
fact it links to the wrong place (the description of the option, not
the option itself). The former is no longer an issue for GCC (it was
for many years) but the latter is still a problem.

If you don't know where to find it yourself, the source is visible here:
https://github.com/yugui/example/blob/master/doc/hello.texi#L208

If GNU Hello and GCC can't get this right using texinfo, maybe texinfo
is not fit for purpose?

  parent reply	other threads:[~2021-07-12 15:03 UTC|newest]

Thread overview: 115+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
     [not found] <1446990946.2994.192.camel@surprise>
     [not found] ` <e7f490fc-ab76-5bc5-5e94-1d9f00f34b62@suse.cz>
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-05-31 15:49       ` Michael Matz
2021-06-01  7:31         ` Martin Liška
2021-06-01 13:31           ` Michael Matz
2021-06-02  7:36             ` Martin Liška
2021-06-02 16:05               ` Joel Sherrill
2021-06-02 16:44                 ` Joseph Myers
2021-06-03 12:26                   ` Martin Liška
2021-06-03 17:16                     ` Joseph Myers
2021-06-04  7:27                       ` 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-11 18:48                 ` Koning, Paul
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-25 13:14                         ` Martin Liška
2021-06-28 10:23                         ` Arnaud Charlet
2021-06-28 10:44                           ` Martin Liška
2021-06-29 15:54                             ` Arnaud Charlet
2021-06-30  7:52                               ` Martin Liška
2021-08-10 15:43                                 ` Martin Liška
2021-08-27  9:31                                   ` 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 10:50                               ` Richard Earnshaw
2021-06-30  4:47                                 ` Martin Liška
2021-06-30 10:14                                   ` Richard Earnshaw
2021-06-30 11:58                                     ` Martin Liška
2021-06-29 16:57                               ` Eli Zaretskii
2021-06-29 18:01                                 ` Eli Zaretskii
2021-06-30 10:11                                 ` Martin Liška
2021-06-30 10:46                                   ` Martin Liška
2021-06-30 13:09                                   ` Eli Zaretskii
2021-07-01 12:44                                     ` Martin Liška
2021-07-01 13:33                                       ` Eli Zaretskii
2021-07-01 14:14                                         ` Martin Liška
2021-07-01 15:06                                           ` Michael Matz
2021-07-02  9:40                                             ` Martin Liška
2021-07-02 10:32                                               ` Eli Zaretskii
2021-07-01 15:44                                           ` Eli Zaretskii
2021-07-01 16:04                                             ` Martin Liška
2021-07-01 16:58                                               ` Eli Zaretskii
2021-07-02  9:30                                                 ` Martin Liška
2021-07-02 10:31                                                   ` Eli Zaretskii
2021-07-02 13:23                                                     ` Martin Liška
2021-07-02 23:53                                     ` Hans-Peter Nilsson
2021-07-05  9:17                                       ` Richard Sandiford
2021-07-05 12:14                                         ` Eli Zaretskii
2021-07-05 13:03                                           ` Richard Sandiford
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 [this message]
2021-07-12 16:00                                                   ` Gavin Smith
2021-07-12 16:15                                                     ` Jonathan Wakely
2022-07-05 12:27                                                       ` Copiable anchor links in gcc manual Gavin Smith
2022-07-05 13:28                                                         ` Jonathan Wakely
2021-07-12 14:37                                           ` Benefits of using Sphinx documentation format Martin Liška
2021-07-12 17:12                                             ` Eli Zaretskii
2021-07-12 16:36                                         ` David Malcolm
2021-07-12 18:23                                           ` Koning, Paul
2021-06-30 12:26                                 ` [PATCH] Port GCC documentation to Sphinx Martin Liška
2021-06-30 13:28                                 ` Martin Liška
2021-06-30 13:38                                   ` Eli Zaretskii
2021-06-30 14:04                                     ` Martin Liška
2021-06-30 15:43                                       ` Eli Zaretskii
2021-07-01 12:31                                         ` Martin Liška
2021-07-12 17:18                               ` Martin Sebor
2021-08-09 12:18                                 ` Martin Liška
2021-07-13 14:54                               ` Tamar Christina
2021-08-09 13:29                                 ` Martin Liška
2021-06-02 20:41       ` GCC documentation: porting " Martin Sebor
2021-06-03 10:56         ` Martin Liška
2021-06-04 15:10           ` Martin Sebor
2021-06-10  9:07             ` Martin Liška
2021-06-10 13:18               ` Martin Liška
2021-06-10 23:48                 ` Martin Sebor
2021-06-11 14:34                   ` Martin Liška
2021-06-04  7:55     ` RFC: Sphinx for GCC documentation Tobias Burnus
2021-06-04 14:24       ` Koning, Paul
2021-06-07 13:30         ` Martin Liška
2021-06-07 21:26           ` Bernhard Reutner-Fischer
2021-06-08  7:43             ` Martin Liška
2021-06-07 13:28       ` Martin Liška
2021-06-07 14:19         ` Tobias Burnus
2021-06-10 10:32           ` Martin Liška
     [not found] <CAKPWYQ0QEqE1v3kv_gvRXEEJOPd8j6FetAU_wh7Vssw81DTj4Q@mail.gmail.com>
     [not found] ` <CAKPWYQ3EobaPGskg9kq5gYtHFoGNXFLtCOcrcFouxg4skvJRxA@mail.gmail.com>
2021-07-12 17:49   ` Benefits of using Sphinx documentation format Gavin Smith
2021-08-09 12:04     ` Martin Liška

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=CAH6eHdQnd9JQs9gKpXGZZabvkrWy-qeBQaoj7WYN0tg1y4_+ow@mail.gmail.com \
    --to=jwakely.gcc@gmail.com \
    --cc=eliz@gnu.org \
    --cc=gcc-patches@gcc.gnu.org \
    --cc=gcc@gcc.gnu.org \
    --cc=joseph@codesourcery.com \
    --cc=mliska@suse.cz \
    /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).