Writing documentation with DocBook-XML 4.3

An abbreviation, generally made from the initial letters of words, and sometimes pronounceable. For example:

  <acronym>PEBKAC</acronym> stands for: Problem exists
  between keyboard and chair.

PEBKAC stands for: Problem exists between keyboard and chair.

Names of packages. Example:

Start <application>emacs</application>.

Start emacs.

Used for citing works by their title. Example:

Have you read <citetitle>Ringworld</citetitle>?

Have you read Ringworld?

For program source code. Example:

Next we define the <code >panic()</code > function.

Next we define the panic() function.

Computer-generated output. Example:

<computeroutput>OA210I OLD PSW WAS FF04230C 1200234B</computeroutput>

OA210I OLD PSW WAS FF04230C 1200234B

Used for emphasized text. Example:

Don't <emphasis>do</emphasis> that then.

Don't do that then.

For boldface, add the attribute role="strong". Example:

A five-ounce bird could <emphasis role="strong">not</emphasis>
hold a one-pound coconut.

A five-ounce bird could not hold a one-pound coconut.

For file names and path names. Example:

Packages live in <filename>/fs/packages</filename>.

Packages live in /fs/packages.

For the first use of a term just being defined. Example:

The term <firstterm >spam</firstterm > refers to unsolicited
commercial e-mail.

The term spam refers to unsolicited commercial e-mail.

Used to set off words in a different language than the surrounding text.

These sharks are in genus <foreignphrase>Squalus</foreignphrase>.

These sharks are in genus Squalus.

Buttons in a graphical user interface. Example:

To exit, click on the <guibutton>Quit</guibutton> button.

To exit, click on the Quit button.

An icon in a graphical user interface.

A label in a graphical user interface.

A menu in a graphical user interface. Example:

Pull down the <guimenu>Team</guimenu> menu.

Pull down the Team menu.

For names of keys on a keyboard. Example:

Press <keysym>Enter</keysym>.

Press Enter.

For in-line quotations. One could simply use the double-quote characters “…”, but the advantage of the quote element is that it correctly handles quotes within quotes. For example:

I said, <quote>As Carol Schaffer used to say,
<quote>common sense isn't</quote>.</quote>

I said, “As Carol Schaffer used to say, ‘common sense isn't’.”

Use this tag for parts of a template, pattern, or general case that will are to be replaced with specific items in practice. Example:

  Call your input file <filename><replaceable
  >f</replaceable >.tex</filename >, where
  <filename ><replaceable >f</replaceable
  ></filename > is some name of your choice.

Call your input file f.tex, where f is some name of your choice.

For the display of any XML or SGML tag. Use the attribute class="starttag" for a starting tag, and class="endtag" for an ending tag. Example:

  Enclose the page title within <sgmltag class="starttag"
  >title</sgmltag >...<sgmltag class="endtag"
  >title</sgmltag > tags.

Enclose the page title within <title>...</title> tags.

Displays the contents below the baseline. Example:

Drink more H<subscript>2</subscript>O.

Drink more H₂O.

Displays the contents above the baseline. Example:

Celebrate the 4<superscript>th</superscript> of July.

Celebrate the 4^th of July.

For commands or other user input. Example:

Type the command <userinput>make trouble</userinput>.

Type the command make trouble.

For variable names in programs. Example:

Add one to <varname>sheepCount</varname>.

Add one to sheepCount.