OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Subject: Re: DOCBOOK: Re: Markup for Protocol Names

On Wed, 20 Feb 2002, Matt G. <matt_g_@hotmail.com> wrote:

I don't normally offer an opinion on markup issues but in this case I'm
glad that I did.

> On Mon, 18 Feb 2002, Trevor Jenkins <trevor.jenkins@suneidesis.com> wrote:
> >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. ... 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>

I've clearly misunderstood the use of token despite my having used it
extensively in my current documentation project. Your alternative (of
systemitem) is what I intended token to be used for.

> Now, perhaps you're thinking "gee, this is pretty darn verbose".

Nope. Not for me. Of course, a customer might think that the resultant
text is overly marked up but that merely exposes their ignorance of what
they have written.

Now to go change some 300 occurences of token (probably) to systemitem.
Thankfully your reply came in before I finished the project, which would
have meant changing some 1000+ occurences. Okay so search-and-replace is
cheap but some of these occurrences might perhaps be better as something
else. Time to go re-read TDG.

Regards, Trevor

British Sign Language is not inarticulate handwaving; it's a living language.
Support the campaign for formal recognition by the British government now!
Details at http://www.fdp.org.uk/ or http://www.bsl-march.co.uk/


<>< Re: deemed!

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Powered by eList eXpress LLC