Custom command references

[jneug]

The @@ommand() syntax is a nice addition. Maybe the final display of the reference could be passed to the style, to allow customization of the final reference?

For example, I integrated tidy with my template for package manuals Mantys and would like to format all commands in the manual with the same #cmd() function.

It could be done with a new function in the style called show-function-reference( location, fn ) or similar.

[Mc-Zen]

Hi, this will definitely be possible.

Did you try achieving this with show rules for links? Maybe you can try that out but if this is not sufficiently flexible we can certainly add this feature.

[jneug]

I experimented with some show rules, but detecting if a link is a reference to a command or to something else, is not very robust (at least the ways I could think of). This often times lead to crashes, because of recursive show-rules.

I think a style function would make this much more flexible.

[Mc-Zen]

You could pick the field dest from the link and make use of the label-prefix that is prepended to each label created by show-module.

However, I agree that this is not extremely elegant and ... also I just noticed it really kind of does not work due to recursive show-rules

[Mc-Zen]

I have to see how to make it work best because the links are actually "interpreted" (the code for the link is inserted as text during parsing and eval'ed together with the docstring)

[jneug]

Couldn't you just insert a custom function like #tidy-cmd-ref() in the docstring, that in turn passes the link generation to the style (and maybe falls back to the default way)?

The function would need to be injected in the eval scope before parsing.

[jneug]

After thinking a bit more about this, it might be useful for future extensions to reserve a key like tidy-helpers or tidy in the scope, that is set to a module with helper function like this reference generator.

[Mc-Zen]

Couldn't you just insert a custom function like #tidy-cmd-ref() in the docstring, that in turn passes the link generation to the style (and maybe falls back to the default way)?

yeah, that was my first thought as well but it requires having the style available during the parsing process and currently it is only passed to show-module(). The descriptions are evaled in parse-module already to take this effort off the shoulders of people writing custom styles.

[jneug]

I see.

Maybe the easiest solution would be, to add a label to the reference links. Then the display could be changed with a show rule.

This would need a minimal change in line 213:

return "#link(label(\"" + parse-info.label-prefix + target + "()\"))[`" + target + "()`]<tidy-cmd-ref>"

[Mc-Zen]

Hi, today I found the ideal solution for this issue:

During parsing we create a link with some prefix prepended to the link text. During showing, a show rule is applied to all links that checks whether the link text contains the prefix and calls a custom function show-reference(dest, content) on it. This is all done internally.

This way we can get the style function that you wanted without needing to provide the style during parsing 🎆

Many thanks for all your suggestions and ideas!