Re: Problems with `@anchor` and `@xrefautomaticsectiontitle`

[Werner LEMBERG]

>> The problem:
>>   In the anchor reference the corresponding section reference title
>>   is shown.  IMHO, this doesn't make much sense because it loses
>>   context – in the example above, how shall the reader know that
>>   she has to look for 'blubb'?  A better solution is to use the
>>   anchor node name if #3 of `@xref` is missing, inspite of
>>   `@xrefautomaticsectiontitle on`.
>>
>>   Note that for automatically generated `@xref` entries (as we have
>>   in LilyPond's 'Internal Reference' manual) it is not possible to
>>   manually provide a third argument; it would be thus quite
>>   valuable if the default could be improved.
> 
> Why can't the third argument be automatically generated as well?  It
> seems inconsistent to use the anchor name in cross-references while
> not using node names in cross-references.

The problem is that LilyPond's xref generator doesn't know whether the
target is a `@node` or an `@anchor`.  Always generating the third
argument automatically is essentially the equivalent to

  @xrefautomaticsectiontitle off

which gives worse optical results.

Attached you can see our real use-case.  On page 204 there is a
description of the 'Timing' context.  Since this LilyPond 'context' is
defined in a different way compared to other contexts, causing the
document generator to not create a separate subsection, I have to
manually insert an `@anchor` command in the documentation string.

The last line of the image is auto-generated by the documentation
generator (iterating over a Scheme list with a single element,
`Timing`):

  This context also accepts commands for the following context(s):
  @ref{Timing}.

> Moreover in most books if you saw a reference "see blub" you would
> be looking for a heading on the page "blub" which may not always
> exist for an @anchor.

As I told before, this is not a normal book but an auto-generated
documentation.

Anyway, I think it makes sense to change the one-argument `@xref` and
friends to produce a better default.


    Werner