zref-clever User Manual desperately needs examples of usage

[murrayE]

The User Manual needs considerable expansion written from the viewpoint of, especially, the new user, through inclusion of EXAMPLES of usage!

Its current focus seems to be more from the viewpoint of the author(s), as a reference manual that enumerates exhaustively all the options.

I'm a fairly experienced user of LaTeX, including of hyperref and cleveref, but still I find the zref-cleveref User Manual forbidding

[gusbrs]

Hi @murrayE , I thank you for your feedback, but that seems unfair. Indeed the manual tries to cover the options, this is intended. But the only shortcoming you mentioned, which is the supposed lack of examples, is simply not true: there's a whole section of "How tos", covering some use cases of configuration I thought would be common. Besides, the basics are the same as the standard referencing system: set a label (with \zlabel in this case), and make a reference (with \zcref). And that's about it, and that is covered in the short "User interface" section.

[murrayE]

Gustavo,

My purpose was not to criticize per se but to offer comment towards making the package more useable!

You are quite correct about the How-tos section beginning on page 22, which is useful.

But it would still help greatly to have some examples interspersed with all the detailed reference material on the preceding 21 pages.

The User Interface section gives no actual examples of what kind of options might be useful, or how.

In fact, to entice new users of the package to get started, the most effective approach could be to put some typical examples of usage first and then follow that by the reference material.

Murray

On 14 Feb2022, at 4:19 PM, Gustavo Barros @.***> wrote:

Hi @murrayE https://github.com/murrayE , I thank you for your feedback, but that seems unfair. Indeed the manual tries to cover the options, this is intended. But the only shortcoming you mentioned, which is the supposed lack of examples, is simply not true: there's a whole section of "How tos", covering some use cases of configuration I thought would be common. Besides, the basics are the same as the standard referencing system: set a label (with \zlabel in this case), and make a reference (with \zcref). And that's about it, and that is covered in the short "User interface" section.

— Reply to this email directly, view it on GitHub https://github.com/gusbrs/zref-clever/issues/8#issuecomment-1039571581, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABILR2NXZ7PONSV4NNJMRMTU3FWUNANCNFSM5OMRVRIQ. Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub. You are receiving this because you were mentioned.

—— Murray Eisenberg @.*** Mathematics & Statistics Dept.
Lederle Graduate Research Tower phone 240 246-7240 (H) University of Massachusetts
710 North Pleasant Street
Amherst, MA 01003-9305

[gusbrs]

A "typical" example is just something like:

\documentclass{article}
\usepackage{zref-clever}
\usepackage{hyperref}
\begin{document}
\section{Section 1}
\zlabel{sec:section-1}
A reference \zcref{sec:section-1}
\end{document}

But I don't think this would add much to the documentation. It is just the usual stuff. And it "not being there" certainly is no significant barrier to interested users, in my judgement. Indeed, I would argue that even if the How-tos are a little more elaborate, they also cover the need of supplying examples of what the most basic (and probably the most common) usage is.

And most certainly, it is not granted to say the User manual "desperately needs EXAMPLES of usage"...

[murrayE]

I see no reason not to include such a very basic example in the documentation: you never know what experience a potential user may have.

P.S. My interest in zref-clever is that, for a book-length project, I’ve been using hyperref + cleveref + crossreftools along with babel-french, which originally caused havoc with my use of colons in labels (e.g., thm:main, lem:first). This required at least two hacks offered on tex.stackexchange.com http://tex.stackexchange.com/ to get around babel-french's making he colon as an active character.

I was trying to see if zref-clever would eliminate the need for those hacks — on the principle that it is safer in general to use packages “as is” rather than hacked — and possibly allow an alternative to crossreftools for my purposes.

But with so few examples, I’m finding it hard to tell.

On 14 Feb2022, at 4:45 PM, Gustavo Barros @.***> wrote:

A "typical" example is just something like:

\documentclass{article} \usepackage{zref-clever} \usepackage{hyperref} \begin{document} \section{Section 1} \zlabel{sec:section-1} A reference \zcref{sec:section-1} \end{document} But I don't think this would add much to the documentation. It is just the usual stuff. And it "not being there" certainly is no significant barrier to interested users, in my judgement. Indeed, I would argue that even if the How-tos are a little more elaborate, they also cover the need of supplying examples of what the most basic (and probably the most common) usage is.

And most certainly, it is not granted to say the User manual "desperately needs EXAMPLES of usage"...

— Reply to this email directly, view it on GitHub https://github.com/gusbrs/zref-clever/issues/8#issuecomment-1039599033, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABILR2IT3DJA5EGI663MKETU3FZV3ANCNFSM5OMRVRIQ. Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub. You are receiving this because you were mentioned.

—— Murray Eisenberg @.*** Mathematics & Statistics Dept.
Lederle Graduate Research Tower phone 240 246-7240 (H) University of Massachusetts
710 North Pleasant Street
Amherst, MA 01003-9305

