`varioref` vs `zref-check`

[dbitouze]

While I understand the point of zref-check, I personally prefer the varioref automatic way of inserting contextual references. Is there any chance for zref-check to collaborate with varioref, just as cleveref does?

[gusbrs]

Hi @dbitouze ,

technically, there's no incompatibility between zref-clever/zref-check and varioref, and you can use them together.

But, yeah, I know that's not what you meant. And the problem is quite a fundamental one, and nothing zref-clever/zref-check can do anything about: varioref does not support zref, meaning it does not work with labels set with \zlabel.

One thing which is viable, is to set both labels with the same name (or have a convenience macro do it for you). Since the referencing systems are independent, you won't get duplicate labels out of that. But that may quickly become tedious, and does not seem a very pretty way to go.

Hopefully, you'll get used to the zref-clever/zref-check integration. I does allow you to reach the same kind of "end result", and is more flexible. In particular, you can get the reference type automated, which is the business of zref-clever and varioref can't give you. It can also handle multiple labels, etc. But, well, varioref is definitely a cool package, and zref-clever/zref-check do require a little more work and markup from the user. In sum, both have advantages and disadvantages. And they just belong to different independent referencing systems.

[jspitz]

I think what is needed to match @dbitouze's request would be a zref-clever command (or \zcref option) that simply outputs the currently valid contextual string rather than just checking one contextual option and either output nothing/a warning or the note if the option applies. This does not strike me impossible from a quick look.

Also, the strings that currently need to be passed via the note option could go to zref-clever's dictionary and localized. Something such as

pageref_following = {on the following page},
pageref_preceding = {on the preceding page},
pageref_facing = {on the facing page}

etc. Then let this command do the respectice checks via zref_check and output the string that is appropriate for the given context.

[jspitz]

Looking closer, though, I see that zref-clever does not do what I thought it does. But wouldn't it be possible to advise it, in the case a check fails, simply to omit the output rather than to just warn that the check failed? I was thinking about something such as:

