> Date: Thu, 30 Jan 2025 08:48:22 +0000 (UTC) > Cc: bug-texinfo@gnu.org > From: Werner LEMBERG <w...@gnu.org> > > > Below is a detailed reply to Eli, but while writing this I found out > what I *really* want :-) > > Please make *all* heading commands – including `@XXXheading` – control > the default print label of `@xref` in the PDF if > `@xrefautomaticsectiontitle` is active. This would make my suggestion > of an option unnecessary, but I'm not sure whether this can be easily > implemented.
The unnumbered headings don't appear in the TOC and don't have numbers, so, unless the body is very short the above will make the referenced text harder to find. > >> I see 'This is a meaningful anchor label' in both the HTML and Info > >> output, but I get 'A' in the produced PDF. > > > > You get "A, page NNN", where NNN is the page of the anchor, right? So > > why is "A" a problem? The chapter name actually appears in the > > document, whereas the anchor label does not. > > IMHO, the problem is that it is not immediately clear where to look at > that page. But references in printed manuals are always at page granularity. They are not accurate like on-line references. In a printed manual, there really is no alternative. > Here is a real-world example: In LilyPond's Notation Reference, we > have an unnumbered sub-sub-section called 'Articulations and > ornamentations' (on page 146). As with almost all similar sections in > the manual, it is followed by the sub-sub-headings 'Predefined > commands' and 'Selected snippets'. The latter, as the title says, > contains LilyPond code snippets that demonstrate various tips and > techniques, and where each one comes with a separate title using the > macro `@subsubsubheading` – these snippets originate from a 'LilyPond > Snippet Repository' (https://lsr.di.unimi.it) and are imported > semi-automatically. One of them is 'Controlling the vertical ordering > of scripts' (on page 148), and the corresponding `@anchor` next to it > has this title as its label. > > In the PDF, if I hover with the mouse above an `@xref` to that anchor, > I see 'Articulations and ornamentations', but I want to see > 'Controlling the vertical ordering of scripts', because this is the > heading next to the `@anchor`. Why is it important what is shown in the tooltip? What's important is that clicking lands you in the right spot (does it?). > > You assume that the text of the anchor's label is significant. > > I don't assume this in general. However, we do this in LilyPond, and > it fits for us. > > > But it isn't (or shouldn't), at least not in the printed output. > > You have the 4th argument of @xref to achieve what you want, if you > > really want that, and that argument allows you to specify _any_ text > > as the label for the cross-reference, regardless of whether it is or > > isn't the label of the anchor or the name of a node/chapter. > > > > IOW, if you want meaningful names for references, use the 3rd and 4th > > arguments to @xref. > > I know all that, thanks. However, following your advice would enforce > us to make a distinction between `@xref` calls to a `@node` label and > calls to an `@anchor` label, which is cumbersome – and I think it is > also sub-optimal regarding Texinfo's API. How so? The label of the @anchor replaces the node name, that's all. What kind of distinction is necessary? > Again, what I suggest is a Texinfo option similar to > `@xrefautomaticsectiontitle`. I can easily modify macro > `\getprintedrefname` in `texinfo.tex` to do it just for LilyPond (and > I'm going to do that soon), but maybe it makes sense for other people, > too. The problem with this suggestion is that it changes the results globally. Consider the plight of someone who reviews patches to the manual: with your suggestion, to judge the correctness and optimality of the patchj, one has to look at the full original manual source, or remember by heart that it has @xrefautomaticsectiontitle somewhere. By contrast, using @xref means all the information about the cross-reference is local.
