[Feature Request] Per RefType options (`cap` and `abbrev`)

[niluxv]

Hi. First of all thank you for this great LaTeX package.

I would like to set default options, in particular cap and abbrev, on a per RefType basis (so the per RefType setting overrules the global setting, but can still be overruled locally by passing options to \zcref). When abbreviations can be easily enabled or disabled on a per RefType basis, the default dictionaries could also be expanded with many more common abbreviations like Theorem -> Thm, Proposition -> Prop, Definition -> Def. etc.

I know that a simple workaround (if no local overwriting of the settings is necessary, which is rarely needed anyway) is to only define the necessary forms, e.g. for cap if a RefType should always be capitalised only define the capitalised form, and for abbrev turn on the global abbrev option and only define abbreviated forms for those RefTypes where one wants them. But per RefType cap and abbrev options would be more flexible.

[gusbrs]

Hi @niluxv , thank your your interest and for your suggestion.

It is in general not trivial to extend the global/local options to the reference type level. The ones that can be set for the type are "dictionary-like", which is not the case of cap and abbrev, which are booleans. This means that neither cap nor abbrev would ever be in an "unset" state, which would defeat the way the precedence rules for the different levels work.

As usual, there is likely a way, but in this case it would imply changing how these options work at the user level (booleans would not suffice). So I would only consider venturing this route for ponderous reasons. And, as far as I can tell, while the suggestion you are making would no doubt be a nice convenience, the end result is achievable with the current structure. Indeed, what you describe as a workaround, I'd call the proper way to handle it (at least as far as my initial intentions went, which does not mean it is set in stone ;-). But could you elaborate the use case you have in mind, and what you are trying to achieve? Do you see a generally useful setup which is impossible to reach by setting the corresponding name forms?

[niluxv]

Yes, you are correct in that everything that is generally useful can be achieved by overwriting the entire (or a large part of the) (default) dictionary :slightly_smiling_face:

One generally useful setup which right now requires overwriting large part of the default dictionary is the following. In English (and Dutch) it is conventional to always capitalise words like Theorem, Proposition, Definition, Lemma, Example, etc. when they are in front of a number to reference a theorem/... (in such cases the word is used as a proper noun). But some words are not capitalised (even when used as proper nouns), e.g. page and equation. Without being able to conveniently set capitalisation on a per RefType basis, it would probably be a good idea to change the default english dictionary to make theorem, etc. always capitalised.

The other generally useful style I can think of is to abbreviate many more words than in the default English dictionary. I.e. Theorem -> Thm etc. It is not a good idea to add these abbreviations to the default dictionary right now though, since anyone will want equation to be abbreviated to eq. (or even nothing, just the eq. number between parenthesis) except when it is the first word of the sentence. This requires abbrev to be enabled globally.

So the point is, there are several common styles but the global options cap and abbrev don't allow to switch between these common styles as there are always some exceptions.

[gusbrs]

Yes, you are correct in that everything that is generally useful can be achieved by overwriting the entire (or a large part of the) (default) dictionary :slightly_smiling_face:

Well, my expectation is that most common uses would not require such a wholesale redefinition of the dictionaries. But, for (hopefully) exceptional use cases, if much of the dictionary would have to be overridden, probably a saner way to deal with it would be to create a custom language (e.g. myenglish), and map the babel/polyglossia language to that. This way you can only define a minimal set of used things and not have to take care of the whole dictionary set of types and names.

One generally useful setup which right now requires overwriting large part of the default dictionary is the following. In English (and Dutch) it is conventional to always capitalise words like Theorem, Proposition, Definition, Lemma, Example, etc. when they are in front of a number to reference a theorem/... (in such cases the word is used as a proper noun). But some words are not capitalised (even when used as proper nouns), e.g. page and equation. Without being able to conveniently set capitalisation on a per RefType basis, it would probably be a good idea to change the default english dictionary to make theorem, etc. always capitalised.

I'd expect that to be catered for by cap=true, why the exception for "page" and "equation" here? Is this exception really a common requirement? If it is, it is true tough that it may be tedious to set this up with the current structure. Because we cannot set cap=true, and override just page and equation to lowercase, for we'd break capfirst for them like this.

The other generally useful style I can think of is to abbreviate many more words than in the default English dictionary. I.e. Theorem -> Thm etc. It is not a good idea to add these abbreviations to the default dictionary right now though, since anyone will want equation to be abbreviated to eq. (or even nothing, just the eq. number between parenthesis) except when it is the first word of the sentence. This requires abbrev to be enabled globally.

That is actually the main reason why the dictionaries contain very few abbreviations, and well established ones at that. So that using abbrev globally provides a reasonable default set. But even if you don't want some of the default ones, it is easy to set it up. Just enable abbrev and override the ones which you don't want, which should be few since there are only a few defined ones by default.

[niluxv]

why the exception for "page" and "equation" here? Is this exception really a common requirement?

I don't really know. I just haven't ever seen page or equation capitalised for an other reason than it being the first word of a sentence. "Chapter 2 begins on Page 9" looks really strange...

Not capitalising eq. is a hard requirement for me at least. The workaround is to make the capitalised abbreviation of equation eq. and pass noabbrev when at the start of a sentence, since I don't want a sentence to start with an abbreviation anyway. (I also had to patch my cleveref setup because people complained about the capitalisation.)

[gusbrs]

Point taken. Indeed, it did bother me that capfirst and noabbrevfirst introduced an asymmetry for the use of cap and abbrev. Given it is quite tricky to extend options to all scopes, I was hopping that I could get away with setting the type names appropriately, but you are right, it becomes too cumbersome even for reasonably common requirements in the case of these two options. Now I've extended the setting of cap and abbrev to both \zcRefTypeSetup and \zcLanguageSetup (and dictionaries), so we have full flexibility in setting them, and the asymmetry does not matter anymore. Thank you for suggesting this.

With the latest changes, you can have something like:

\zcLanguageSetup{dutch}{
  cap=true,
  type=page,
    cap=false,
  type=equation,
    cap=false,
    abbrev=true,
}

[niluxv]

The new mechanism works great! Especially being able to also set these language specifically is very nice (and I hadn't even thought about that possibility when I opened this issue). Thanks a lot!

[gusbrs]

I'm glad you are enjoying it! :smile:

And, a coincidence, I was about to leave a comment here today. For I've been playing with varioref and found out that \vnameref actually does pretty much what you had requested. A \vnameref prints something like "Section 2 on page 5", the main reference capitalized, the page not. So that's a good point of reference for the practice.

About extending it to \zcLanguageSetup it made sense. One reason for which I had restricted it originally was technical, it is a boolean. But, once I had set up things to treat it at the reference type level, it was an easier step to extend it to the language scope too. And, for other reasons, I had to revamp the options infrastructure since the last release, and I moved from using property lists to individual variables. One side effect of this is that we now have somewhat better support for using different data types for options in multiple levels, booleans included. So this is better paved now.