[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
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 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.
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]