Documentation does not explain how to select a style

[ysalmon]

Hello,
I have just discovered your package ; it is quite nice !

However, the PDF documentation seems to lack explanation about how to select one the style presented in Section 4.2. Indeed, this section details everything about styles, but not how to produce the different examples provided in Subsection 4.2.1.

This is extremely frustrating !

I resorted to looking into the source code of the manual and it seems that using \renewmenumacro{\keys}{shadowedangularkeys} for example works. Yet I am not sure if this is the correct way to change the style for displaying keys, as this command is only mentioned in relation with menu styles, which is also consistent with its name.

I think the documentation would be improved by adding a new Subsection just before current Subsection 4.2.1 with title "Selecting a style".

[tweh]

Hi,

you’re right, this isn't well documented and if I find some time I’ll take a look to improve the manual.

And your guess is right

\renewmenumacro{\keys}{<style>}

is the way to go. An ”menu style” ist meant in a broad meaning here. Actually the package doesn’t differentiate between menu, keys, paths or whatever. It is just a sequence of items with some styling for each item (depending ion the position in the sequence).

[thymaro]

I had the exact same problem. I was skimming the manual to see what I was doing wrong when selecting the style. I had to comment out the style specification in my preamble, because I couldn't get them to work and I'm not very fluent in tex-package-sourcecode. I am glad to having found this thread, but it should really be in the documentation. 😜

[ysalmon]

I went to report this, only to remember that I had already !

The interface to specify a style, besides being undocumented, is very counter-intuitive.

One tends to try

\usepackage[<style>]{menukeys}

and

\usepackage[style=<style>]{menukeys}

[Skillmon]

@ysalmon I could provide such options, it shouldn't be too difficult. Does the following interface sound good to you?

For each of the default macros provide a key accepting the different styles:

• option menus accepting the values default, rounded, and angular
• option keys accepting the values rounded, shadowedrounded, angular, shadowedangular and typewriter
• option paths accepting the values default, withfolder, withblackfolder, hyphenate, hyphenatewithfolder, hyphenatewithblackfolder

Feel free to suggest a better interface if you can think of something and I'll see whether it's possible to implement it.

[ysalmon]

I am not so sure because this would only work for the default available styles.

In fact, everything would make more sense if the \renewmenumacro command was called \setmenustyle or something like that.

This is a naming convention and documentation problem rather than a functionality problem.

More generally, the documentation is bizarre : it tells us how to define new styles (a feature for advanced users), it explains the source code of the package (which is only interesting to people who might want to fork it), but it does not tell what a user discovering the package should type in order to get the sample outputs of section 4.2.

This is true for setting the style, but also pertaining to the + symbol between keys.

When I set \renewmenumacro{\keys}{roundedkeys} and give \keys{\ctrl+c}, I get a single rectangle with ctrl+c within it, not two rectangles separated with a +. And this is confusing, because obviously ctrl+c is two keys, not one, and because section 4.2.1 shows output with multiples rectangles separated by +. So I wonder how this output was obtained.

[tweh]

Hi guys,

I’d say that this in fact is documented in section 4.4.2 Defining or changing menu macros. So maybe the documentation is bad but complete ;-)

I’d rathe not use package options for changing the styles as – like ysalmon said – this would only work for the predefined ones.

Regarding your concern about the naming convention: Since the \(re)newmenumacro (re)defines a new macro it would be wrong in my eyes to rename ist to simple something like \changestyle.

However as this problem just seems to be to find the solution I’d suggest, we add something like the following in the documentation right before presenting the styles:

---

4.2.1 Predefined styles

The package offers some predefined style to be used with existing and new menu macros. To creat a new one with a style you can add

\newmenumacro{\mymenus}{roundmenus}

to the preamble. To change the styl of an existing macro you can use

\newmenumacro{\mymenu}{roundmenus}

instead. Pleas note that this might also changes the separation character. See section 4.4.2 for more details on how to (re)define macros.

[tweh]

This is true for setting the style, but also pertaining to the + symbol between keys.

When I set \renewmenumacro{\keys}{roundedkeys} and give \keys{\ctrl+c}, I get a single rectangle with ctrl+c within it, not two rectangles separated with a +. And this is confusing, because obviously ctrl+c is two keys, not one, and because section 4.2.1 shows output with multiples rectangles separated by +. So I wonder how this output was obtained.

This is also explained in section 4.4. However it could be worth to discuss the order of the section, but again, I won't say that there is something undocumented. And pleas don’t complain about the fact that the implementation is also documented. You don’t have to read this part, but it’s common sense that this should be documented ;-)

[tweh]

PS: The thin with the separator is also explained in 4.1 so at the very beginning and before talking about the styles. See page 5 and footnote 4. So maybe you could expand on how you think this ist not documented …

[ysalmon]

I am not complaining ;-) It is always good to document code — but that is another story, because the user of some software or package is not concerned with the code, only with the interface.

Thank you for pointing out the relevant parts of the documentation. I think I finally understand what had been bothering me.

The notion of style you are using is not the same as the one in eg. TikZ or beamer (which is odd in part because if I understand correctly this package relies on tikz). In TikZ, changing the style of an element does not involve defining or redefining a macro : the predefined macros fetch the needed styles. This is also the case with eg. CSS : you use it to style preexisting elements, you do not redefine elements to give the a style.

This is why I would never have thought about looking at a part of a documentation pertaining to (re)defining macros in order to choose the style of the output : section 4.4.2 is about defining or changing menu macro, but when trying to apply a style, this is not what I have in mind.

While this way of doing things makes sense once you get it (I think it is somehow similar to how theorem styles work in most packages), it does not seem consistent with the way color themes are managed (which is more beamer/tikz-like) ; it also has the bizarre consequence about the separator : even though the separator for \keys is + by default, I need to restate it explicitly if I \renewmacro it, because for that command, the default separator is ,, and this even if I was only concerned with changing the appearance of the keys.

I hope I managed to convey more clearly what I previously found unclear ;-)

[Skillmon]

@ysalmon of course a .style in TikZ redefines a macro, that's just not transparent to the user...

@tweh of course this is documented (which is why I only addressed the suggested interface request of @ysalmon), but I should've pointed it out in the first place... And I like your suggestion of adding a brief introduction to \(re)newmenumacro before showing the different styles, and I think with this the documentation will be much clearer and the confusion as described by @ysalmon would be avoided in the future.

[ysalmon]

Yes of course ; but the fact that setting a style involves changing macros internally is not a concern for the user : semantically, this is not the same concept at all to him/her. In the same fashion that some other features of some packages involve changing catcodes internally : the intent of the user when invoking such features is not to change catcodes, and they should not be concerned with that — it is a shortcoming of TeX that they sometimes have to.

[tweh]

@ysalmon thanks for the clarification. Now I got what you mean :-)

For me as a non-native “style” means the appearance of something and thus this wording. I see your pint that there is a differnce in TikZ and CSS where object and their style are somehow separated. But for menukeys I see no advantage in this. Otherwise it would require a greater change in the interface, to something like

\newmenumacro{\menu}{
   style = rounded,
   separator = >,
  color-theme = black,
  …
} % 'classic' would be to have these arguments switched, I guess …

However even with this change I won’t say that \(re)newmenumacro is a wrong wording. Since wie deal with clerical TeX macros in this case other than in TikZ where you can’t redefine the object like a node itself but only its style. I hope to be clear …