Re: [PATCH] doc: add more AsciiDoc cross-references

["Julia Evans" <julia@jvns.ca>]

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