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

[Kate.Wringe@sybase.com]

"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 <lasse-list-docbook-2009@mail.plastictree.net>

06/12/2009 03:47 AM

To	docbook@lists.oasis-open.org
cc
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.

attrba20.dat