"should one use inline markup at all?" YES. Generally, we try to use tags when we have content that we want to appear differently in the output and to help our localizers.
For example, we used to just use initial caps to distinguish text that appears in the software (e.g., window/dialog names, field labels, radio buttons, etc.,); however, as the text in the software expanded (e.g., we are now seeing more phrases in field labels), it became more difficult for us and our users to distinguish the software-related text within a sentence. In addition, our localizers were telling us that it would help their work if they had a way to easily pick out the text that came from the software. Hence we now use guilabel to tag text that comes from the software. The following is a list of inline tags that we use: We use literal for things that need to stand out but must not to be localized. In the output, literal appears in bold. We use emphasis with a bold role for things that need to stand out and should be localized. In the output, emphasis with bold, appears in bold otherwise emphasis appears in italics. We use computeroutput for code snippets, command lines, and other stuff from the software. In addition, we use a role to specify whether the content must be localized. In the output, computeroutput appears in monospaced font. (We use programlisting when we need a block element to contain the same type computer stuff. ) We use filename for the names of files, paths, and registry keys. In the output, filename appears in italics. We use guilabel for text such as window names, Start menu items, field labels, radio buttons, etc. Currently we are debating how guilabel should appear in the output. We use citetitle for book names that we can't link to with olink or ulink. For example, a book outside of our collection. We use phrase to put conditions on inline text that doesn't have another inline element on it. For example, a sentence within a paragraph or a product name within a para or title, etc. Kate. Lasse Kliemann <[email protected]> 06/12/2009 03:47 AM To [email protected] cc Subject Re: [docbook] RE: Always use most specific markup? * Message by [email protected] 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.
attrba20.dat
Description: Binary data
--------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
