Chapter 1. Working with XMLmind Editor

The ORM production team favors XMLMind Editor (XXE). Therefore, much of our documentation refers to XXE, and we have developed some nice customizations for it (details in the next section). However, please remember that you are not obliged to write in XXE—you can choose your preferred tool, e.g., oXygen XML Author. See “Picking an XML Editor” in the DocBook guidelines for more info.

If you decide to use XXE, please download the professional version 3.5.2:

http://www.xmlmind.com/archive/xmleditor/3.5.2/

This version is free and permits commercial use, unlike later versions. You do not need a license for it. The xxe-std-3_5_2.zip file will work on Windows, Linux, and Mac OS X operating systems.

XXE is officially supported on Windows XP/Vista/7, on Linux 2.6, and on Mac OS X 10.4 (Tiger), 10.5 (Leopard), 10.6 (Snow Leopard). It is possible to use it on other Java 1.5+ platforms (e.g., Solaris), but without support from XMLmind.

The information in this document is geared toward using XXE as part of O’Reilly’s workflow. For more general information about getting started with XXE, a good starting point is the official XXE documentation. The XXE site also provides a useful PDF. Additionally, you may want to take a look at the XML.com article “Getting Productive with XMLMind” by O’Reilly authors James Elliot and Marc Loy. Their article was referenced during the creation of this document and is a good resource for beginners.

Customizing XXE

You can install some customizations that tweak XXE to display your DocBook documents so they more closely resemble the PDF (and eventually printed) form. Download the CSS file customized to O’Reilly fonts, headings, and item numbering here: .

https://prod.oreilly.com/external/tools/xxe/customizations/xmlmind_custom.zip
(username: guest; empty password)
  • If on Mac or Linux (and Unix, more generally), unzip to ~/.xxe/addon/.

  • If on Windows XP, unzip to C:\Documents and Settings\username\Application Data\XMLmind\XMLEditor\addon\.

More detailed instructions for installing customizations can be found on the XXE website.

Using XXE

A program like XXE puts a word-processing face on XML, making it more user-friendly while checking the markup validity. The Element Bar (see Figure 1-1), or Node Path, at the top of your screen lets you know where you are in the XML structure at any given point (whether you are in a section, title, paragraph, list, etc.). Clicking on an element in the Element Bar will display a red box around the element in the document, making it easy to identify where it starts and ends.

The Element Bar shows the XML hierarchy
Figure 1-1. The Element Bar shows the XML hierarchy

You can also navigate the hierarchy by using the movement buttons in the upper-right corner of the screen. The up and down arrows move you through parent and child elements; the left and right arrows move you through sibling elements.

To see a view of the document structure in tree form, go to View→0 (no stylesheet). This is shown in Figure 1-2. If you’d like to see both the DocBook and the tree view, go to Options→Preferences→Window→Show both tree and styled views, as shown in Figure 1-3.

View menu
Figure 1-2. View menu
Tree view
Figure 1-3. Tree view

If you’re wondering why the book.xml file is not editable in XXE, it’s because the content is being pulled in from the XInclude references to the chapter files. You must edit the chapter files directly. Fortunately, there is a handy shortcut to open a referenced file from book.xml: just place your cursor wherever you want to edit, and hit Cmd-Shift-E. The chapter file will open at that location. You can also get there by choosing Edit→Reference→Edit Referenced Document.

Handy Tools

XXE offers a number of tools you can use when working on your DocBook manuscript. Here are a few of our favorites:

Element Search

If you have the ORM customizations installed, you can hit ESC-G to open the Find Element pop up, or go to Select→Find Element. Type the name of any element into the Element field, as shown in Figure 1-4. Click OK, and XXE will jump to the next instance of that element in your document. There are optional fields for specifying attributes and contained text. If you are familiar with the XPath language, the Advanced tab lets you enter an XPath to jump to a specific point in a document.

XXE will not automatically cycle back to the top of the document in a search, so be aware of your location when searching.

Searching for an element
Figure 1-4. Searching for an element
Search & Replace

You may find it useful to search for or find/replace certain words or phrases. You can do this by clicking the Search tab in the righthand panel (shown in Figure 1-5) or hitting Cmd-F. You can choose to ignore case or search by part of a word, and you can also choose to skip over a single instance or every instance of the word within a certain element.

Spelling

Another tool that comes in handy is the spell check (illustrated in Figure 1-6), also found in the righthand panel. You can use the “Skip Element” button to skip over instances in certain elements; for example, if you want a word to be capitalized in section headers but not within text.

Spell check
Figure 1-6. Spell check
Special Characters

If you find that you need to insert a character that isn’t a standard keyboard character, you can choose it from the Characters tab, shown in Figure 1-7. The character palette will display the Unicode number for a character if you hover over the symbol. If you can’t find a symbol, but know the Unicode number, you can type in the Unicode number to bring up the appropriate symbol. (See “Unicode for Special Characters” in the DocBook guidelines.)

Character palette
Figure 1-7. Character palette
Validation

XXE checks the validity of your document as you go (the little square panel in the lower-left corner indicates validity status), and you can also choose the Validity tab to display any errors that might have cropped up in the document.

