OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

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

"should one use inline markup at all?"
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.


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

06/12/2009 03:47 AM

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

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