Is documentation sufficient for show string substitution and function arguments?

Questions
,
1

I have a paper with many url links of the form

 #link("https://somewhere.wherever.org/some-long-directory/LzXsYW_wHYqpTZEjr_8N/interesting.html")[this article]

and want to be able to abbreviate the url in the text to make reading and editing the source easier. I tried to use a show rule to do this and it fails. That is,

#show "url001": "https://somewhere.wherever.org/some-long-directory/LzXsYW_wHYqpTZEjr_8N/interesting.html"
...
#link("url01")[this article]

does not work – the link resolves to “url001” and not the long mess. So it appears that string substitution via show does not take precedence over evaluation of the link destination.

Is this analysis correct? If so, should the show documentation reflect this?

(I solved my immediate problem by making a dictionary with the keys:

#let ud = (:)
#ud.insert("url001", "https://somewhere.wherever.org/some-long-directory/LzXsYW_wHYqpTZEjr_8N/interesting.html")
#ud.insert("url002", "https://forum.typst.app/t/is-documentation-sufficient-for-show-string-substitution-and-function-arguments/5948")

and a function to access it:

 #let ln(short,body) = link(ud.at(short),body)

to handle the extraction. The result is much more readable text

 see #ln(url002,[_the Typst forum_])

and a collection of urls that is easier to check with other tools.)

2

To me the behaviour makes perfect sense. A show rule that captures text should capture text inside the document. An embedded link is not text, so it should not be captured. If you want to capture links inside show rules, you could do something like this (though i’m not sure if I would recommend it):

#show link.where(dest: "url001"): it => {
  let fields = it.fields()
  let _ = fields.remove("dest")
  let body = fields.remove("body")
  link(..fields, "https://somewhere.wherever.org/some-long-directory/LzXsYW_wHYqpTZEjr_8N/interesting.html", body)
}

A better way is to just define your own variables:

#let url001 = "https://somewhere.wherever.org/some-long-directory/LzXsYW_wHYqpTZEjr_8N/interesting.html"

#link(url001)
3 Likes
3

This is why I asked if the documentation is sufficient – two people can reasonably interpret it in different ways.

I don’t think that your explanation is a makes perfect sense. The string that is being replaced is not an embedded link, it is simply a string. The link function explicitly accepts a string (or a label, location, or dictionary), so that has to be examined at the outset, and substitution seems a reasonable thing to do at that point when a string is found.

Actually, the dictionary I described is, for me, the better way. The dictionary can easily be expanded (as I have done in the actual document) to include other fields, for instance, the last date the URL was validated and the name of the screenshot/pdf in my files that holds a copy. A simple variable is not so flexible.

But the question here is about the documentation for #show.

1 Like