Expandable \pageref. Safety, potential risks, compatibility with PDF management - TeX - TopAnswers

TopAnswers TeX

टेक्-मराठी

Expandable \pageref. Safety, potential risks, compatibility with PDF management

Code Review

add tag

निरंजन

I need to have page references expandably. You can check the following MWE that shows my current attempt:

```
\documentclass{article}
\usepackage{hyperref}

\ExplSyntaxOn
\cs_new:Npn \__tmp_page_ref:n #1 {
  \cs_if_exist:cTF { r @ #1 } {
    \IfPackageLoadedTF { hyperref } {
      \exp_args:Nee \hyperlink {
        page. \exp_not:N \use_ii:nnnnn \use:c { r @ #1 }
      } {
        \exp_not:N \use_ii:nnnnn \use:c { r @ #1 }
      }
    } {
      \exp_not:N \use_ii:nnnnn \use:c { r @ #1 }
    }
  } {
    \textbf { ?? }
  }
}

\cs_gset_eq:NN \exppageref \__tmp_page_ref:n
\ExplSyntaxOff

\begin{document}
\section{foo}
\label{foo}

\exppageref{foo}


\end{document}
```

I wanted to know if this is a safe approach to take? Can there be any clashes with other things that deal with label-ref things? Especially tagged PDF and PDF management.

---
Edit: As per Ulrike's suggestion, the `exp` module name and `\tl_set:Nn` were discarded.

comments

transcript

निरंजन replying to Skillmon

@Ulrike @Skillmon I think I understood where I was making the mistake. I will recheck my code and get back. I will probably write another post. Sorry for all the noise and thanks to both for being patient with me.

निरंजन replying to Ulrike Fischer

Hmm, so you mean I should just save the page numbers and use hyperlinks later? Hmm, I think I had tried something along these lines, but it failed somewhere. I will check my code again to see if that's doable. Thanks.

Skillmon

@निरंजन I suspect this might be an XY-problem. What exactly are you trying to do? Why do you think you need this expandable access to page numbers while still creating links?

Skillmon replying to निरंजन

There are two different use cases that can't be both fulfilled with the same macro:  
  
1. Producing a linking reference in text (use `\pageref` for that)  
2. Programmatically accessing the page number set by a label (use either `refcount`, `\@kernel@pageref@exp`, `ltproperties`, or your `\exppageref` with the `\hyperlink` part removed from it for this).  
  
