fix: make description consistent with link-external-filter example code

[mcanouil]

The pull request fixes an inconsistency in the example description, making it consistent with the example code.

Fixes quarto-dev/quarto-cli#10780

[soxofaan]

The "custom" in this example looks a bit weird imho. It's not a common url part. Why not make it a little more concrete and self-explanatory by changing it to be about www.quarto.org/docs or something alike?

And to be really nitpicky: I would also change the domain to something non-quarto, e.g. www.example.com, which is designed for exactly these kind of things

[mcanouil]

The issue was that it was not consistent. Changing "custom" to "docs" or "whatever" does not change/improve anything. Same as using example.com.

[soxofaan]

does not change/improve anything.

• changing /custom to /docs improves the familiarity and self-explanatory nature of the snippet (I've never seen /custom being used as top-level path components in docs)
• changing quarto.org to example.com makes it more clear that you have to put your own URL there, not the URL of the software you are using. The domain example.com is explicitly being defined for documentation purposes like this

[mcanouil]

example.com does not have pages beside index.html.

You seem to want to restrict the example to be what you know/expect rather that for it to be whatever regular expressions allows.
It's a regular expression, if "you" don't understand what it is, using example.com or quarto.org/docs in the example won't change anything.

Here, Carlos' comment applies:

The confusion can be solved by experimenting with the option, and understanding regexes are necessary to using them.

I won't make changes here until one of the maintainers makes a review.
As I said, the goal is was to fix the inconsistency and not to change the whole example.

[soxofaan]

Nevermind. I was just trying to help improve the docs based on my first hand experience trying to make sense of the example.
And I have plenty of regex experience, that wasn't even the issue to begin with.

[mcanouil]

To be clear, what I'm saying is that I don't want to make more changes without having the feedback of the maintainers first, not that your feedback is not valuable.

[soxofaan]

also note that this example is repeated at

quarto-web/docs/reference/formats/html.json

Lines 444 to 445 in 1d47eb8

	"name": "link-external-filter",
	"description": "A regular expression that can be used to determine whether a link is an internal link. For example, \nthe following will treat links that start with http://www.quarto.org as internal links (and others\nwill be considered external):\n\n```\n^(?:http:|https:)\\/\\/www\\.quarto\\.org\\/custom\n```\n"

which also has to be addressed I think

[cscheid]

which also has to be addressed I think

For everyone's sake, quarto-web/docs/reference/formats/html.json is autogenerated by tools/reference.ts, which is updated by quarto run tools/reference.ts, as described on our README.

So the workflow here is we first fix the schema files (that's quarto-dev/quarto-cli#10806), then we run the command above, and do a separate PR here with the results here.

[mcanouil]

Indeed for the reference pages.
Also why this PR only changes the hardcoded example.