To understand DocBook, a basic understanding of SGML is helpful. SGML stands for Standard General Markup Language and is one of the first markup languages every created. HTML is actually derived from SGML and XML is a subset of SGML. SGML uses what is called a Document Type Definition to specify elements which are contained between brackets, < and >. Text is marked by both beginning and ending elements, for example in the DocBook DTD, one denotes a title with <title>The Title</title>.
The DTD (in the case of the GDP, DocBook) defines rules for how the elements can be used. For example, if one element can only be used when embedded within another, this is defined in the DTD.
An SGML file is just a plain ASCII file containing the text with the markup specified above. To convert it to some easily readable format, you need special tools. The GDP uses DocBook Tools, a free package of utilities for working with DocBook which includes Jade, which does the SGML/DSSL parsing. You can read more about DocBook Tools in the section called “Installing DocBook”.
The final appearance of the output (e.g. PostScript or HTML) is determined by a stylesheet. Stylesheets are files, written in a special language (DSSSL -- Document Style Semantics and Specification Language), which specify the appearance of various DocBook elements, for example, what fonts to use for titles and various inline elements, page numbering style, and much more. DocBook tools come with a collection of stylesheets (Norman Walsh's modular stylesheets); GNOME Document Project uses some customized version of this stylesheets -- see the section called “GDP Stylesheets”.
The advantage of specifying the structure of a document with SGML instead of specifying the appearance of the document with a typical word processor, or with html, is that the resulting document can be processed in a variety of ways using the structural information. Whereas formatting a document for appearance assumes a medium (typically written text on a standard-sized piece of paper), SGML can be processed to produce output for a large variety of media such as text, postscript, HTML, Braille, audio, and potentially many other formats.
Using 'content' as the elements to define the text of a document also allows for search engines to make use of the actual elements to make a "smarter search". For example, if you are searching for all documents written by the author "Susie" your search engine could be made smart enough to only search <author> elements, making for a faster and more accurate search.
Since the overall appearance of the output is determined not by the DTD or the SGML document, but rather by a stylesheet, the appearance of a document can be easily changed just by changing the stylesheet. This allows everyone in the project to create documents that all look the same.
As stated before, the GDP uses the DocBook DTD. For a list of introductory and reference resources on DocBook, see the section called “Resources”. The following sections also provide convenient instructions on which markup tags to use in various circumstances. Be sure to read the section called “GDP Documentation Conventions ” for GDP documentation-specific guidelines.
In not so distant future (probably before GNOME 2.0), DocBook itself and GNOME Documentation project will migrate from SGML to XML. This transition should be relatively painless: (almost) all DocBook tags will remain the same. However, XML has stricter syntax rules than SGML; thus, some constructions which are valid in SGML will not be valid in XML. Therefore, to be ready for this transistion, it is strongly advised that the documentation writers conform to XML syntax rules. Here are most important differences:
- Minimization
It is possible with some implementations of SGML to use minimizations to close elements in a document by using </>, for example: <title>The Title</>. This is not allowed in XML. You can use sgmlnorm command, included in DocBook Tools package, to expand minimized tags; if you are using Emacs with psgml mode, you can also use menu command Modify->Normalize.
- Self-closing tags
Also, in SGML some tags are allowed not to have closing tags. For example, it is legal for <xref> not to have a closing tag: <xref linkend="someid">. In XML, it is illegal; instead, you should use <xref linkend="someid"/> (note the slash!).
- Case sensitive tags
In XML, unlike SGML, tags are case-senstive <title> and <TITLE> are different tags! Therefore, please always use lowercase tags (except for things like DOCTYPE, CDATA and ENTITY, which are not DocBook tags).
Top-level element of a book body must be <chapter>; it may contain one or more <sect1>, each of them may contain <sect2> and so on up to <sect5>. The top-level element of an article body is always <sect1>. Regardless of which elements you use, give each structural element a unique id, so that you can link to it. For usage example, see the template.
Please try to avoid using deeply nested sections; for most situations, <sect1> and <sect2> should be sufficient. If not, you probably should split your <sect1> into several smaller ones.
Use the tag <para> for paragraphs, even if there is only one paragraph in a section--see template for examples.
For notes, tips, warnings, and important information, which should be set apart from the main text (usually as a paragraph with some warning sign on the margin), use tags <note>, <tip>, <warning>, <important> respectively. For example:
<tip> <title>TIP</title> <para> To speed up program compilation, use <application>gcc</application> compiler with Pentium optimization. </para> </tip>produces
Note that this should not be inside a <para> but between paragraphs.
To include screenshots and other figures, use the following tags:
<figure id="shot1">
<title>Screenshot</title>
<screenshot>
<screeninfo>Screenshot of a program</screeninfo>
<graphic format="PNG" fileref="figures/example_screenshot" srccredit="ME">
</graphic>
</screenshot>
</figure>
replacing example_screenshot with the
actual file name (without extension). The result will look like this:
NOTE
Notice in this example that the screenshot file name does not include the file type extension -- to find out why, please read the section called “Images in DocBook Tools”.
To show a file fragment--for example, program listing--use <programlisting> tag:
<programlisting>
[Desktop Entry]
Name=Gnumeric spreadsheet
Exec=gnumeric
Icon=gnome-gnumeric.png
Terminal=0
Type=Application
</programlisting>
which produces
[Desktop Entry]
Name=Gnumeric spreadsheet
Exec=gnumeric
Icon=gnome-gnumeric.png
Terminal=0
Type=Application
As a matter of fact, all examples in this document were
produced using <programlisting>.
To show a record of terminal session--i.e., sequence of commands entered at the command line--use <screen> tag:
<screen>
<prompt>bash$</prompt><userinput>make love</userinput>
make: *** No rule to make target `love'. Stop.
</screen>
which produces
bash$make love
make: *** No rule to make target `love'. Stop.
Note the use of tags <prompt> and
<userinput> for marking system prompt
and commands entered by user.
The most common list types in DocBook are <itemizedlist>, <orderedlist>, and <variablelist>.
- <itemizedlist>
This is the simplest unnumbered list, parallel to <ul> in HTML. Here is an example:
<itemizedlist> <listitem> <para> <guilabel>Show backup files</guilabel> — This will show any backup file that might be on your system. </para> </listitem> <listitem> <para> <guilabel>Show hidden files</guilabel> — This will show all "dot files" or files that begin with a dot. This files typically include configuration files and directories. </para> </listitem> <listitem> <para> <guilabel>Mix files and directories</guilabel> — This option will display files and directories in the order you sort them instead of always having directories shown above files. </para> </listitem> </itemizedlist>and output:Show backup files -- This will show any backup file that might be on your system.
Show hidden files -- This will show all "dot files" or files that begin with a dot. This files typically include configuration files and directories.
Mix files and directories -- This option will display files and directories in the order you sort them instead of always having directories shown above files.
Note the use of — for long dash (see the section called “ Special symbols ”). Also, please note that the result looks much nicer because the terms being explained (Show backup files, etc.) are set in a different font. In this case, it was achieved by using <guilabel> tag. In other cases, use appropriate tags such as <guimenuitem>, <command>, or -- if none of this applies -- use <emphasis>.
- <orderedlist>
This list is completely analogous to <itemizedlist> and has the same syntax, but it produces numbered list. By default, this list uses Arabic numerals for numbering entries; you can override this using numeration, for example <orderedlist numeration="lowerroman">. Possible values of these attribute are arabic, upperalpha, loweralpha, upperroman, lowerroman.
- <variablelist>
This list is used when each entry is rather long, so it should be formatted as a block of text with some subtitle, like a small subsection. The <variablelist> is more complicated than itemizedlists, but for larger blocks of text, or when you're explaining or defining something, it's best to use them. Their greatest advantage is that it's easier for a computer to search. The lines you are reading now were produced by <variablelist>. The source looked liked this:
<variablelist> <varlistentry> <term> <sgmltag><itemizedlist></sgmltag></term> <listitem><para> This is the simplest unnumbered list, parallel to <sgmltag><ul></sgmltag> in HTML. Here is an example:... </para></listitem> </varlistentry> <varlistentry> <term> <sgmltag><orderedlist></sgmltag></term> <listitem><para> This list is completely analogous to <sgmltag><itemizedlist></sgmltag> </para></listitem> </varlistentry> <varlistentry> <term> <sgmltag><variablelist></sgmltag></term> <listitem><para> This list is used when each entry is rather long,... </para></listitem> </varlistentry> </variablelist>
Lists can be nested; in this case, the stylesheets are smart enough to change the numeration (for <orderedlist>) or marks of each entry (in <itemizedlist>) for sub-lists
<guibutton> -- used for buttons, including checkbuttons and radio buttons
<guimenu>, <guisubmenu> --used for top-level menus and submenus respectively, for example <guisubmenu>Utilities</guisubmenu> submenu of the <guimenu>Main Menu</guimenu>
<guilabel>--for items which have labels, like tabs, or bounding boxes.
<interface>-- for most everything else... a window, a dialog box, the Panel, etc.
If you need to refer to a sequence of menu choices, such as Main Menu->Utilities->GNOME terminal there is a special construction for this, too:
<menuchoice>
<guimenu>Main Menu</guimenu> <guisubmenu>Utilities</guisubmenu>
<guimenuitem>GNOME terminal</guimenuitem> </menuchoice>
To refer to another place in the same document, you can use tags <xref> and <link>. The first of them automatically inserts the full name of the element you refer to (section, figure, etc.), while the second just creates a link (in HTML output). Here is an example:
An example of a <link linkend="extip">tip</link> was given in
<xref linkend="notes" />.
which produces: An example of a tip was given in the section called “Notes, Warnings, And Tips”.
Here notes and extip are the id attributes of the section called “Notes, Warnings, And Tips” and of the example of a tip in it.
To produce a link to an external source, such as a Web page or a local file, use <ulink> tag, for example:
To find more about GNOME, please visit <ulink type="http"
url="http://www.gnome.org">GNOME Web page</ulink>
which produces: To find more about GNOME, please visit
The GNOME Web
Site You can use any of the standard URL types, such
as http, ftp, file, telnet, mailto (in
most cases, however, use of mailto is
unnecessary--see discussion of
<email> tag).
Here are some tags used to describe operating system-related things:
<filename> -- used for filenames, e.g.<filename> foo.sgml </filename> produces: foo.sgml.
<filename class="directory"> -- used for directories, e.g.<filename class="directory">/usr/bin </filename> produces: /usr/bin.
<application> -- used for application names, e.g. <application>Gnumeric </application> produces: Gnumeric.
<envar> -- used for environment variables, e.g. <envar>PATH</envar>.
<command> -- used for commands entered on command line, e.g. <command>make install </command> produces: make install.
<replaceable> -- used for replaceable text, e.g. <command>db2html<replaceable> foo.sgml </replaceable></command> produces: db2html foo.sgml.
To mark up text input by the user, use <userinput>.
To mark keystrokes such as shortcuts and other commands, use <keycap>. This is used for marking up what is printed on the top of the physical key on the keyboard. There are a couple of other tags for keys, too: <keysym> and <keycode>. However you are unlikely to need these for most documentation. For reference, <keysym> is for the “symbolic name” of a key. <keycode> is for the “scan code” of a key. These are not terms commonly required in GNOME documentation, although <keysym> is useful for marking up control codes.
To mark up a combination of keystrokes, use the <keycombo> wrapper:
<keycombo>
<keycap>Ctrl</keycap>
<keycap>Alt</keycap>
<keycap>F1</keycap>
</keycombo>
Finally, if you want to show a shortcut for some menu command, here are the appropriate tags (rather long):
<menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>q</keycap></keycombo>
</shortcut>
<guimenuitem> Quit</guimenuitem>
</menuchoice>
which produces simply
Quit (Ctrl-q)
To mark up e-mail address, use <email>:
The easiest way to get in touch with me is by e-mail
(<email>me@mydomain.com</email>)
which produces: The easiest way to get in touch with me is
by e-mail (<me@mydomain.com>) Note that
<email> automatically produces a link
in html version.
DocBook also provides special means for entering typographic symbols which can not be entered directly form the keyboard (such as copyright sign). This is done using entities, which is SGML analogue of macros, or commands, of LaTeX. They generally have the form &entityname;. Note that the semicolon is required.
here is partial list of most commonly used enitites:
Note that the actual look of the resulting symbols depends on the fonts used by your browser; for example, it might happen that long dash (—) looks exactly like the usual dash (-). However, in the PostScript (and thus, in print) the output will look markedly better if you use appropriate tags.