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] | [List Home]

Subject: RE: [docbook] RE: Always use most specific markup?

I think your decision is reasonable for your situation.

We provide some editorial tools that allow an author to 
list all the instances of "element X," such as all the
filenames in a document to allow checking that the paths
are consistent and correct for the platform in question
(many of our products run on Windows, Linux, and HP-UX,
with different conventions for locations of the files on
each) or listing all the commands or functions that are 
referenced in a document (since names of them can change 
at the last minute and even though we encourage using 
entities for things like that it doesn't always get
done).  There are also some sophisticated indexing packages
that will collect all instances of a specified element and
can thus produce an index of all the text describing each
command (we do not have this in place but I have seen it --
I think I prefer human indexing, myself, but it takes time
and expertise).

However, unless there are tools that use the more specific
markup (either for editorial purposes or to provide improved
access in the published document for the user) the additional
effort of the precision in the markup is probably not worth
it.  We do have some writers who do more precise markup than
the tools actually use, some because the feel "it's the right
thing to do" and some because they feel we need better tools
that will use the markup and they want it in place for when
we do.  Either way, our minimum standard is what is required
but we do not punish anyone for being more precise.

Best Regards,
Larry Rowland 

-----Original Message-----
From: Lasse Kliemann [mailto:lasse-list-docbook-2009@mail.plastictree.net] 
Sent: Friday, June 12, 2009 1:48 AM
To: docbook@lists.oasis-open.org
Subject: Re: [docbook] RE: Always use most specific markup?

* Message by -Cavicchio_Rob@emc.com- from Wed 2009-06-10:
> Lasse Kliemann wrote:
> > Should one always use the most specific markup available? For 
> > example, sometimes it may be conceivable to use 'systemitem' 
> > instead of 'filename', 'envar', or 'function'.
> I don't think there's a yes-or-no answer to that question. It totally
> depends on the information you are marking up, and how it might be used.

Well, that's a "no" answer to my question then :-)

And that's what I was hoping for. It is not "forbidden" to to use 
general markup even if a more specific one is available, but it 
depends on the application which way to choose.

In an off-list answer, the following broader question was 
proposed as a basis for discussion: "should one use inline markup 
at all?" That made me think (not for the first time, though) 
about why I use inline markup. Here is a list of my most 
important applications of inline markup:

- Computer code, or strings from a computer system, in general.
  This, for one, is to distinguish computer code and language 
  "code". Computer code may contain the same symbols as are used 
  to construct sentences in a human language. These have to be 
  distinguished.  Example: a file name at the end of a sentence. 
  It must be clear whether the final '.' is to end the sentence 
  or is part of the file name. In plain text, I usually use 
  single-quotes for this.

  Another motivation to mark up a more complex piece of code is 
  to express that we have *one* piece of code, i.e., its parts 
  (or words) belong together. (This may be seen as a special case 
  of distinguishing computer code and language code, applied to 

  Docbook offers a vast collection of markups for this, including 
  '<code>', '<filename>', '<envar>', '<literal>', '<systemitem>'.

- Replaceable parts, usually required to explain usage of 
  commands, e.g., 'ls FILENAME'. In plain text, caps are often 
  used for this. Since this may be ambiguous, I prefer something 
  else whenever possible, e.g. italics.

  Docbook offers '<replaceable>' for this.

- Emphasis. In plain text, I usually use *this* or _that_.

  Docbook offers '<emphasis>' for this.

- Quotations. In plain text, I use double-quotes for this. 
  Docbook also offers something, I think it is '<quote>'.

  It would be conceivable to distinguish further: Quoting from a 
  document are quoting the spoken word. However, this may not be 
  so important for technical documentation.

- Word as a word. In plain text, I usually use single-quotes for 
  Docbook offers '<wordasword>'.

- Preciseness of a word or phrase. Either express that a word or 
  a phrase is used in a sense that is more vague or imprecise 
  than the context may suggest; or that a word or a phrase is 
  used in a very specific meaning, at least more specific than 
  its usage in common language.

  I never found either concept in any structural markup system. 
  What comes closest to the second concept in Docbook is 
  '<firstterm>', which could be used when the word of phrase is 
  used in its very specific meaning the first time, probably 
  accompanied by a definition of that meaning.

  In plain text, I usually use single-quotes to indicate 
  impreciseness and underscores to indicate specific meanings.

Summarizing, in Docbook I would use for inline markup: 
'<replaceable>', '<emphasis>', '<wordasword>', '<firstterm>' and 
somthing for computer code or strings. For the latter, I was 
considering sticking to '<systemitem>' and maybe '<literal>', but 
not to use the more specific ones, unless there is a benefit to 
this beyond what I described above.

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