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

[Lasse Kliemann <lasse-list-docbook-2009@mail.plastictree.net>]

* 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 
  whitespace.)

  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 
  this.
  
  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.

PGP signature