[gusbrs]

P.S. My interest in zref-clever is that, for a book-length project, I’ve been using hyperref + cleveref + crossreftools along with babel-french, which originally caused havoc with my use of colons in labels (e.g., thm:main, lem:first). This required at least two hacks offered on tex.stackexchange.com http://tex.stackexchange.com/ to get around babel-french's making he colon as an active character.

I was trying to see if zref-clever would eliminate the need for those hacks — on the principle that it is safer in general to use packages “as is” rather than hacked — and possibly allow an alternative to crossreftools for my purposes.

But with so few examples, I’m finding it hard to tell.

I'm glad you're interested in the package, and even happier if it happens to solve some of the problems you face. I do hope you find it useful. However, there are trade-offs, and you should ponder them. Do take a look at section 11 "Limitations". Also, depending on the nature of the project you are into, do read section 2 "Warning" and consider it carefully.

I see no reason not to include such a very basic example in the documentation: you never know what experience a potential user may have.

I'll keep your suggestion in mind but, for the time being, I think the "How-tos" section already covers sufficiently basic use cases. So I'm closing this one.

[hpvd]

I see no reason not to include such a very basic example in the documentation: you never know what experience a potential user may have.

+1 on this. Examples do always help. The more covering of different experience levels of users, the better for any kind of documentation (for both directions, from beginners to very very experienced users)

[gusbrs]

+1 on this. Examples do always help. The more covering of different experience levels of users, the better for any kind of documentation (for both directions, from beginners to very very experienced users)

The second how-to currently in the manual is the following:

\documentclass{article}
\usepackage{zref-clever}
\newtheorem{lemma}{Lemma}[section]
\begin{document}
\section{Section 1}
\begin{lemma}\zlabel{lemma-1}
A lemma.
\end{lemma}
\zcref{lemma-1}
\end{document}

It is simple enough, and it does illustrate basic usage. There is really no need to add a how-to on "making a cross-reference to a section". I do hope I'll be able to extend the How-to section one day, but more in the direction of more interesting examples, not in adding even more basic ones than the basic ones already there. The manual presumes basic knowledge on how to use LaTeX cross-references and will continue to do so, it does not intend to replace a "LaTeX Introduction" for which there are plenty and better sources.

[dbitouze]

A useful addition would be examples which highlight the advantages of zref-clever over cleverref. For instance, there's no obvious difference between:

\documentclass{article}
\usepackage{cleverref}
\newtheorem{lemma}{Lemma}[section]
\begin{document}
\section{Section 1}
\begin{lemma}\label{lemma-1}
A lemma.
\end{lemma}
\cref{lemma-1}
\end{document}

and:

\documentclass{article}
\usepackage{zref-clever}
\newtheorem{lemma}{Lemma}[section]
\begin{document}
\section{Section 1}
\begin{lemma}\zlabel{lemma-1}
A lemma.
\end{lemma}
\zcref{lemma-1}
\end{document}

[gusbrs]

Ok, vox populi. I have added to my todo list to add a "zref-clever for the impatient" section to the manual, and will do so when I have some time.

However, @dbitouze , regarding comparisons with cleveref, what I've tried to emphasize in the manual is that zref-clever can reach parity to the standard referencing system in terms of features. Or, at least, near parity, as much as the support for zref allows. And that's what the example you mentioned tried to capture. That's deliberate. I do think cleveref is a great package, I have been its user for several years, and zref-clever itself owes much to it, so I would not like to make the relation between the packages any sort of "contest". Even if, admittedly, this may make the path to information a little longer.

That said, if you have a concrete example (or examples) to suggest for the "How-tos" section within this spirit (that is, something which is interesting on its own), I'd be glad to consider it for inclusion. But, if you do so, please open a separate issue for it, and not revive an issue that was closed for due reason to add further (different) requests.

[dbitouze]

Thanks for considering!

About "contest", I understand. I rephrase: "A useful addition would be examples which highlight the differences between of zref-clever and cleverref."

About concrete example (or examples) to suggest, the point is that I hoped since a long time to have the time to study zref-clever in details, but I never succeed. And that's why it would be helpful to have a quick overview: it would help to read what follows :smile:. If I succeed and find useful examples, I'll open a new issue (sorry to use the current one but opening a new one for my addition would probably be considered as a duplicate).

[gusbrs]

About "contest", I understand. I rephrase: "A useful addition would be examples which highlight the differences between of zref-clever and cleverref."

About concrete example (or examples) to suggest, the point is that I hoped since a long time to have the time to study zref-clever in details, but I never succeed. And that's why it would be helpful to have a quick overview: it would help to read what follows :smile:.

It sounds like you'd be interested in https://github.com/gusbrs/zref-clever/issues/9. I'd say this is as far as I'm willing to go with a comparison.