Editing Documents in Docbook Dave LeBlanc This document is a Docbook book of articles and should only be edited as such in ~sysadmin/docs/RecoveryBible/EditingDocuments.xml December 20, 2008 Table of Contents 1. Philosophy ..................................................................................................................... 1 1.1. Types of documentation ........................................................................................ 2 2. Methodology .................................................................................................................. 2 2.1. Tools needed ....................................................................................................... 2 3. Procedure ...................................................................................................................... 3 A. Using XMLmind XML Editor .......................................................................................... 4 1. Starting XXE ......................................................................................................... 4 2. Creating a new document ......................................................................................... 5 3. Inserting elements ................................................................................................... 6 4. Selecting elements .................................................................................................. 8 4.1. The implicit element selection ........................................................................ 9 4.2. The text selection ......................................................................................... 9 4.3. The node selection ........................................................................................ 9 5. Navigating through elements ................................................................................... 11 5.1. Using Tab to go from a #text to the other, just like in a form ............................ 11 5.2. XXE makes a difference between the end of a #text node and the beginning of the #text node next to it .................................................................................. 12 6. Copy, cut, paste, delete .......................................................................................... 13 6.1. Copy, cut, paste, delete applied to the text selection .......................................... 13 6.2. Copy, cut, paste, delete applied to the node selection ......................................... 13 7. Splitting and joining elements ................................................................................. 14 7.1. Simple Split and Join .................................................................................. 14 7.2. Split and Join generalized ............................................................................. 15 8. Replacing elements ................................................................................................ 16 9. Converting elements .............................................................................................. 19 9.1. Convert applied to the text selection ............................................................... 19 9.2. Convert applied to the node selection ............................................................. 20 10. Editing element attributes ...................................................................................... 20 10.1. Required attributes in newly created elements ................................................. 22 11. Checking document validity .................................................................................. 23 1. Philosophy Documentation is the keystone to continuity. Continuity serves well in emergency situations when panic mode arises and little thought is required, or when asked to fill a position and perform a duty that is not familiar. Documentation may also be viewed as a method to efficiency, giving the reader to ability to spot inconsistencies or discrepancies in processes, methods and procedures. At the very least, documentation serves as a reminder of something important to the reader. 1 Editing Documents in Docbook 1.1. Types of documentation Technical documentation involves basically three types of documentation: web-only, offline-only, and hybrid. • Web-only consists of information that needs to be updated with some frequency, but only readily available within a webpage. • Offline-only consists of information that needs to be available when the servers containing important information are broken for whatever reason; e.g., disaster recovery procedures. Documentation classified as offline-only is as such for process simplification -- each time a document is updated it is then printed, to avoid having copies in multiple locations. This reduces the number of invalid/stale copies of documentation. • Hybrid documentation is the information available online for the sake collaborative editions/changes with the added feature of having nicely printed copies on demand; e.g., a list of machines and their dependancies, a procedure describing shutdown order of a cluster. This type of documentation is sometimes required to be available online and offline, depending on what is being done with the information therein. For our purposes here, we will only focus on offline-only and hybrid. 2. Methodology Docbook provides a framework for creating technical documentation with the ability to output multiple different formats from a single XML source. This fits the philosophy of having multiple types of documentation while enabling the editor/author to have one master source document. With a Docbook XML document, the editor/author can specify via XSLT stylesheet how each output format will appear in its published form. There are many default Docbook XSLT stylesheets available, allowing an author to fully customize each published result. The author/publisher of a document may create webpages, manpages, Postscript, PDFs, etc. using a few simple tools on the single source document. Further, multiple documents may be included (XInclude) into a single document, resulting in a master source of documentation concerning a given subject. Couple this powerful publishing framework with a revision control system, and the result is a documentation system capable of tracking changes within the contents of documents. 2.1. Tools needed • A general understanding of the DocBook markup language (similar to how you need to have knowledge of HTML when editing webpages) • A DocBook-aware XML editor (you may use a non-DocBook editor, but that requires you know Docbook tags) XMLmind XML Editor is currently the most widely used. [see Appendix A for more info] • DocBook XSL stylesheets These are readily available, and can be downloaded from Sourceforge [http://sourceforge.net/projects/ docbook], but are also included with XMLmind XML Editor. • A general understanding of how DocBook XSL is employed. [ see http://www.sagehill.net/ docbookxsl/index.html ] 2 Editing Documents in Docbook • An XSL processor • SAXON SAXON is a Java command-line program that provides a set of services for converting XML data into other formats. SAXON is capable of converting XML documents into HTML (single page, or multi-page), Java Help, Microsoft Windows Help, XHTML (single or multi-page), and Formatting Objects (FO) which is an intermediary format that can then be transformed into PDF or RTF. • Xalan Xalan is part of the Apache XML Project. It has versions written in both Java and C++, both of them free. Generally Xalan is used with the Xerces XML parser, also available from the Apache XML Project. • xsltproc It is free, as part of the open source libxml2 library from the Gnome development project. It is considered the fastest of the processors, and is highly conformant to the specification. It is much faster than either of the Java processors, and is capable of handling XInclude. • An XSL-FO processor FOP is part of Apache's XML project and is the world's first print formatter driven by XSL formatting objects (FO) and the world's first output independent formatter. It is a Java application that reads a formatting object tree (as e.g. generated by SAXON) and then renders the resulting pages to a specified output. Output formats currently supported are PDF, PCL, PS, SVG, XML (area tree representation), Print, AWT, MIF and TXT. Since the primary output target is PDF we will use FOP for PDF formatting. • A Revision Control System is usually beneficial to track changes to important documents with the ability to revert documents to their previous state. 3. Procedure 1. If source document is under revision control, make sure it is checked out. 2. Edit the source XML document with a Docbook editor, such as XMLmind XML Editor Personal Edition [http://www.xmlmind.com/xmleditor] [see Appendix A for more precise instructions on XMLmind XML Editor] 3. Save the resulting Docbook XML file. 4. If souce XML document is under revision control, or should be, check the file in. 5. If the document includes (XInclude) portions of other documents, use xmllint to create a full normalized XML source that resolves the include statements (this is not necessary if using xsltproc): xmllint --xinclude masterfile.xml > full_target.xml Note xmllint usually comes packaged with libxml2-utils, and in this particular use it simply locates and combines all the included portions of linked documents 6. In this step, we process the xml file with the xsl stylesheet to produce FO output. 3 Editing