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

"Julia Evans" [off-list ref] writes:

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.

To see if I understand correctly, let me rephrase the second
paragraph a bit (not as an attempt to offer an improvement; by
restating the above differently while expressing what I take to be
the same thing, we will see whether I misunderstood what you wrote
if my version ends up saying what you did not intend), as I found it
somewhat puzzling.

    The short form <<EXAMPLES>> uses EXAMPLES as both the link
    target (which is not shown to the end user except in the
    browser's location bar when the link is visited) and the
    clickable text.  In different parts of the document, however,
    the text in HTML may need to be rendered as "EXAMPLES" or
    [EXAMPLES], which can be achieved by using the
    <<EXAMPLES,"EXAMPLES">> or <<EXAMPLES,[EXAMPLES]>> form.  For
    consistency, always use the longer form, even when there are no
    such typesetting constraints.

I'll mark the topic as Expecting a reroll in my working copy of the
"What's cooking" report of the next issue.

Thanks.