Document `\Hy@raisedlink` and `\hyper@@link` as public for class and package authors?

[gusbrs]

Section 4 of the manual "Interfaces for class and package authors" lists some public interfaces of hyperref, and welcomes suggestions, so I make a couple of them.

I'm not sure if \Hy@raisedlink is meant to be public, but it is certainly quite useful for packages providing hyperref support. So, if it is meant to be public, could it be documented as such in the manual? If not, could a public version of it be considered?

The second suggestion (made in edit) is \hyper@@link. If it is meant to be public, the inclusion would be welcome. If its not, I don't see an alternative for making a link to "a destination name in a file". xr-hyper can do this, but it exploits the famous "fifth empty field" of \newlabel, which is actually consumed deep down in hyperref's machinery (as far as I can tell, in \Hy@setref@link). A grep in the TL tree gives a reasonable number of packages which make use of it. I'm guilty as charged, but I'm not alone, the list includes: cite.sty, cleveref.sty, amsrefs.sty, among others.

[u-fischer]

I'm still pondering about \Hy@raisedlink. If I make it public then probably not under this name. But I have some doubt that packages should use it directly. Imho destinations should be created by \hyper@refstepcounter (I'm pondering making this public) or \phantomsection which both contain the raised link code.

I don't think that \hyper@@link should be public. That command tries to guess which link type to create based on some heuristics of the argument (which can sometimes fail). Imho package writers should better use the dedicated commands depending on if it should go to an external file or an internal link:

\hyper@@link{filename}{destname}{link text}
=>
\hyper@linkfile {link text} {filename} {destname}

and

\hyper@@link{}{destname}{link text}
=>
\hyper@link {link}{destname}{link text}
or
\hyper@linkstart {link} {destname} link text \hyper@linkend 
or some other context, eg.
\hyper@linkstart {cite} {destname} link text \hyper@linkend 

and

\hyper@@link{https://filename}{destname}{link text}
=>
\hyper@linkurl {link text}{https://filename\hyper@hash destname}

[gusbrs]

Hi Ulrike,

\hyper@@link{filename}{destname}{link text}
=>
\hyper@linkfile {link text} {filename} {destname}

I had missed \hyper@linkfile could be a full replacement for the use case I have and that one could build an "external" link as you show with \hyper@linkurl. Point taken. And than you for the suggestions.

I'm still pondering about \Hy@raisedlink. If I make it public then probably not under this name. But I have some doubt that packages should use it directly. Imho destinations should be created by \hyper@refstepcounter (I'm pondering making this public) or \phantomsection which both contain the raised link code.

I do have some use cases where, as far as I can tell, I could not handle with either of those. At least not without controlling \theH<counter> (with which I troubled you previously). But me not knowing how to do otherwise is not really a strong point. What perhaps could be an argument is that there exists a public interface to set the anchor manually, in the form of \hyper@anchor, \hyper@anchorstart, and \hyper@anchorend. Considering how frequent the idiom \Hy@raisedlink{\hyper@anchorstart{\@currentHref}\hyper@anchorend} is in the source, if we can set the anchor, shouldn't we be able to raise it too? Of course, with an appropriate public name, as it may be.

[u-fischer]

I do have some use cases where, as far as I can tell, I could not handle with either of those. At least not without controlling \theH<counter>

Well I think that sounds more as if you need an interface "to control \theHcounter". What is the destination name you want to get? Can you show an example or a link?

[gusbrs]

Well I think that sounds more as if you need an interface "to control \theHcounter". What is the destination name you want to get? Can you show an example or a link?

I know this is not a support channel. I'll describe the case in the spirit providing an use case that hyperref may deem interesting. But, if it turns out it is really just "me not knowing how to do it", please feel free to just say "go ask in TeX.SX".

I'm working with end notes right now, and the command can receive an arbitrary "mark", as is somewhat tradition for footnote and endnote functionality to receive an arbitrary number there, in which case the counter is not stepped. This excludes the use of \hyper@refstepcounter (unless I start to go around it, and decrease before stepping, etc.). And, for hyperlinking the end notes (forth and back), I have to build correct anchor on both sides: where the mark is placed, to the text where it is printed; and where the text is printed, to the mark's location. I have an unique ID which I can correctly track on both sides. So I build anchors based on this ID: postnote.ID.mark and postnote.ID.text, and can get correct hyperlinks from the mark to text and from text to mark. If I used \phantomsection, it forces the anchor to be \Hy@MakeCurrentHrefAuto{section*}, so I loose this connection. True, I could store \hyperget{currentanchor}{} as you suggestes and pass it around. But, from my perspective, this wouldn't improve things, quite the contrary. Just an unnecessary complexity added to the code. And, as far I can tell, the fact that \hyper@refstepcounter calls hyper@makecurrent{<counter>} would also complicate things, in the absence of a stable \theH<counter> even for the case where the counter should be stepped.

This is the outline of the current use case I'm working on, and why I (think I) need to set the anchor manually, and thus need \Hy@raisedlink and which ultimately what led me to suggest \Hy@raisedlink be made public. Please consider it just in the interests of hyperref, and do tell me to "buzz off" and "go study some more", or "go ask somewhere appropriate", if that's the case.

Still, my only argument really is: if there is a public interface for manual anchor setting, shouldn't there be one to raise it too?

[u-fischer]

Hm. Assuming that ID is a counter. Then \newcommand\theHID{postnote.\the\value{ID}.mark} would produce your one anchor wouldn't it? And to get the other one you only need to swap the definition by \newcommand\theHID{postnote.\the\value{ID}.text}, which can be done with a simple \let.

[gusbrs]

Assuming that ID is a counter. Then \newcommand\theHID{postnote.\the\value{ID}.mark} would produce your one anchor wouldn't it? And to get the other one you only need to swap the definition by \newcommand\theHID{postnote.\the\value{ID}.text}, which can be done with a simple \let.

Not really, postnote is the "user facing counter", which needs not be unique. ID is an expl3 counter, which behaves differently from standard ones in some circumstances of interest. Of course, this does not mean I could not build a proper \theHID based on it. I wouldn't be able to pass it to \refstepcounter I presume, but I might be able to work around it.

Anyway, I guess it really seems a case for TeX.SX then, thank you for the suggestions and patience. And please feel free to close this.