DOCBOOK: Re: Markup for Protocol Names

["Matt G." <matt_g_ at hotmail dot com>]

>From: Trevor Jenkins <trevor.jenkins@suneidesis.com
>Subject: Re: DOCBOOK: Markup for Protocol Names
>Date: Mon, 18 Feb 2002 11:50:13 +0000 (GMT)

>On Mon, 18 Feb 2002, Holger Rauch <Holger.Rauch@heitec.de> wrote:
>
> > How are protocol names (such as "HTTPS") supposed to be
> > marked up?
>
>Don't know what others might use but my preference is to use
>
>         <token>HTTPS</token>

I definitely wouldn't use 'token'.  A token is supposed to be a logically 
atomic unit of information.  Examples of this are reserved words, operators, 
variable names, and '{' braces, in the C programming language.  By "atomic", 
I mean that a token is logically indivisible, in a given context (e.g. you 
can brake the token 'return' into smaller groups of letters, but if you're 
trying to parse a C program, it isn't meaningful to do so).

I would use 'systemitem'.  Or, failing that, 'phrase'.  In either case, the 
'role' attribute should probably be used.  For example:
	<systemitem role="protocol">HTTPS</systemitem>
or
	<phrase role="protocol">HTTPS</phrase>


Now, perhaps you're thinking "gee, this is pretty darn verbose".  If so, 
don't feel ashamed of yourself, however.  Verbosity has disadvantages: the 
more work you make it for someone to say/do something, the less likely it is 
that they will.  This leads to inconsistent markup.  Furthermore, the 'role' 
attribute is an open-ended hook.  Unless you customize your stylesheets to 
allow only certain values (but if you're doing this, why not just add a 
protocol element?), or check for non-sanctioned values in your processing 
application (i.e. stylesheets), there exists the possibility that someone 
may misspell "protocol", which will cause semantic loss of that instance.

Another issue to consider is that perhaps a 'protocol' element one day gets 
added to the DocBook vocabulary, or you use a customization layer with it.  
It seems troublesome to go back and change all the documents that were 
previously written, to maximize the advantages of having this element (which 
may prevent you from ever getting around to adding it).

"What's to be done about all this?", you may ask.  I have a solution that I 
devised in a markup language with much more ad hoc semantics (dare I say 
it...?  LaTeX): use indirection.  Indirection allows you to centralize the 
translation, which enhances manageability and consistency.  Specifically, I 
recommend that you define a general entity, and reference it for every case 
in which you want to mention HTTPS:

    <!ENTITY Https "
        <systemitem role="protocol">HTTPS</systemitem>
    ">


Then, in your document, you can use it as:

    At the expense of host-side stream encryption and per-transaction
    key generation, as well as client-side decryption (requiring a
    compatible browser), &Https; enables secure web transactions to
    be performed over insecure networks.


Now, not only is it easy to type, but if you make a spelling error (aside 
from leaving off the "s", perhaps), the parser will flag it as an error.  
Furthermore, you've centralized this definition, so that if the name of the 
standard, or the tags you want to use, ever change, you only have to make an 
edit in one place.  Putting this definition in an external parameter entity 
can allow you to share this definition between multiple documents.

I usually group multiple such entity definitions, by subject matter, into a 
external parameter entities.  That way, I benefit from reuse, centralized 
management, and consistency across multiple documents and authors.

One thing to watch out for is naming conflicts (especially since the first 
definition of an entity will silently override any subsequent ones).  
Therefore, I break down the problem by prefixing each entity name with a 
prefix that is common to the file in which it's defined.  Each file then has 
a unique prefix.  (You may recognize this technique from C or other 
programming languages that have no formal mechanism for precluding namespace 
collisions.)


Matt Gruenke


_________________________________________________________________
Join the world’s largest e-mail service with MSN Hotmail. 
http://www.hotmail.com