[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Werner LEMBERG
Subject: Re: Problems with `@anchor` and `@xrefautomaticsectiontitle`
Date: Sat, 20 Feb 2021 14:59:46 +0100 (CET)

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

  This context also accepts commands for the following context(s):

> 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

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


PNG image

reply via email to

[Prev in Thread] Current Thread [Next in Thread]