If you’re working on a chapter file, you can ignore errors about broken xrefs (like those shown in Figure 1-8) if the reference is to something in a different chapter file. These types of errors will disappear once you open the book.xml file with all chapters included. If they don’t disappear when you open book.xml, they’re real validity errors and need to be fixed.

Validation tab with broken cross-reference errors
Figure 1-8. Validation tab with broken cross-reference errors
Note to self…

If you would like to put in a comment as a reminder to yourself or someone else who will be working with your files, you can choose Edit→Comment→Insert Comment (as shown in Figure 1-9). A comment will be inserted with a yellow background to help it stand out. See Figure 1-10 for an example. The stylesheet won’t display the comments in the PDF, so you don’t need to worry about removing them.

Another option is to enter remarks in the text. These are displayed in red and italicized in XXE (assuming you have the ORM customizations installed) so as to stand out. Again, they won’t appear in the PDF.

Inserting a comment
Figure 1-9. Inserting a comment
Comment within a document
Figure 1-10. Comment within a document

New Sections

When adding sections to your document, use the “Add section” button (see Figure 1-11) to choose a sectN element. (In contrast to what’s shown in Figure 1-11, do not choose the section element; sectns should be used as described in “Organizing Your Files” in the DocBook guidelines.) If the new section comes above or below where you want it to go in the hierarchy, you can use DocBook→Promote and DocBook→Demote to move it to the appropriate level. The buttons used are shown in Figure 1-12. By promoting sections, you can move a section that is currently a sect2 to a sect1. Demoting will move a sect1 down to a sect2.

The Move Up and Move Down functions can be used to move elements past each other, though they’re mostly used to move sections around.

Adding a new section
Figure 1-11. Adding a new section
Promoting and demoting sections
Figure 1-12. Promoting and demoting sections

When you create new sections, your sections will automatically renumber in XXE according to where the new section has been entered. The same applies to figure and table numbering.

Splitting and Merging Sections

If you need to split up a section, select the paragraph that you want to start the new section by selecting the para in the Element Bar, and then choose DocBook→Promote to create a new section with that paragraph.

Merging two sections can be a bit more difficult. If you are just moving a few paragraphs into another section, you can cut and paste the text from one section to the other and delete the second section title. If you have a more complex section to move, use the steps below:

  1. Make sure the two sections you want to join are adjacent to each other, with the section heading that you want to keep positioned first.

  2. Select the first section in the Element Bar.

  3. Select→Select All Children (display boxes will surround all the individual elements that make up that section).

  4. Choose Edit→Copy (Cut isn’t an option for a complex section).

  5. Select the title element of the second section you want to join.

  6. Choose Edit→Paste and paste the first section into the title element of the second section. This will replace the second section’s title with the first section’s title, and insert all the other elements of the first section at the beginning of the second section.

  7. Now go back and delete the first section.

Using Elements Correctly

The Element Bar at the top of XXE will show you which element you have selected. Block elements are paragraph-level elements (e.g., programlisting). Inline elements go within block elements (e.g., emphasis). The Element Bar’s default description of text in any element is #text. You can select #text and convert to an element that better suits your needs, like literal.

For example: if you want to emphasize a word or phrase by putting it in italics, highlight the text and click the Convert button in the Edit panel. In the field that appears, start typing the name of the inline element you wish to apply, in this case emphasis.

The Convert button is shown in Figure 1-13. You can also use the formatting buttons in the toolbar (above the Element Bar) to convert text to emphasis, links, plain text, etc. This is often faster than using the Convert button for these basic elements.

Using the Convert button
Figure 1-13. Using the Convert button

To insert a bulleted list, choose “Add itemizedlist” from the toolbar to insert the first bullet point. For a numbered list, choose “Add orderedlist.” For a term-definition list, choose “Add variablelist.”

If you don’t see the element you want as an option for your highlighted text, it probably means it isn’t a valid option. Try placing your cursor at a different level in the hierarchy. Only the elements that are valid for your location in the hierarchy according to the DTD are displayed as options. (This is a very useful feature of XXE as well as a potentially aggravating one, if you can’t figure out why the program is not letting you do something.)

Similarly, if you’ve cut text from one spot and are having trouble pasting it, make sure you are pasting into the same element. XXE won’t let you paste somewhere invalid. Try moving up or down the hierarchy, or use the Paste, Paste Before..., or Paste After... buttons in the toolbar.

Inserting Tables

There are two options for tables: formal and informal. A formal table will have a number and title, making it better suited for cross-referencing. An informal table lacks a number and title and is more suited for a small table interspersed with normal text that won’t need to be referenced later. The easiest way to add a table to a document is to choose the “Add table” button in the toolbar (shown in Figure 1-14). The most common type of table you will probably use is table(head_row)—that is, a formal table with a row at the top serving as the header.

Inserting a table
Figure 1-14. Inserting a table

If you need to add rows or columns to your table (the default is three rows by two columns), go to DocBook→Column→Insert Before, or After or DocBook→Row→Insert Before or After.

For a formal table, make sure you select the table element and give it an id attribute, as illustrated in Figure 1-15. This is a unique identifier that will be used when you add a cross-reference to it.

