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