* Message by -- 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.