If you really wanted to fulfil both needs in the same macro you'd have to somehow deduce whether you're in an expansion context or not, which is not generally possible in TeX (one can check whether one is inside a `\csname`, so you could limit yourself to `\csname`-expansion tricks like `\csname @empty\expanded{\endcsname#1}` which would fully expand `#1` with `\ifincsname` being true -- however this would mean you'd always have to use some special code to trigger that expansion mode, which is basically the same as using another macro, so why bother).

Ulrike Fischer

sorry but it is not understandable what you are trying to do. In your code you store a list of page numbers but why do you want to add a link there?   A link is only needed when you *use* the page number. Side remark: do not test 100 times if hyperref is loaded. Do that once and then define an internal link-command that is either hyperlink or does nothing.

निरंजन replying to Skillmon

> > Where did you show us that `\pageref` doesn’t work for you?  
> 
> (Here:) First I tried `\edef\foo{\pageref{foo}}` and I was expecting `\pageref{foo}` to “expand” and produce n (the page number, e.g., 2). I guess I was using the term expansion incorrectly here, what is the correct word? Anyway, the definition of `\foo` didn’t contain n. Instead it was still `\pageref{foo}`.
  
But yes, as you show, even mine is not expanding as I expected it to. I don't understand two things.

1. I had used `\exp_args:Nee` in my code, why did it not protect `\hyperlink` from `e`? To be even more sure, I used `\exp_args:NNee \exp_not:N \hyperlink { link } { text }`. Even that didn't work. Why? Is there any way for `e` to see `\hyperlink` as something that shouldn't blast.
2. It didn't work with `refcount` either (as I expected). Are you simply saying that a hyperlinked thing cannot be used inside `e`, so what I am trying to do is essentially not achievable. I will get non-expandable implementation of this only. If that's the case, then okay, I should change the question and the part related to expandability can be removed, but the code review can still happen as I want to use this in a public package.

Skillmon replying to निरंजन

Where did you show us that `\pageref` doesn't work for you?  
  
Example demonstrating the difference: Try doing `\int_set:Nn \l_tmpa_int { \exppageref{foo} }` with and without your addition of `\hyperlink`.

निरंजन

@Skillmon @Ulrike kill me, but I still don't get the difference. Since you know the use case very well, can you demonstrate with an example where you expect things going wrong? Also, I showed you why `\pageref` didn't work for me. Can you show how one can use it and yet achieve the desired results? I am unable to produce such an example.

Ulrike Fischer

as skillmon wrote: the code in refcount and the definition used by `\@kernel@pageref@exp` in the kernel, is expandable so you can do `\edef\blub{\@kernel@pageref@exp{label}}`. But you added a hyperlink, and that will produce a link but with it the command no longer works in an edef and also no longer produce a pure number.

Skillmon replying to निरंजन

Your code isn't fully expandable since you're trying to create links. But the aim of making something work inside `\edef` is expandability. So something which returns the final result inside `\edef\foo{\bar}` is called expandable. That's why I said "calling that 'expandable' is correct".  
  
The terminology was correct, that doesn't imply that your implementation fulfils the goal of being expandable.  
  
Your code does create working links, but you couldn't use your code any longer where TeX expects a number for instance. What you now have is a custom implementation of `\pageref`.  
  
Distinction is exactly that:  
- you want to create a link: use the unexpandable implementation (`\pageref`)  
- you need to access the page-value of a reference expandably because you need it for calculations or whatever: use the expandable implementation  
  
Regarding implementing yourself: I can understand that. And the issue won't be `\use_ii:nnnnn` changing, but the structure of labels changing (which did happen in the past, but is highly unlikely to happen again since the current specification of them is extensible).

निरंजन

Just for you to see the actual use case, you may take a look at `linguistix.dtx` (v0.8): line number 3338-3376. In PDF, it's on page 45. It is released and available in a recent TeX Live. It just doesn't have the code for hyperlinking which is a feature I am planning to add with the code in this post.

निरंजन

> For anything that should be used by others you have to make sure to stay compatible with any development in the kernel. You don’t have that responsibility if you use one of the established packages/solutions for such a task.

I don't see it as a problem. I enjoy staying in loop of recent developments.

निरंजन

> The thing with reimplementing package code is that the burden of maintenance shifts on to you.

Fair enough, but:

1. I don't mind taking the responsibility if it gives me better control. `refcount` uses dozens of `\expandafter`s which are tough to understand (to me as well as to the users of my code). OTOH, my code uses simplified l3 version of the same (which could be wrong, which is why I am posting for the code-review).
1. I don't see any reason for something as stable as `\use_ii:nnnnn` to change and just in case, let's say it does change, then it would be quite unlikely for me to miss it. Also, at the core, I really don't think my package is doing anything different than what `refcount` does. It is just doing it with a different syntax.
1. The joy of doing most things without needing other packages.

निरंजन

> For your use case I’d just strictly differentiate between programmatic (expandable) usage, and in text usage (with links).  

Sorry, I don't see the distinction. Please elaborate.

निरंजन

> However there are certain limitations on what you can do by expansion only (as said before, link targets for instance).

What I still fail to understand is my code _does_ produce correct hyperlinks whereas you and Ulrike seem to disagree. Is it accidentally working because of something else I am missing? Why does the code I present link to page.1 correctly?

निरंजन replying to Skillmon

> no, calling that “expandable” is correct.

Okay, so do we have two expansions? You first said my code is not expandable and here you are saying that it could be expanded. Which two types are you talking about?

Skillmon replying to निरंजन

no, calling that "expandable" is correct. However there are certain limitations on what you can do by expansion only (as said before, link targets for instance).  
  
For your use case I'd just strictly differentiate between programmatic (expandable) usage, and in text usage (with links). So just stick to `\pageref` in the document, but in some macro processing the result further use an expandable solution.  
  
The thing with reimplementing package code is that the burden of maintenance shifts on to you. For a one-off document this is no problem obviously (but why put the work into reimplementing stuff then?). For anything that should be used by others you have to make sure to stay compatible with any development in the kernel. You don't have that responsibility if you use one of the established packages/solutions for such a task.

निरंजन

@Ulrike @Skillmon, thanks for your responses. I think I am using the word expandable incorrectly. First I tried `\edef\foo{\pageref{foo}}` and I was expecting `\pageref{foo}` to "expand" and produce _n_ (the page number, e.g., 2). I guess I was using the term expansion incorrectly here, what is the correct word? Anyway, the definition of `\foo` didn't contain _n_. Instead it was still `\pageref{foo}`. So I started looking for other options and I encountered `refcount` package. I saw the code of the package and I understood its implementation, so instead of loading the full package, I decided to only write the macro that I needed. This is the background story. Now when I do `\edef\foo{\exppageref}`, it does have something like `\use_ii:nnnnn {1}{1}{}{}{}`. This is what I wanted to see. But now I want to hyperlink it too. For that, I was going to use `\hyperlink{page.\exppageref{foo}}{\exppageref{foo}}`. It does produce what I want. I just want to know if this is safe to do.

Skillmon replying to Ulrike Fischer

me neither :) And, yes, I know the kernel got the necessary functionality (and posted code with that under another question here). Also, I'd argue that `\@kernel@pageref@exp` (of which I wasn't aware of, I stuck to properties) is of the category of names that aren't to be used by authors.

Ulrike Fischer replying to Skillmon

refcount is not really necessary, the kernel contains an expandable version (`\@kernel@pageref@exp`), and  with ltproperties you get it too. But yes, this doesn't work with a link, but I don't see  why you would need a link in an expansion context.

Skillmon

Well they don't create a link, but that's impossible doing expandably anyways, as far as I'm aware.

Skillmon

@निरंजन, re: [your question](#question), Are you aware of the `refcount` package and its command `\getpagerefnumber` (or `\getrefbykey{<reference>}{page}{<default>}`)?

Ulrike Fischer

that is still not expandable, as \hyperlink is not expandable., if you try `\edef\blub{\exppageref{foo}}` it will error. Beside this it is completly unclear what you want to do. `\pageref` doesn't write to the aux-file, so redefining `\pageref` does nothing here.

निरंजन

I was wondering how the output was correct though. With the `\pageref` command, the page number was not written to the auxiliary file. But with my older code, it was okay. That's why I misunderstood it as expandable.

निरंजन replying to Ulrike Fischer

Sorry, my bad. I have corrected both the mistakes. Also, I had used `_protected` before, that also removed. I think this version should be fine?

Ulrike Fischer

beside this you shouldn't create commands with `\__exp` that is our module name.

Ulrike Fischer

? that is not expanable. Something that contains \tl_set:Ne never is.