From: Jeff King Date: Thu, 24 Sep 2026 15:55:17 GMT Subject: Re: [PATCH] doc: add more AsciiDoc cross-references Message-ID: <20260924155517.GB736248@coredump.intra.peff.net> In-Reply-To: <63520573-c8a7-41bd-aaeb-bfc2b5e43856@app.fastmail.com> On Thu, Sep 24, 2026 at 08:30:31AM -0400, Julia Evans wrote: > Thanks for investigating, I was really dreading looking into the guts of > asciidoc to figure out exactly what was happening. It would be nice to be able > to write just <>, especially because I believe asciidoctor will check > that internal links are valid, so there's no concern about breaking links if we > change the title of a section. I think asciidoc(tor) doesn't do it itself, so HTML will be generated with a broken link. But in the manpage flow, we pass through xml docbook, which does complain loudly. So that will be enough to let us know about the breakage. > 1. Leave it is as is and break some links > 2. manually enter the ID like `_editing_patches`, trying to make sure to always > match the auto-generated ID (I'm not sure how to do that). I think this might > also cause some confusion for editors in the future as to why the section IDs > are formatted like that > 3. Somehow fix it so that we can just do <> > > I'm not sure if #1 or #2 is better, obviously I'm biased towards #1 because > it's less work for me. #3 seems like the ideal but I don't know how to do that. Yeah, sorry I was a bit rambly in my other message, but I think #1 is OK. I'm not sure if asciidoctor allows us to configure the algorithm for converting a title into a section id. If it does, it might be nice to have a flag day where we make all of the auto-ids look like what we'd expect. But that is a totally separate topic, and can happen later. I think #3 is sort-of orthogonal, as I couldn't get the "natural" xrefs to work. So we have to either declare the ids ourselves or use the auto-generated ones, at which point the use of single- or double- <> xrefs is purely a matter for the linking site, not the linked-to section. > Here's a revised commit message, can submit that as a v2 if it seems correct. > > doc: add more AsciiDoc cross-references > > Instead of saying "see EXAMPLES below", say "see <> > below" to make the man pages easier to navigate on the web. > > The reason for using the more verbose <> > (instead of <>) is in some cases, the HTML output is rendered > as `"EXAMPLES"` or `[EXAMPLES]` instead of just `EXAMPLES`. > So this gives us more control over how the output looks. > > This also changes some of the HTML IDs of the headings from `_examples` > to `EXAMPLES`, which has the potential to break some links. Yeah, I think this is OK. If we want to be really pedantic, the "EXAMPLES" with quotes is only in the manpages, not the HTML (and also includes extra text: "the section called"). But the point is the same. We must use the doubled form to get consistent text output. -Peff