\newcommand*{\zcvref}[1]{%
    \zcref[check=thispage]{#1}%
    \zcref[check=nextpage,note={on the following page}]{#1}%
    \zcref[check=prevpage,note={on the preceding page}]{#1}%
    \zcref[check=facing,note={on the facing page}]{#1}%
    \zcref[check=pagegap]{#1} on \zcpageref{#1}%
}

only fully integrated in zref-clever with all contextual options zref-check provides (and per-entry overrideable default localized note).

[gusbrs]

Well, @jspitz , that's a neat way to say "it's just a matter of reimplementing varioref for zref". :-)

And, no, varioref is not trivial at all. There's quite some more than just the basic functionality of \vref and, in particular, the looping issue is a tricky and fundamental one.

It is a matter of "someone" doing it, of course. But zref-clever/zref-check does offer equivalent functionality with a different concept which is more flexible, even when it is indeed less automated.

I get that you folks like varioref, I do too. But, c'mon...

[jspitz]

I understand that it might be (too) hard to do. The point is that nobody wants to check warnings over and over again and then re-edit strings manually.

[gusbrs]

About:

\newcommand*{\zcvref}[1]{% ...

It is not that simple, in this case, zref-check is of little use. For something of the sort to work, we'd need to retrieve the abspage property and really check the cases.

The point is that nobody wants to check warnings over and over again and then re-edit strings manually.

You don't need to do it over an over again. You can use option msglevel=obeydraft or obeyfinal to only get warnings when you are actually wrapping up your document. Anyway, it does require some work eventually.

[jspitz]

It is not that simple, in this case, zref-check is of little use. For something of the sort to work, we'd need to retrieve the abspage property and really check the cases.

OK, I see. Thanks for the explanation.

[gusbrs]

About the "over and over again", let me add something that may help. The use of the zref-clever/zref-check integration presumes a certain workflow and in that it is different from varioref with which you can just make the reference and forget it (unless it loops).

The basic envisaged workflow is that, at any time, you can make a reference with \zcref for some element for which you may want to have some contextual text added to it. So, you go ahead and make it "plain", but add the pagegap check to it: \zcref[check=pagegap]{fig:figure-1}. This reference will render always correctly, even if it is "less pretty" than what we may want it to be. So you don't have to worry about it, unless you want to. At a certain point, you choose to give finishing touches to your document, then you enable the zref-check warnings (by whatever means, using msglevel=obeydraft and dropping the draft option, for example). The pagegap check will tell you whether there's an opportunity to add some contextual text, you just have to take a look to those that fail the check, and see if you'd like to change something there. And any reference which passes the check, is already what you want. That's more or less the idea.

And you can do things with this structure which you can't do with \vref. Some examples. You can actually check (within limits) whether a float is actually "above" or "below" the reference, whereas with varioref you have to "know (!)" it. You also get the automation of the type, which varioref does not provide (true you can use \labelformat or cleveref). And, finally, if you so fancy it, you can choose the style of the reference and the contextual text case by case, which allows you to make some local fine tuning according to the situation.

[jspitz]

Yes, I understand the idea now. It is more or less a helper for manual context text (which presumes that a document is only output in one specific format). I can see why people might want to use that, although it isn't for me. I just thought that if it'd be possible to emulate varioref with zref-clever, this package would really be "your last reference package", as you indicate in the manual. It is still an awesome package, but a crucial bit is missing (for my own workflow, that is).

[gusbrs]

Hi @dbitouze and @jspitz , I had an interesting idea these days about this and decided to try my hands on it. The idea was: instead of attempting to replace varioref, why not try to build a wrapper around it? And so I did, and it appears to be viable. You can find a prototype at https://github.com/gusbrs/zref-vario.

This is barely out of the oven, so do expect rough edges. It also needs the current repo version of zref-clever. It offers a \z... counterpart to each of the main varioref user commands, each of which does some setup (customizing the varioref variables and handling label setting and extraction) then calls the varioref original. The only UI difference in these macros is that each receives a single optional argument, which can receive \zcref options, and vcurrent and vother which correspond to the optional arguments of their original counterparts (when they have it).

Comments are welcome. Specially if you are well acquainted with the varioref machinery, I'd love to know if you think this might blow in my hands. I'm still getting to know the internals better. I think I got all the handles right, but I'm still weary and yet to be really convinced this is a good idea. So, for the time being, this is yet to prove itself a sound basic concept.

[gusbrs]

After some massaging, some polishing and some testing, I think it turned out pretty good. So I went ahead and released it. It should be reaching you folks soon. I do hope you enjoy! :-)

[jspitz]

I do hope you enjoy! :-)

Be sure about that. Thanks for investing your time in this.

[hpvd]

since I'm also a big fan of intelligent full automation -setup and forget but always get a pretty advanced result- ++++1 on giving variorefs possibilities to clever-zref !

[hpvd]

just an addition:

of course it's nice to have the full control about naming of references and make each of them pretty unique. For lot's of people, the really big advantage of LaTeX is, that they "only" has to generate and write the content, while Latex cares for all the other things like numbering, toc, index, bib and also for the setting of the document Everything in high, always reproducible quality - even if the document format is changed.

Of course, always having the possibility to manually fine-tune everything is great, but IMHO the vision is that this fine-tuning is mostly done one time during setup of document and having to manually interact/control should be as unnecessary as needed.

In other places this "intelligent full automation" of the final mile becomes reality these days (2022) e.g. with the packages

• lua widow control which solves problems of widows in automatic fashion https://github.com/gucci-on-fleek/lua-widow-control
• linebreaker which solves many overfull boxes https://github.com/michal-h21/linebreaking
• fewerfloatpages https://github.com/FrankMittelbach/fmitex-fewerfloatpages
• well-known microtype which gives documents the final professional touch https://github.com/schlcht/microtype/

All this is not reachable with any other tool in automatic fashion, only with good old but pretty up-to-date Latex.

Maybe (hopefully!) zref-clever will support this direction further by offering many advanced possibilities of z-ref to be used in intelligent automatic -sometimes magic- ways :-)

Many thanks for your great work!

[gusbrs]

@hpvd Thank you for your kind words. :-)