Applying an id attribute to a table
Figure 1-15. Applying an id attribute to a table

Inserting Figures

Figures are similar to tables in that they can be either formal or informal, where formal figures have a number and title, and informal figures have neither. For formal figures, make sure to fill in the title. See the “Figures” section of the DocBook guidelines for more info.

For instructions for producing the images for your book, please see the O’Reilly Media Illustration Guidelines.

Place your image files in the figs/ or images/ directory in your repo. Then, to add an image in the document, click the “Add image” button in the toolbar and choose figure from the drop-down menu (unless you have a very good reason for choosing one of the other options). This is illustrated in Figure 1-16.

Inserting a figure
Figure 1-16. Inserting a figure

When you select the imagedata element within the figure (where it says “Unknown format”), you will notice that in the Attributes panel, fileref has ??? as a placeholder. Click the folder icon at the top of the Attributes panel, and you can browse for the file location of your image (see Figure 1-17). You can also manually enter this file path next to fileref in the menu, or double-click on the imagedata placeholder to bring up a fileref window, as shown in Figure 1-18.

Sourcing the figure file
Figure 1-17. Sourcing the figure file
Picking a file source location
Figure 1-18. Picking a file source location

Make sure you press Return after entering the value of an attribute, or it will disappear when you leave the field.

Make sure to give each figure an id so that it can be cross-referenced later. If you notice your figures are rendering too wide for the page in your PDFs, you can scale them down by adding a width attribute value, as explained in “Image sizing” in the DocBook guidelines.

XXE is able to display PNGs but not PDFs—just like web pages.

Establishing Cross-References

You may want to use placeholders for cross-references that will be inserted later (like “see Chapter XX”). When you are ready to insert the cross-reference, delete the entire placeholder (“Chapter XX”, not just “XX”—the stylesheet will automatically generate the “Chapter” and number in the PDF), click the Insert button, and choose xref from the list of available elements in the Edit panel. Then go to the Attributes panel and find the ??? placeholder in the linkend field. Select the question marks and replace them with the ID of the element you want to reference. You can also click the “List of values…” button at the top of the panel (it looks like a yellow ruler), and it will give you a list of available IDs to cross-reference. Figures 1-19 and 1-20 illustrate this process (don’t worry about the xrefstyle attribute, though).

Make sure all formal figures, formal tables, and formal examples are explicitly cross-referenced in the text.

Find the ID
Figure 1-19. Find the ID
Fill in the linkend
Figure 1-20. Fill in the linkend

Working with Index Terms

The index is automatically generated from indexterms in the component book files. See the O'Reilly Indexing Guidelines for more information on indexing in DocBook. The following instructions assume the ORM customizations are installed.

If you are an author writing a first edition manuscript, you do not need to worry about indexterms; indexing will be done by a professional indexer once your book is in production.

Inserting a new index entry

To insert a new entry:

  1. Place the cursor where you want the entry, and hit ESC-i. This will open a pop-up window that lets you type in primary, secondary, and tertiary index terms, separated by slashes.

  2. Hit Enter and the index entry will appear in gray.

To insert a “See” or “See also” entry:

  1. After creating the entry as outlined above, select the primary element (or secondary or tertiary, depending on what the “See”/“See also” entry refers to) in the Element Bar to highlight it.

  2. Select “Insert After” (or hit Cmd-j) to insert the see or seealso element.

  3. Enter the appropriate text.

To insert an index range:

  1. Start by inserting a new entry as outlined above.

  2. Select the indexterm in the Element Bar to highlight it. You should see a red box surrounding it.

  3. In the Attributes panel, go to the “class” row and choose startofrange.

  4. With indexterm still highlighted, go to the “id” row and enter a name. The name can be anything you want, but we suggest you follow a format. For example, if you’re working in Chapter 2 and the term is foo, then the id might be ch02_foo.

  5. Go to the place in the text where the range should end, and insert another indexterm using ESC-i. But don’t actually enter a term in the pop-up window; just press “OK” to create an empty indexterm.

  6. Select the empty indexterm.

  7. In the Attributes panel, go to the “class” row and choose endofrange.

  8. With the empty indexterm still highlighted, go to the “startref” row and enter the exact same id you used in step 4. If you don’t use the same text in the same case, you will get a validity error that looks something like this:

    reference to non-existent ID "ch02_fot" [cvc-id.1]

Editing existing entries

To search for index entries using XXE:

  1. Open the book.xml file.

  2. With the cursor at the top of the document, hit ESC-G to open the Find Element pop up.

  3. In the “Element” field, type in indexterm. If you want to find a particular term, type it in the “Containing Text” field.

  4. Hit Enter to jump to the first instance in the book. Hit Cmd-A to jump to the next instance.

  5. Once you find the entry you want, you won’t be able to edit it because the data is contained in the chapter file, not the book.xml file that you’re searching in. So hit Cmd-Shift-E to open the referenced file and jump to the entry.

  6. Edit and save.

  7. Go back to book.xml to do your next search.



[1] Do not choose link. That is a different element altogether and should not be used unless you have a good reason.