3 Editing DocBook XML #

If you have worked with DocBook before, you know about the typical top-level elements for documents, book and article. For larger documentation projects, another typical top-level element is set (a collection of books).

To define the individual components of a book, use structural elements such as part, chapter, preface or appendix. Chapters are usually subdivided into sections (section elements or sect1, sect2 etc.). Smaller structural units are para (for paragraphs), or list elements such as orderlist, itemizedlist, or variablelist.

If you have set up your documentation project from scratch with daps-init, you can explore the example documents that are installed within the directory structure. They show the most commonly used DocBook XML constructs.

As DAPS does not include any editor software, you are completely free in the choice of your XML editor. While you can use your text editor of choice, it is helpful if the editor supports editing XML in accordance with the schema you use. Several open source editors can be extended with plug-ins for automatic tag insertion and completion, insertion of xref elements and for checks if the XML document is well-formed. If you are already familiar with vi or Emacs, you can configure them to support XML editing mode. If you prefer an editor with a graphical user interface, jEdit (http://www.jedit.org/) is a good choice.

XML elements can be nested deeply . Constructs like variablelist, table or image often have a lot of child elements—some of them required, some optional. If you have an editor with schema support, it will tell you which elements are allowed at the current cursor position, but nevertheless it is cumbersome if you need to insert the child elements of complex XML constructs consecutively.

Most editors allow you to write or record macros that can be used to automatically insert “skeletons” for complex XML constructs. For Emacs, DAPS already includes macros for adding DocBook elements. For details, refer to Section B.1, “Emacs—Macros for Inserting DocBook Elements”.

DAPS comes with a spell checker optimized for DocBook documents. The spell checker skips tags and attributes, thus allowing you to focus on the content of the document. The spell checker is based on aspell and can be evoked with the DAPS spellcheck. By default, it starts in interactive mode, but you can also run it in the “batch” mode, where it directs a sorted list of misspelled words to standard output. DAPS also allows you to specify a custom dictionary and the language to use for spell check.

The following examples demonstrate how to use spell check with DAPS. All options in these examples can be used together, except for --file and --rootid that are mutually exclusive.

Note: spellcheck Options and XIncludes

All options in the following examples can be used together, except for --file and --rootid that are mutually exclusive.

The spellcheck command always follows xi:includes, even when using the --file option.

For your convenience, you can integrate a spellchecker such a aspell (and a custom aspell dictionary, if needed) into your XML editor. This way, spelling is checked “on the fly” during editing. Consult your editor's documentation on how to integrate a custom dictionary. If you use jEdit, proceed as outlined in Section B.3, “jEdit—Spell Check on the Fly”.

To prevent the 404 or similar errors, DAPS includes a link checker for validating all external links (such as HTTP, HTTPS and FTP links) in the XML sources. This tool is based on checkbot, see man 1 checkbot for more information. The link checker searches for the url attribute in ulink elements and checks links included there. Use it to create a report of all links that caused some kind of warning or error.

Note: linkcheck follows XIncludes

The linkcheck command always follows xi:include statements, even when using the --file option.

Figure 3.1: Example Output of daps linkcheck #

Tip: Opening the Link Check Report

To directly open the link check report, use the DAPS command output as an argument for a browser (for example, the command line Web browser w3m):

tux:~> w3m -dump $(daps -d PATH_TO_DC_FILE linkcheck)

Similar products often share a considerable amount of features and differ in details only. It is therefore convenient to apply the same approach to the documentation of similar products or product families: Share most of the XML source code and only differentiate text snippets where necessary. DocBook allows you to create documentation variants from the same pool of XML sources by means of profiling.

In DocBook XML files you can mark some elements as conditional by using profiling attributes. When processing the files to generate output, specify which conditions apply to the output. The stylesheets will then include or exclude the marked text, according to the conditions.

Profiling allows you to keep both common and product-specific content in one XML file and select at production time which information to include in the output.

For details, refer to Section 6.3, “Profiling—Support for Document Variants”.

DAPS provides useful commands that can help you to keep track of the files and images in your documentation project.

For the image-related commands, see Section 5.5, “DAPS Commands for Managing Images”.

Note: Output of File Listings

By default, the output of the listing commands is a list of file names (including the absolute path), all printed in one line with the file names separated by blanks. This default output format is useful for piping (or copying and pasting) the output for use with another command.

If you need a pretty printed output where each file name is listed on a separate line, use the --pretty option.

See Example 3.1, “Default Output of a File Listing DAPS Command” and Example 3.2, “Pretty-printed Output of a File Listing DAPS Command” for a comparison of both outputs.

tux:~> daps -d PATH_TO_DC_FILE list-srcfiles
YOUR_DOC_DIR/DC-daps-example YOUR_DOC_DIR/images/src/png/example1.png YOUR_DOC_DIR/images/src/png/example_png2.png YOUR_DOC_DIR/xml/MAIN-daps-example.xml

tux:~> daps -d PATH_TO_DC_FILE list-srcfiles --pretty
YOUR_DOC_DIR/DC-daps-example
YOUR_DOC_DIR/images/src/png/example_png1.png
YOUR_DOC_DIR/images/src/png/example_png2.png
YOUR_DOC_DIR/xml/MAIN-daps-example.xml

Tip: Using Pretty-Printed Output for Counting

To count the number of files listed in a given output, you can also combine the --pretty parameter with the wc command:

tux:~> daps -d PATH_TO_DC_FILE list-srcfiles --pretty | wc -l

For Example 3.2, the command above would return

4

as a value.

For a complete DocBook reference see DocBook: The Definitive Guide (http://www.docbook.org/tdg/en/html/docbook.html).

Useful tips and tricks on using DocBook and the DocBook stylesheets can be found in The DoCookBook—Recipes for DocBook Developers and Writers, available at http://doccookbook.sourceforge.net/