Re: DOCBOOK: URI/URL markup in DocBook

[Michael Smith <smith at xml-doc dot org>]

Elliotte Rusty Harold <elharo@metalab.unc.edu> writes:

> Currently the enumerated systemitem classes include the following
> network related info:
> 
> systemname
> domainname
> fqdomainname
> groupname
> ipaddress
> username
> etheraddress

Actually, the list has gotten quite a bit longer. The enumerated
values in the 4.2CR3 DTD are:

  constant
  event
  eventhandler
  domainname
  fqdomainname
  ipaddress
  netmask
  etheraddress
  groupname
  library
  macro
  osname
  filesystem
  resource
  systemname
  username
  newsgroup

> I have encountered a frequent need for one more:
> 
> url
> 
> Note that this is not necessarily a clickable link like the ulink
> element. Rather it is a literal URL printed in text, such as
> "Sun's home page is at
> <systemitem class="url">http://www.sun.com/</systemitem>."
> 
> I have also encountered a need to distinguish different kinds of
> non-resolvable URLs, specifically:
> 
> XML namespace URIs
> SAX feature names
> SAX property names
> JAXP feature names
> SOAP Actions
> RDDL purposes
> RDDL natures
> 
> Doubtless there are others, and more are likely to be invented in the
> future.

But I wonder how many non-language/API/protocal-specific classes there
might be. I think it's unlikely that the ones you've listed above
would ever be added as "off-the-shelf" enumerated values to the
standard DocBook DTD. I'm not saying that's what you're suggesting --
just wondering how many "general" classes of URLs there might be.

> For the moment, I've been using the class attribute to separate
> these. However, I think the time has come to add at least a url role
> to systemitem, or possibly skip that step completely and go straight
> to a url element.
> 
> Questions:
> 
> 1. Do we really need a uri element? or separate url, uri, urn elements?
> 
> 2. Should this element have some sort of purpose or role attribute that
> identifies the type of the URI? For example,
> 
> <uri class="url" role="namespace">http://www.w3.org/TR/2001/XInclude</uri>
> <uri
> class="urn">urn:publicid:%2B:IDN+example.org:DTD+XML+Bookmarks+1.0:EN:XML</uri>

If the TC decided to add it, as far as the choice between implementing
it by adding it as a new value on the class attribute for Systemitem,
or by adding it as a new element instead, I'm personally inclined to
think it might be better added as a new element -- especially if other
users have the same need you mention: to distinguish different classes
of URLs from one another (but also in part because I wonder what the
best use of Systemitem might really be[1]).

I can also see a URN element being useful, though it seems like there
would be less of need to distinguish different classed of URNs from
one another.

But if the TC were to decide to implement specific URL and URN
elements, would there really be any need for a separate URI element
also? (Or a need for a URI class value on Systemitem, if the TC
decided to do it that way?)

  --Mike



[1] I personally wonder how intuitive Systemitem is to new DocBook
    users; I wonder how many new users, when they're trying to select
    an appropriate element to mark up something, think to check the
    list of class values on Systemitem.

    I think Systemitem can be more useful to experienced DTD
    implementors as a "semantic extension" element in a
    subset/customization or "authoring DTD", where they might want to
    "specialize" Systemitem in ways very specific to their particular
    organization's documentation needs.