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

[Junio C Hamano <gitster@pobox.com>]

"Julia Evans" <julia@jvns.ca> writes:

>> 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 meant something different, let me try again (with Peff's corrections as well):
>
>     The reason for using the more verbose <<EXAMPLES,EXAMPLES>>
>     (instead of <<EXAMPLES>>) is that in some cases, <<EXAMPLES>> is
>     rendered as `the section called "EXAMPLES"` or `[EXAMPLES]`.
>     <<EXAMPLES,EXAMPLES>> is rendered as just `EXAMPLES`, which gives us
>     more control over the output.
>
> ("in some cases" is code for "I still don't fully understand
> exactly when each one happens and why")

I see.  I think I understand now.

In your example, "leaving it vanilla without any extra adornment" is
the control you want to gain by using the two-argument form, while in
the version that shows my (mis)understanding, it is "you can mark up
the string that is shown in any way you want".

Either way, the shorthand form forces you to leave the rendering to
the toolchain, but the two-argument form gives you more control over
how the text is rendered.

Thanks.