Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
Applies to DAPS 3.0

3 Editing DocBook XML

This chapter covers the following topics:

  • Choosing an editor for editing DocBook XML files

  • Checking the contents of your DocBook files for mistakes

  • Adapting your documentation to fit multiple similar product versions at once

  • How to keep track of the files included a documentation project

3.1 Basic Structural Elements

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.

3.2 Choice of Editor

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”.

3.3 Spell Checking

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
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.

Spell Checking Files in a Documentation Project
tux:~> daps -d PATH_TO_DC_FILE spellcheck

Runs a spell check operation on all files in the documentation project with the default dictionary (en_US). The files are opened one by one in interactive mode and checked with aspell. To abort spell checking of the current file, press X. The spell check continues with the next file in the project.

Uses the ROOTID defined in the specified DC file as starting point. You can restrict the spell check to parts of the set, such as a book, article, glossary, appendix, part, or chapter element. To do this, specify the ID of the respective element with the --rootid option:

tux:~> daps -d PATH_TO_DC_FILE spellcheck --rootid=ID
Spell Checking a Single XML File
tux:~> daps -d PATH_TO_DC_FILE spellcheck --file PATH_TO_XML_FILE

Checks the specified file (plus all files included with XIncludes on this level) using the default dictionary. Suggests alternative spellings for each misspelled word and waits for user interaction.

Spell Checking XML Files in Languages Other than English
tux:~> daps -d PATH_TO_DC_FILE spellcheck --lang=LANG \
  [--file PATH_TO_XML_FILE]

Checks the specified documentation project or file with the dictionary for LANG (make sure the specified aspell dictionary is installed). Suggests alternative spellings for each misspelled word and waits for user interaction. The language code used for the --lang option is the same that is used for the LANG environment variable and matches the directory names in /usr/share/locale.

Spell Checking XML Files in Batch Mode
tux:~> daps -d PATH_TO_DC_FILE spellcheck --list \
  [--file PATH_TO_XML_FILE]

Checks the specified documentation project or file. Returns a list of misspelled words to standard output. You can use the --list option to easily collect a list of words that are unknown to aspell and use this output as basis for a custom aspell word list or dictionary.

Spell Checking XML Files with an Additional Custom Dictionary
tux:~> daps -d PATH_TO_DC_FILE spellcheck --extra-dict=PATH_TO_CUSTOM_DICT \
[--file PATH_TO_XML_FILE]

Checks the specified documentation project or file with the default dictionary and the additional custom dictionary specified with --extra-dict.

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”.

3.5 Profiling—Support for Document Variants

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”.

3.6 Keeping Track of Your Documentation Project

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

Listing All Files in a Documentation Project
tux:~> daps -d PATH_TO_DC_FILE list-srcfiles

Lists all source files (XML sources, images, entity declarations, and the DC file) used by the document specified with the DC file.

tux:~> daps -d PATH_TO_DC_FILE list-srcfiles --xmlonly

List only source XML files used by the document specified with the DC file.

tux:~> daps -d PATH_TO_DC_FILE list-srcfiles --imgonly

List only source images used by the document specified with the DC file.

Checking for Superfluous Files
tux:~> daps -d PATH_TO_DC_FILE list-srcfiles-unused

Lists all files that are not referenced in the document specified by the DC file, but are available in the xml and images/src subdirectories. This command is useful if you want to clean up your source files and want to know which files are no longer needed for the documentation project.

Important
Important: Use a set to Check for Superfluous Files

If you are storing multiple DC files in the same project directory, use the DC file of a set for this check. As it contains all articles and books in the project directory, this makes sure that any files found during the check are indeed unnecessary.

Checking Where an ID or File is Included
tux:~> daps-d PATH_TO_DC_FILE list-file --rootid
     ID

Lists the file that contains the ID specified with the mandatory parameter --rootid. For example:

tux:~> daps -d DC-daps-example list-file --rootid sec.template.examples.images
The ID "sec.template.examples.images" appears in:
/DOC_DIR_PATH/xml/MAIN-daps-example.xml

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

Note
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.

Example 3.1: Default Output of a File Listing DAPS Command
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
Example 3.2: Pretty-printed Output of a File Listing DAPS Command
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
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.

3.7 Further Information

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/

Print this page