Re: [PATCH] doc: add more AsciiDoc cross-references
- From
Julia Evans <julia@jvns.ca>
- Date
- Sep 24, 2026, 12:30 UTC
- Message-ID
- <63520573-c8a7-41bd-aaeb-bfc2b5e43856@app.fastmail.com>
- In-Reply-To
- <20260923214038.GA49087@coredump.intra.peff.net>
Show 22 quoted lines
> Even weirder, in the manpage output both implementations actually expand > this to: the section called "FOO". So changing your patch like this: > > -See the <<PRUNING,PRUNING>> section below for more details. > +See the <<PRUNING>> section below for more details. > > gives doc-diff output like this: > > - See the PRUNING section below for more details. > + See the the section called “PRUNING” section below for more details. > > which is obviously nonsense. > > I could very well believe that some older versions did other weird > things in the presence of includes. ;) But AFAICT the real need for the > doubled text is to control what is in the expanded text (both because of > differences between the versions, but also differences in output > backends). > > Which is kind of a shame, because writing just <<PRUNING>> makes the > source a lot more readable. I wonder if we can configure these text > fallbacks, which would let us use the single-item form reliably.
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 <<PRUNING>>, 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.
Re your other message about breaking links because we're changing the HTML IDs: the options I see right now are
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 <<PRUNING>>
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.
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 <<EXAMPLES,EXAMPLES>>
below" to make the man pages easier to navigate on the web. The reason for using the more verbose <<EXAMPLES,EXAMPLES>>
(instead of <<EXAMPLES>>) 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.