Subject: Re: DOCBOOK: URI/URL markup in DocBook
Elliotte Rusty Harold <email@example.com> 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). 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  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.
Powered by eList eXpress LLC