-
Notifications
You must be signed in to change notification settings - Fork 4
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
zref-clever User Manual desperately needs examples of usage #8
Comments
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 |
gusbrs,
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, gusbrs ***@***.***> 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 <#8 (comment)>, 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
|
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"... |
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, gusbrs ***@***.***> 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 <#8 (comment)>, 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
|
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'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. |
+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. |
A useful addition would be examples which highlight the advantages of \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} |
Ok, vox populi. I have added to my todo list to add a " However, @dbitouze , regarding comparisons with 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. |
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 |
It sounds like you'd be interested in #9. I'd say this is as far as I'm willing to go with a comparison. |
In response to users' demand in issue #8.
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
The text was updated successfully, but these errors were encountered: