Open ChristianGruen opened 1 month ago
I don't think there's an interesting technical distinction. My impression is that we prefer $href
when the thing being identified is likely to be a page that exists on the web. This leverages the experience of users familiar with <a href=...>
. We tend to prefer $uri
when the identifier is just an identifier and may not have a useful hypertext representation on the web, things like collation identifiers.
If users are attempting to divine meaning from the argument names and finding the differences confusing, I won't object to using one name consistently. Whether that would be a net win depends, I guess, on whether more or fewer people will be confused by doc($uri)
because they have an immediate connection to href
but not uri
.
I always use url
. everyone has heard of urls. But I guess url is not used in Xpath
Pedantically, url
is a misnomer. It strongly implies that the things identified have a location
, or can be located, which is not true of entirely abstract things that might be identified (like collations, for example). Back in the day, the distinction between URIs that referred to information resources that could be located by doing a GET request on a server and URIs that refered to abstractions like "peace", "love", and "understanding", not to mention things that (some would argue) are not information resources, like the corporeal form of the individual who wrote this comment, was a subject of intense debate.
There are at least two different schools of thought:
The name is sound and smoke, / beclouding Heaven's glow
— Goethe: Faust (advocating for tolerance of differently named attributes)
Consistency over Correctness
— Internal rule at McKinsey & Company (advocating for same-named attributes even if some people argue that they have subtly differing meanings)
If different attribute names have been established for (purportedly) similar or maybe same things, I’d recommend to quench it with an editorial note that states that these are, by and large, the same things, and, mostly for historical reasons, one of them is called $uri
and the other one is called $href
.
The name is sound and smoke, / beclouding Heaven's glow — Goethe: Faust (advocating for tolerance of differently named attributes)
;-) …and it was introduced with “Feeling is all”.
mostly for historical reasons, one of them is called
$uri
and the other one is called$href
.
Fortunately, we can ignore history this time, as the parameter names have become relevant only recently for the 4.0 feature to explicitly address a parameter in the function call: fn:doc(href := 'https://faust.org')
. Once we choose names, we cannot change them anymore in future versions.
Your note was helpful. I looked up the 3.1 spec, and I noticed…
fn:doc($uri)
fn:collection($arg)
…that both parameter names were changed. However, the overall naming scheme is definitely more consistent now.
My personal preference would be McKinsey’s one (in addition, the result will still be correct).
I was asked about the difference between the function parameter names
$href
and$uri
…fn:doc($href)
(“Retrieves a document using a URI supplied as anxs:string
…”);fn:unparsed-text($href)
; othersfn:collection($uri)
,fn:uri-collection($uri)
; others…and I couldn’t give a convincing answer. At least in BaseX, both
fn:doc
andfn:collection
can be used interchangeably to address single resources (but things change when the target contains multiple resources).Would it be reasonable to rename
$href
to$uri
, or are there reasons why we need to differ those two?If we rename the parameter,
fn:resolve-uri
may be the only function using$href
(maybe even here,$uri
could work?).