Наши партнеры

Книги по Linux (с отзывами читателей)

Библиотека сайта rus-linux.net

D.1. General Tips and Tricks

For a general overview of what markup is all about, please read Chapter 5

  • An editor capable of inserting elements according to the DTD will help a lot since it will enforce the DTD. This way you can be sure that no invalid elements were added anywhere in your document.

  • In order to ensure that future changes are as easy as possible, authors should try to keep compatibility with the XML version of the DocBook DTD. This means keeping element names in lower case, using double quotes in all attributes, and not omitting end tags. Most tools that automatically insert elements (like psgml+emacs) follow these rules automatically or with some fine tuning.

  • Each type of document created has a specific structure. This document is in "book" format. Most authors, however, will want to use the shorter "article" format instead. Templates are available from Appendix A.

D.1.1. Useful markup

Table D-1 shows some markup that is useful for generating generic documents. Remember that some elements are valid only on some contexts.

TipCheck several formats

Sometimes the appearance of a particular tag changes from one conversion format to another. As a beginner in DocBook writing, you may wish to see how your document looks in several formats before you publish them. You are advised to look at how your document is presented in HTML, PDF and PostScript, since these formats will be made available by TLDP once you publish your document.

NoteBetter too much than not enough

Since the formatting depends on the output style chosen, it's recommended to use as much markup as possible. Even if the appearance of the output doesn't seem to change with the standard output style, there may be specific output formats that will make these tags stand out.

Table D-1. Useful markup

DescriptionSample markupResult
E-mail address<email>address@domain</email>
About the author<author>...</author>(see example below)
Author's name
Mary Margaret O'Hara
Keys' name (printings on the keyboard)<keycap>F1</keycap>F1
Symbol represented by the keys<keysym>KEY_F1</keysym>KEY_F1
Key's code<keycode>0x3B</keycode>0x3B
Combinations or sequences of keys
Program Menus<guimenu>File</guimenu>File
Menu Items<guimenuitem>Save</guimenuitem>Save
Menu Sequences
File->Save (Ctrl-S)
Mouse Button<mousebutton>left</mousebutton>left
Application Names<application>application</application>application
Text Bibliographical Reference<citation>reference</citation>[reference]
   <attribution>Text Author</attribution>
   <para>Quote Text.</para>


Quote Text.

--Text Author 
Index(NA)See Section D.4.
File Names
 <filename id="directory">directory</filename>
Emphasize Text[a]
   <para>Footnote text</para>
(See note at the end of this table for an example)
 <ulink url="http://www.conectiva.com">Conectiva S.A.</>
Conectiva S.A.
Itemized (unnumbered) List

  • item

  • item

Ordered (numbered) List

  1. item

  2. item

Segmented List
   <title>Binary to decimal conversion</title>

Binary to Decimal Conversion

Binary: 00

Decimal: 0

Binary: 01

Decimal: 1

Binary: 10

Decimal: 2

Variable List
      <term>Entry 1</term>
      <term>Entry 2</term>

Entry 1


Entry 2


Simple Lists
 <simplelist type="horiz" columns="3">
<simplelist type="inline">


A, B, C, D, E, F
Pictures(NA)See Section D.5
(See the glossary at the end of this document)
Crossed References
 <section id="secao">
<section id="reference the other section">
<para>Please, see<xref linkend="secao" /> for more information.
a. Text can be emphasized in a few ways. The most common ways are italics and bold. DocBook, however, supports only italics. The use of bold requires additional settings on the style sheet used.