mouse:~ppr/src/docs/misc/docbook.txt
7 November 2003

This file lists some of the Docbook tags used in the PPR documentation and the
conventions for their use.  It is intended for quite reference while writing
PPR documentation.  One should also refer to the LDP Author Guide.

==============================================================================
 Document Header
==============================================================================

<article>

This tag encloses whole documents.

<articleinfo>
	<title>My Document</title>
	<author><firstname>David</firstname><surname>Chappell</surname></author>
	<pubdate>15 January 2003</pubdate>
	<copyright>
		<year>1995--2003</year>
		<holder>Trinity College Computing Center</holder>
	</copyright>
</articleinfo>

These tags contain article header information.

<abstract>

This tag contains one or more paragraphs which summarize the article comments.

==============================================================================
 Document Sections
==============================================================================

<sect1 id="XXX">
<sect2 id="XXX">
<sect3 id="XXX">

These tags delineate chapters and subheadings.

<title>

This tag encloses the title of a section.  It should come immediately after
the opening section tag.

<para>

This tag encloses each paragraph.

<footnote>
	<para>
	</para>
</footnote>

These tags make a footnote.

==============================================================================
 Computer Objects
==============================================================================

<command>

This tag encloses the name of an executable command or the text that a user
enters in order to execute it.

<option>

An option for a command.

<replaceable>

Text which can or should be replaced by the user.

<application>

This tag encloses the name of an computer program (as opposed to the command
that launches it).  For example: jobs are submitted to
<application>PPR</application> using the <command>ppr</command> command.

<envar>

This tag encloses the name of an environment variable.

<errorcode>

A numberic or symbolic error code.  For example,
<errorcode>EINTR</errorcode>.

<errorname>

A text description of an error code, for example, <ErrorName>Access
Denied</ErrorName>.

<errorclass>

A category of error such as <errorclass>fatal</errorclass>.

<screen>

This is a varbatim environment for displaying text which a user might see on
a computer screen.  It need not be enclosed in a paragraph.

<filename>

This tag encloses a file name.

<filename class="HeaderFile">

This tag encloses the name of a C header file.

<filename class="Directory">

This tag encloses the name of a directory.

<filename class="SymLink">

This tag encloses the name of a symbolic link.

<hardware>

A physical part of a computer system, for instance <hardware>Parallel Port
1</hardware>.

<systemitem class="OSname">

The name of an operating system.

<SystemItem class="SystemName">

The name of a computer system.

<prompt>

A command-line-interface prompt for user input.

<guilabel>

The label place where the user may enter data in a GUI interface.

<guimenu>

The name of a GUI menu.

<guisubmenu>

The name of a submenu in a GUI.

<guimenuitem>

The name of a terminal menu item in a GUI.

<guibutton>

The text of a pushbutton in a GUI.

<computeroutput>

An inline bit of computer program output.

<userinput>

An inline bit of text that a user is expected to enter into a computer
program.

<literal>

Some piece of text data taken from a computer system, such as part of a
configuration file.

==============================================================================
 Lists
==============================================================================

<variablelist>
	<varlistentry>
		<term>the</term>
		<listitem>
			<para>
			A definite article.
			</para>
		</listitem>
	</varlistentry>
	<varlistentry>
		<term>a</term>
		<listitem>
			<para>
			An indefinite article.
			</para>
		</listitem>
	</varlistentry>
</variablelist>
		
These tags produce dictionary lists.

==============================================================================
 Imported Images and Figures
==============================================================================

<figure id="id_here">
<title>title here</title>
<mediaobject>
	<imageobject><imagedata fileref="pprhack_somesection1.eps" format="eps"/></imageobject>
	<imageobject><imagedata fileref="pprhack_somesection1.png" format="png"/></imageobject>
</mediaobject>
</figure>

This displays an XFig image.

<figure id="id-here">
<title>title here</title>
<screenshot>
	<screeninfo>notes about how to reproduce</screeninfo>
	<graphic format="png" fileref="screenshot.png" width="6in" scalefit="1"/>
</screenshot>
</figure>

This displays a screenshot image.  The contents of <screeninfo> are not
displayed.  If you want to scale by a fixed factor, replace width= and
scalefit= with scale=.

==============================================================================
 Source Code
==============================================================================

<programlisting>

This is a verbatim environment for block formatted program code.

<programlisting>
<![CDATA[
int main(int argc, char *argv[])
    {
    }
]]>
</programlisting>

This is a verbatim environment for block formatted program code with
markup recognition disabled.

<funcsynopsis>
	<funcprototype>
		<funcdef>int <function>printf</function></funcdef>
		<paramdef>
			<parameter>char *format</parameter>
			<parameter>...</parameter>
		</paramDef>
	</funcprototype>
</funcsynopsis>

These tags are used to mark C function prototypes.

<varname>

The name of a variable.

==============================================================================
 Hyperlinks
==============================================================================

<xref linkend="target_id"/>

This tag inserts the name of the target section.  If the output format
supports hyperlinks, then the section name is hyperlinked to the section
to which it refers.

<ulink url="XXXXX">linked text</ulink>

A hyperlink with a URL.  It does not generate the linked text.

==============================================================================
 Other
==============================================================================

<email>

An e-mail address.

<productname>

The name of a commercial product such as a printer.

<citetitle>

Citation of another book.

