Product SiteDocumentation Site

JBoss Middleware 0.1

JBoss Documentation Guide

The canonical reference for JBoss developers and writers

Edition 1

Logo

Jared Morgan

Technical Writer 
Red Hat, Inc Engineering Content Services

Darrin Mison

JDocBook and Publican Interoperability revised content and pom.xml engineering 
Red Hat, Inc Engineering Content Services

Sean Rogers

XML Element Guidelines 
Red Hat, Inc Engineering Content Services

Abstract
Throughout JBoss Middleware, the amount of user documentation is significant. This guide contains information that will help new and existing JBoss projects author XML documentation to a common technical and content quality standard. JBoss projects will benefit from the information regarding XML structure, and specific grammar guidelines. By following the recommendations in this guide, your JBoss project will have the style and XML usage information necessary to create professional open source software user documentation; be able to leverage JBoss' wider content, editorial, and translation infrastructure; and be able to easily contribute downstream content to supported products, and accept contributions, including translations, from products downstream.

Preface
1. License
2. Document Conventions
2.1. Typographic Conventions
2.2. Pull-quote Conventions
2.3. Notes and Warnings
3. We Need Feedback!
4. Acknowledgements
1. Introduction
2. eXtensible Markup Language
2.1. Advantages
2.2. Role in JBoss Middleware
2.3. XML References
3. Authoring Tools
3.1. Syntext Serna
3.2. oXygen XML Editor
3.3. XML Copy Editor
4. Publishing Tools
4.1. Maven jDocBook
4.2. Publican
5. JDocBook and Publican Interoperability
5.1. Introduction
5.2. Prerequisites
5.2.1. Install Maven
5.2.2. Install Publican
5.3. Create Book Repository
5.4. Build with Publican
5.5. Build with jDocBook
5.5.1. xi:include Fallbacks
5.5.2. Insert .ent Parameter Entities
5.5.3. Configure pom.xml
5.5.4. Publish with jDocBook
5.5.5. Begin Authoring
6. Structure Guidelines
6.1. Disallowed Elements and Attributes
6.1.1. Disallowed elements
6.1.2. Disallowed attributes
6.2. Entities
6.3. Chapters and Sections
6.4. Lists
6.5. Procedures
6.6. Tables
6.7. Emphasis (Bold, Italic, Underline)
6.8. Graphics and Screenshots
6.9. Admonitions (Warning, Important, Note)
6.10. Special Characters (Symbols)
6.11. Menus, Buttons, and Labels
6.12. Applications and Utilities
6.13. Code Examples
6.14. Links and References
7. Language Guidelines
7.1. Dictionary
7.2. Active Voice
7.3. Tense
7.4. Gender References
7.5. Sentence Structure
7.6. Conversational Language
A. pom.xml Multi-Profile
B. Sample Project
B.1. Default Folder Structure
B.2. Book Components
B.3. Customizing Book Structure
C. Revision History

Preface

1. License

This document is licensed under the Creative Commons CC-BY-SA license. You are welcome to utilize any content contained in this user guide according to the terms of this license.

2. Document Conventions

This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.
In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed.

2.1. Typographic Conventions

The following typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.
System input, including shell commands, file names and paths, and key caps and key-combinations are presented as follows.
To see the contents of the file my_next_bestselling_novel in your current working directory, enter the cat my_next_bestselling_novel command at the shell prompt and press Enter to execute the command.
The above includes a file name, a shell command and a key cap, all distinguishable thanks to context.
Key-combinations can be distinguished from key caps by the symbol connecting each part of a key-combination. For example:
Press Enter to execute the command.
Press Ctrl+Alt+F1 to switch to the first virtual terminal. Press Ctrl+Alt+F7 to return to your X-Windows session.
The first sentence highlights the particular key cap to press. The second highlights two sets of three key caps, each set pressed simultaneously.
If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph are presented as follows.
File-related classes include filesystem for file systems, file for files, and dir for directories. Each class has its own associated set of permissions.
Words or phrases encountered on a system, including application names; dialog box text; labeled buttons; check-box and radio button labels; menu titles and sub-menu titles are presented as follows.
Choose SystemPreferencesMouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, click the Left-handed mouse check box and click Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).
To insert a special character into a gedit file, choose ApplicationsAccessoriesCharacter Map from the main menu bar. Next, choose SearchFind from the Character Map menu bar, type the name of the character in the Search field and click Next. The character you sought will be highlighted in the Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the Copy button. Now switch back to your document and choose EditPaste from the gedit menu bar.
The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all distinguishable by context.
Note the shorthand used to indicate traversal through a menu and its sub-menus. This is to avoid the difficult-to-follow 'Select Mouse from the Preferences sub-menu in the System menu of the main menu bar' approach.
Italics denotes text you do not input literally or displayed text that changes depending on circumstance. Replaceable or variable text is presented as follows.
To connect to a remote machine using ssh, type ssh username@domain.name at a shell prompt. If the remote machine is example.com and your username on that machine is john, type ssh john@example.com.
The mount -o remount file-system command remounts the named file system. For example, to remount the /home file system, the command is mount -o remount /home.
To see the version of a currently installed package, use the rpm -q package command. It will return a result as follows: package-version-release.
Note the words in bold italics above — username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.

2.2. Pull-quote Conventions

Two, commonly multi-line, data types are set off visually from the surrounding text.
Output sent to a terminal is presented as follows:
books        Desktop   documentation  drafts  mss    photos   stuff  svn
books_tests  Desktop1  downloads      images  notes  scripts  svgs
Source-code listings are presented and highlighted as follows:
package org.jboss.book.jca.ex1;

import javax.naming.InitialContext;

public class ExClient
{
   public static void main(String args[]) 
       throws Exception
   {
      InitialContext iniCtx = new InitialContext();
      Object         ref    = iniCtx.lookup("EchoBean");
      EchoHome       home   = (EchoHome) ref;
      Echo           echo   = home.create();

      System.out.println("Created Echo");

      System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
   }
   
}

2.3. Notes and Warnings

Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.

Warning

A Warning should not be ignored. Ignoring warnings will most likely cause data loss.

Important

Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring Important boxes won't cause data loss but may cause irritation and frustration.

Note

A note is a tip or shortcut or alternative approach to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.

3. We Need Feedback!

If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a documentation issue using the JIRA tracking system against the product JBoss_Middleware.
When submitting a bug report, be sure to mention the manual's identifier: doc-JBoss_Documentation_Guide
If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.

4. Acknowledgements

Many thanks to the following Red Hat contributors for adding valuable content to this reference.
Darrin Mison contributed the base technical information for Section 5.2.1, “Install Maven”, and Section 5.5.4, “Publish with jDocBook”.
Sean Rogers contributed heavily to Chapter 6, Structure Guidelines with reworked and detailed XML element guidelines from the ECS wiki. These guidelines were originally written by David O'Brien.
Many thanks to Ruediger Landmann and the Publican Team for allowing us to directly include Section 6.1.2, “Disallowed attributes”, Section 6.1.1, “Disallowed elements”, and Section 6.2, “Entities” from the Publican User Guide.

Chapter 1. Introduction

Welcome to the JBoss Documentation Guide, and congratulations on taking the first step to discovering how you can improve your JBoss user documentation.
If you are new to user documentation, you might be wondering how to get started with your documentation project. In this guide, you will discover how to set up a book repository that works with Maven jDocBook as well as Red Hat's Publican. You will also learn about XML structure tips and grammar rules that will help you and your contributors write XML documentation consistently.
If you use XML regularly and already have Maven managing your project, it's time to learn some complimentary skills. Take your Maven XML documentation to the next level and make it cross-compatible with Publican. Apply the language guidelines in this guide to enhance the usability and readability of your documentation. Read and apply the XML structure guidelines to see what a little structure can do to your life.
After reading this guide and following its recommendations, you will be able to "keep the code real" for both your project and your documentation.

Chapter 2. eXtensible Markup Language

In this chapter, you will learn about the advantages of XML and why JBoss uses XML as the standard for all documentation. You will also discover other resources that may help you to understand the finer points of DocBook XML.

2.1. Advantages

Choosing DocBook XML for your documentation over other formats has numerous benefits.
Separate content from data
With XML, you do not have to concern yourself with "styling" your document as you write. There is no need to think about what size font you need to use for a heading, or if your numbered list will be correct when you publish the content.
Platform independence
Your XML documentation is compatible on any operating system. Basic XML authoring does not require expensive software to write XML, although you may find it easier to use XML authoring tools. Some of these tools are free (as in beer).
Consistent document structure
XML documents use a Document Type Definition (DTD) that specifies the underlying structure of your document. You still have freedom to structure your document according to the permissions of the DTD, but you will not be able to make errors that would make your document less usable. For example, putting a sections inside a bulleted list.
Once source, multiple outputs
XML allows you to publish your XML content to multiple output formats. You can output your documentation to PDF, single-page HTML and and multiple-page HTML.
One source, multiple contributors
Because XML is designed to be modular, multiple authors can work independently on different parts of XML documentation. XML is also compatible with revision control software such as Subversion (SVN) which allows contributors to manage content development and work remotely with ease.

2.2. Role in JBoss Middleware

DocBook XML is used extensively throughout JBoss, because the underlying support infrastructure is tailored towards structured authoring. Apache Maven, the JBoss project management infrastrucutre, supports XML documentation natively with the Maven jDocBook plugin.
Choosing DocBook XML allows Red Hat to contribute to your project by offering internationalization and localization services. You can also gain the experience of trained Content Authors who can value-add to your documentation by editing your XML, and provide guidance on XML authoring.
Red Hat Engineering Content Services can also contribute changes in your enterprise documentation back up into the community stream if you author your documentation using DocBook XML.

2.3. XML References

There are numerous resources available that discuss XML authoring. By far the most authoritative resource for DocBook XML is DocBook: The Definitive Guide, which is freely available online at http://www.docbook.org/tdg/en/html/ . This guide provides you with definitions for all available elements in the DocBook standard.
If you are new to XML authoring, you may wish to learn the basics behind XML before beginning your documentation project. A Technical Introduction to XML by NormanWalsh is a great place to start. You can access the resource online at http://nwalsh.com/docs/articles/xml/
In JBoss, some elements and attributes are excluded from use, because they impact translation and localization. You can read more about disallowed elements in Section 6.1.1, “Disallowed elements”. Section 6.1.2, “Disallowed attributes” discusses the attributes that are disallowed due to translation impacts.
In this user guide, Chapter 6, Structure Guidelines discusses the JBoss standard XML elements. You will learn how to apply the elements correctly according to what you are documenting.

Chapter 3. Authoring Tools

While you can write XML using a basic text editor, the easiest way to author XML is by using an XML Authoring Tool. A good XML Authoring Tool can auto-complete structure for you, and most importantly, validate the XML content you have written to ensure it is well-formed and valid to the standard.
The number of XML authoring tools available can seem daunting to a first-time content author. The following applications will help you to get started with XML authoring, and ease your transition into the world of structured authoring.

3.1. Syntext Serna

Syntext offer a free (as in beer) What You See Is What You Get (WYSIWYG) XML editor called Serna Free .
This editor hides much of the complexity of XML authoring, and lets you focus on authoring the content. You still must have good knowledge of XML structure, because the application still requires you to select the right parent tag before it can auto-complete subsequent selections.
Serna is a cross-platform editor. By far, the best feature of this editor is the fact that you can open up the root XML file (the <book> level), and all xi:include links, cross-references, entities, and graphics are opened up in the editor as one seamless file. This really helps with validation, and makes linking between chapters and sections easy.

3.2. oXygen XML Editor

The <oXygen/> XML Editor is a multi-platform XML editor, debugger, and profiler that supports Unicode. Because <oXygen/> is a java application, you can use it on any system that support Java. If your project uses Eclipse, there is a plug-in available that allows you to run <oXygen/> as part of your Eclipse infrastructure.
<oXygen/> is aware of xi:include statements, and therefore can follow xi:include statements as part of the validation process. This is almost a mandatory feature in the authoring program you choose, because xi:includes are used extensively throughout JBoss documentation.
If you prefer to edit in text mode, or prefer full WYSIWYG mode, <oXygen/> offers modes that may suit your requirements.
Unlike Serna Free, <oXygen/> is not free, nor is it open-source. Trial versions are available, so consider it along with the other available authoring tools.

3.3. XML Copy Editor

XML Copy Editor is a linux-only text-based editor, that has no WYSIWYG functionality. You must know your XML rules very well to use this editor.
XML Copy Editor contains a DocBook XML Parser, which will validate your XML. What it can't do is open all the xi:includes and resolve internal <xref> declarations that are not in the same file. This will result in a lot of validation errors, that may mask actual structural validation issues.
The advantage that XML Copy Editor offers is the ability to edit the XML structure in a basic text interface. This can be very useful when you are trying to debug your XML documentation and need to open up the chapter or section that contains the structural error.

Chapter 4. Publishing Tools

The two publishing tools used by the JBoss Community are Maven jDocBook, and to a lesser extent, Publican.

4.1. Maven jDocBook

Apache Maven (or Maven, as it is commonly referred to) is a project management tool that is used extensively throught JBoss Middleware. As a JBoss developer, you are probably quite familiar with Maven's capacity to build and manage your software project.
There are some excellent resources available for developers that are new to Maven. For further reading, refer to the Apache Maven homepage.
Maven supports many plug-ins which extend the functionality of the tool. One such plug-in is the maven-jdocbook-plug-in (or jDocBook as it is commonly referred to). The plug-in checks the validity of your XML documentation prior to publish, and transforms the XML source to a number of output formats as part of your Maven build.
Rather than relying on locally installed DocBook transformation engines, jDocBook utilizes Maven's dependency mechanism to import the components it requires to execute the publish. SAXON is used as the transformer factory for the XML source.

4.2. Publican

Publican is a Perl-based publishing system developed in-house by Red Hat. The program is executed from the command-line, with a set of well documented user commands. It is used by Red Hat's Engineering Content Services division as the de-facto standard for producing enterprise documentation according to brand, XML validity, and translation requirements.
Publican is a cross-platform solution, with versions available for Linux (including Fedora, Red Hat Enterprise Linux, Debian, and Ubuntu), Apple Mac, and Microsoft Windows.
Publican and jDocBook can complement each other in your documentation project. You can use Publican for the following tasks:
  • quickly validate your XML to Publican and (by default) jDocBook requirements. Publican begins to evaluate your XML as soon as you call it, rather than having to wait until Maven dependencies are downloaded.
  • produce translation files which allow your community (and enterprise) documentation to be translated economically.
For a complete guide to Publican, including installation instructions and commands, visit the Publican home page on fedorahosted.org.

Chapter 5. JDocBook and Publican Interoperability

5.1. Introduction

The following information will allow you to configure your documentation project to publish in both Maven jDocBook and Publican. The configuration described in this section is recommended if your community project wants Red Hat Engineering Content Services (ECS) to contribute content enterprise documentaton enhancements upstream, including translation and content improvements.
The work flow assumes that you are starting from scratch; you need to configure a documentation repository for a new book, and do not have any other cross-compatible repositories in your project. You are also using a linux-based operating system.

Sample Project

If you prefer to take an existing repository and customize it to your requirements, you may wish to review Appendix B, Sample Project. A basic Publican book is provided for you to take and customize to your requirements.
If your project already has a suite of user documentation, and you wish to make your documentation cross-compatible, you can follow the guidelines stated below and implement the correct structure in your documentation repository. Alternatively, contact the Red Hat JBoss Middleware team who can assist your project with the conversion process.

5.2. Prerequisites

The following pre-requisites are necessary for Maven jDocBook and Publican interoperability. It is assumed that you do not have any of the following components installed, and require some basic configuration instructions--or links to appropriate resources-- to make the installation process simple.
This section also assumes you are using a Linux-based operating system.

5.2.1. Install Maven

The pom.xml configuration file used in this project requires Maven v2.2.0 or later. Download Maven directly from the Apache Maven homepage, and install and configure your system as described in Procedure 5.1, “Install Maven”.
Procedure 5.1. Install Maven
  1. Verify Java Deleveloper Kit 1.5 or above is installed

    For Linux Users
    Maven is a pure Java application, and requires Java 1.5 or later.
    Ensure you have Java installed on your system, and have set the JAVA_HOME environment variable in your ~/.bash_profile.

    Publican 1.0 requires Java OpenJDK

    Publican 1.0 requires Java OpenJDK (jre-1.6.0-openjdk), because of a dependency with the FOP renderer. PDF generation may be affected if you install a Sun JDK version. HTML generation is unaffected, as is the ability to create books and validate your XML to Publican standards.
    For Windows Users
    Maven requires the Sun Microsystems Java Development Kit (JDK). The Java Runtime Environment (JRE) is not sufficient. You can obtain the JDK from the Java SE Downloads page.
    The JAVA_HOME environment variable must be set for Maven to execute on Windows systems. Setting JAVA_HOME is covered later in this procedure.
  2. Download Maven

    Click the compiled zip archive link, for example apache-maven-2.2.1-bin.zip
    Select a download mirror from the list.
    For Linux Users
    Save the zip archive to your /home directory.
    For Windows Users
    Save the zip archive to your C:\Documents and Settings\user_name directory.
  3. Install Maven

    For Linux Users
    Extract the zip file to your /home directory. If you selected the zip archive in Step 2, and do not rename the directory, the extracted directory is named apache-maven-2.2.1.
    For Windows Users
    Extract the zip archive to C:\Program Files\Apache Software Foundation. If you selected the zip archive in Step 2, and do not rename the directory, the extracted directory is named apache-maven-2.2.1.
  4. Configure Environment Variables

    For Linux Users
    Add the following lines to your ~/.bash_profile. Ensure you change the <username> to your actual username.
    export M2_HOME=/home/<username>/apache-maven-2.2.1
    export M2=$M2_HOME/bin
    export PATH=$M2:$PATH
    
    By inluding M2 at the beginning of your path, the Maven version you just installed will be the default version used.
    For Windows Users
    Add the M2_HOME, M2, and JAVA_HOME environment variables.
    1. Press Start+Pause|Break. The System Properties dialog box is displayed.
    2. Click the Advanced tab, then click the Environment Variables button.
    3. Under System Variables, select Path.
    4. Click Edit, and append the two Maven paths using a semi-colon to separate each entry. Quotation marks are not required around paths.
      • Add the variable M2_HOME and set the path to C:\Program Files\Apache Software Foundation\apache-maven-2.2.1.
      • Add the variable M2 and set the value to %M2_HOME%\bin.
    5. In the same dialog, create the JAVA_HOME environment variable:
      • Add the variable %JAVA_HOME% and set the value to the location of your JDK. For example C:\Program Files\Java\jdk1.6.0_02.
    6. In the same dialog, update or create the Path environment variable:
      • Add the variable %M2% to allow Maven to be executed from the command-line.
      • Add the variable %JAVA_HOME%\bin to set the path to the correct Java installation.
    7. Click OK until the System Properties dialog box closes.
  5. Implement changes to .bash_profile

    For Linux Users Only
    To update the changes made to the .bash_profile in the current terminal session, source your .bash_profile.
    [localhost]$ source ~/.bash_profile
    
  6. Update gnome-terminal profile

    For Linux Users Only
    Update the terminal profile to ensure that subsequent iterations of gnome-terminal (or Konsole terminal) read the new environment variables.
    1. Click EditProfiles
    2. Select Default, and click the Edit button.
    3. In the Editing Profile dialog, click the Title and Command tab.
    4. Select the Run command as login shell check box.
    5. Close all open Terminal dialog boxes.
  7. Verify the .bash_profile changes and Maven install

    For Linux Users
    To verify that the changes have been implemented correctly, open a terminal and execute the following commands:
    • Execute echo $M2_HOME, which should return the following result.
      [localhost]$ echo $M2_HOME
      /home/username/apache-maven-2.2.1
      
    • Execute echo $M2, which should return the following result.
      [localhost]$ echo $M2
      /home/username/apache-maven-2.2.1/bin
      
    • Execute echo $PATH, and verify the Maven /bin directory is included.
      [localhost]$ echo $PATH
      /home/username/apache-maven-2.2.1/bin
      
    • Execute which mvn, which should display the path to the Maven executable.
      [localhost]$ which mvn
      ~/apache-maven-2.2.1/bin/mvn
      
    • Execute mvn -version, which should display the Maven version, related Java version, and operating system information.
      [localhost]$ $ mvn -version
      Apache Maven 2.2.1 (r801777; 2009-08-07 05:16:01+1000)
      Java version: 1.6.0_0
      Java home: /usr/lib/jvm/java-1.6.0-openjdk-1.6.0.0/jre
      Default locale: en_US, platform encoding: UTF-8
      OS name: "linux" version: "2.6.30.9-96.fc11.i586" arch: "i386" Family: "unix"
      
    For Windows Users
    To verify that the changes have been implemented correctly, open a terminal and execute the following command:
    • In a command prompt, execute mvn -version
      C:\> mvn -version
      Apache Maven 2.2.1 (r801777; 2009-08-06 12:16:01-0700)
      Java version: 1.6.0_17
      Java home: C:\Sun\SDK\jdk\jre
      Default locale: en_US, platform encoding: Cp1252
      OS name: "windows xp" version: "5.1" arch: "x86" Family: "windows"
      
You have now successfully configured Maven for use with jDocBook.

5.2.2. Install Publican

Publican is a publication system, not just a DocBook processing tool. As well as ensuring your DocBook XML is valid, Publican works to ensure your XML is up to a publishable and translatable standard.
Refer to Section 4.2, “Publican” for a basic overview, and links to Publican resources such as the Publican User Guide.
Install the JBoss Community publican brand as part of your installation.

5.3. Create Book Repository

You can use Publican to create a base documentation repository for you with the files required for Publican validity. Refer to Creating a Document in the Publican User Guide for detailed instructions. The basic procedure is described in Procedure 5.2, “Create a Publican Book”.
Procedure 5.2. Create a Publican Book
In this procedure, replace the book_name placeholder with the name of the book you want to create. The name must not contain spaces.
  1. Navigate to your documentation directory

    Create a directory in your project for your documentation and move into that directory.
    Most JBoss Community projects commonly choose to locate their documentation repository as a child folder in their /trunk SVN repository. This is recommended, because it allows to keep your documentation as a version snapshot when you branch your project source code.
  2. Call Publican

    Execute the following command to create a basic US English Publican book, which uses the JBoss Community brand package.
    [localhost]$ publican create --name book_name --brand jboss-community
    

5.4. Build with Publican

Before beginning to customize your newly created Publican book, you should publish your book to verify that it meets requirements.
Procedure 5.3. Build Your Book
In this procedure, replace the book_name placeholder with the name of the book you created.
  1. Navigate to the book directory

    Assuming you created your book in the /home directory, navigate to the book_name directory and obtain a directory listing.
    [home]$ cd book_name
    [book_name$]$ ls
    en-US   publican.cfg
    
  2. Publish the book

    The book_name directory contains the en-US folder, and the publican.cfg settings file. This is the directory that you execute all Publican publish commands from.
    To publish your book to PDF, execute the following command:
    [book_name]$ publican build --langs=en-US --formats=pdf
    
  3. View the published output

    After the publican build has completed successfully, the book_name directory contains the tmp folder. This directory contains the files produced as part of the Publican build.
    To view the published output, navigate to the /tmp/en-US/pdf directory and open the PDF to review the published book.

5.5. Build with jDocBook

You have created your book, and verified that it publishes using Publican. The next step is to add the maven elements to your book.

5.5.1. xi:include Fallbacks

To ensure jDocBook can publish the content generated by Publican, additional XML content is required in your documentation repository. jDocBook does not have access to the Publican Common_Content directory, therefore the required XML files must be included as xi:fallback references in the preface.xml and book_info.xml files.
Procedure 5.4. Obtaining local copies of front-matter XML
In this procedure, replace the book_name and [user] placeholders with the correct values.
This procedure assumes you are using a Linux-based operating system, Publican is installed and correctly configured, and your book_name directory is located in your /home directory.

Note

The front matter mentioned in this procedure is available in the sample project, or in the /extras directory (if you installed the rpm package of this user guide).
  1. Navigate to the Publican Common_Content directory

    Navigate to the Common_Content directory and obtain a directory listing.
    [localhost]$ cd /usr/share/publican/Common_Content/
    [Common_Content]$ ls
    common   JBoss_Community
    
  2. Create the fallback_content directory in your book repository

    Create a fallback_content directory in your book_name/en-US directory.
    [Common_Content]$ mkdir /home/[user]/book_name/en-US/fallback_content/
    
  3. Copy the front matter files into your book repository

    Navigate to the en-US directory of the /common directory and obtain a directory listing.
    [Common_Content]$ cd /common/en-US/
    [Common_Content]$ ls
    Conventions.xml   css   Feedback.xml   images  Legal_Notice.xml
    
    Copy Conventions.xml, Feedback.xml and Legal_Notice.xml to your book_name directory.
    [Common_Content]$ cp Conventions.xml Feedback.xml Legal_Notice.xml /home/[user]/book_name/en-US/fallback_content/
    

Fallback Content Ownership

The front-matter information located in the fallback_content directory of each user guide is now your project's responsibility. You can customize the information to suit your project.
Now you have created local copies of the front-matter to include in your book, you must add the content as XML fallbacks to certain files in your Preface.xml and Book_Info.xml files. Refer to Procedure 5.5, “Inserting xi:fallback links” for instructions relating to including xi:fallbacks. Table 5.1, “jDocBook Content” describes the fallback files in more detail.
XML Component Description Order of Component in the Book
Conventions.xml Contains typographical standards used within the guide. This information is optional, and can be included at the discretion of your project. Inserted by xi:fallback reference at the middle of the Preface.xml file.
Feedback.xml Contains information about how to raise a bug against the user documentation. Consider customizing this information to help readers raise issues against your documentation. Inserted by xi:fallback reference at the end of the Preface.xml file.
Legal_Notice.xml Contains standardized Red Hat legal information. You can customize this content to suit the legal requirements of your project. Inserted by xi:fallback reference at the end of the Book_Info.xml file
Table 5.1. jDocBook Content

Fallback content is added to each xi:include element that jDocBook does not have access to.
DocBook XML allows any number of xi:fallback elements to be defined for xi:include elements. It is only necessary to define one fallback for jDocBook and Publican interoperability.
Procedure 5.5. Inserting xi:fallback links
This example describes how to set xi:fallback links for jDocBook publishes. The default Publican Common_Content files are used for the enterprise documentation.
  1. Open the file that will contain the XML fallback

    Using the information in Table 5.1, “jDocBook Content”, open the XML file that contains the pre-existing xi:include.
    For example, if you want to include the Feedback.xml file in your book, open the Preface.xml file in an XML editor of your choice.
  2. Locate the xi:include

    In the XML file you opened, search for the xi:include you need to append the xi:fallback to.
    For example, if you want to include the Feedback.xml file fallback in your book, perform a search for "Feedback.xml" to locate the xi:include.
  3. Append the xi:fallback

    It is up to you and your project which files are included in your documentation. If you do not want to include a particular file, you must set a blank xi:fallback so jDocBook can publish your book.
    For fallbacks that resolve to a fallback file
    Insert the fallback so it resolves to the target file in the fallback_content directory. The structure described in the following XML sample is for the Legal_Notice.xml information in the Book_Info.xml file.
    <!--FOR PUBLICAN -->
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
     href="Common_Content/Legal_Notice.xml">
        <!--FOR JDOCBOOK:-->
        <xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude">
            <xi:include href="fallback_content/Legal_Notice.xml"
             xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
        </xi:fallback>
    </xi:include>
    
    For fallbacks that exclude a Common_Content fallback file
    You must still specify how jDocBook parses front-matter files that you do not want to include in your book. The xi:fallback is still required, because jDocBook still needs a processing instruction when it encounters the Common_Content files. The structure described in the following XML sample shows how to exclude the Legal_Notice.xml information in the Book_Info.xml file when you publish to jDocBook.
    <!--FOR PUBLICAN -->
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
     href="Common_Content/Legal_Notice.xml">
        <!--FOR JDOCBOOK:-->
        <xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude"/>
    </xi:include>
    

5.5.2. Insert .ent Parameter Entities

Publican references the book_name.ent file for all entities contained within your book. Local entities declared in the DOCTYPE declaration will cause Publican builds to fail.
To ensure jDocBook and Publican can parse the entities declared throughout your book, you must append a parameter entity to each DOCTYPE declaration in your book's XML files. The parameter entity specifies the location of the book_name.ent file, then calls the file as part of a single parameter entity delcared in each XML file's DOCTYPE declaration.

Bulk Append

If you have a number of files to convert initially, you may find it easier to use a command line utility to append the entity declaration. Refer to Procedure 5.7, “Adding parameter entities using the command line” for instructions relevant to large conversions.
Procedure 5.6. Adding parameter entities manually
This procedure describes the method to manually insert a parameter entity declaration into the XML DOCTYPE declaration.
In this procedure, replace the book_name placeholder with the name of the book you created.
  1. Open the XML file

    Open the XML file that must contain the parameter entity in a text editor.
  2. Locate the DOCTYPE declaration

    The DOCTYPE declaration is located at the very beginning of the file. For example, a <section> DOCTYPE declaration will look similar to the following sample.
    <?xml version='1.0' encoding='UTF-8'?>
    <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "docbookV4.5/docbookx.dtd" [
    ]>
    
    For <chapter> XML files, change the DOCTYPE declaration to chapter.

    DOCTYPE declarations are mandatory

    If the XML file does not contain a DOCTYPE declaration, you must add the correct declaration to the XML file.
  3. Append the parameter entity to the DOCTYPE declaration

    The parameter entity declaration sets the BOOK_ENTITIES entity. The entity resolves to the book_name.ent file in your book's repository.
    <!ENTITY % BOOK_ENTITIES SYSTEM "book_name.ent">
    %BOOK_ENTITIES;]>
    
    The entity is declared, then subsequently called in the DOCTYPE by specifying %BOOK_ENTITIES in the DOCTYPE declaration.
    <!ENTITY % BOOK_ENTITIES SYSTEM "book_name.ent">
    %BOOK_ENTITIES;
    
    Insert the parameter entity declaration between the square brackets ([ and ]) in the DOCTYPE declaration.
    <?xml version='1.0' encoding='UTF-8'?>
    <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "docbookV4.5/docbookx.dtd" [
    <!ENTITY % BOOK_ENTITIES SYSTEM "book_name.ent">
    %BOOK_ENTITIES;
    ]>
    
  4. Repeat for all files in your repository

    Append the parameter entity to all files in your book repository. This includes any files in your fallback_content directory.
Procedure 5.7. Adding parameter entities using the command line
This procedure describes adding the parameter entity declaration to XML files by creating, and subsequently running the book_ent script. The procedure assumes you are using a Linux-based operating system.
The script provided is a Bourne Again Shell script, therefore will work on Linux systems only.
In this procedure, replace the book_name placeholder with the name of the book you created.
  1. Create a book_ent shell script

    In your /home directory, create a /bin directory.
    Create an empty file in the /bin directory named book_ent, and add the following code to the file.
    #!/usr/bin/env bash
    for file in *.xml; do
        sed -i -e 's/docbookx.dtd" \[/docbookx.dtd" \[\n<!ENTITY % BOOK_ENTITIES SYSTEM "'${1}'.ent">\n%BOOK_ENTITIES\;/' ${file}; \
    done
    
    
    Make the file executable.
    [bin]$ chmod 777 book_ent
    
  2. Configure Environment Variables

    In your ~/.bash_profile, set the following PATH:
    PATH=$PATH:$HOME/bin
    
    By including the /bin directory as a PATH, you will be able to execute book_ent as a command in any directory. Use /bin to store any other automation scripts you choose to create.
  3. Implement changes to .bash_profile

    To quickly verify the changes to ~/.bash_profile, execute the following commands:
    • Source your .bash_profile.
      [localhost]$ source ~/.bash_profile
      
    • Execute echo $PATH, and verify the /bin directory is included.
      [localhost]$ echo $PATH
      /home/username/bin
      
  4. Navigate to your en-US directory

    In the open terminal, navigate to the location of the en-US directory of your book.
  5. Append the XML DOCTYPE to all XML files in the en-US directory

    In the en-US directory, execute the book_ent script. Substitute book_name with the name of your book_name.ent file. You do not need to specify the .ent file extension.
    [en-US]$ book_ent book_name
    
    All XML files in the en-US directory have now been changed.
  6. Append the XML DOCTYPE to all XML files in sub-directories

    The book_ent script is not recursive. Therefore, you must execute the script for all XML files contained in sub-directories (for example, the fallback_content directory).
    1. Navigate to a sub-directory that contains XML files to update.
    2. Execute the script again, specifying the relative path to the book_name.ent file. Use two backslash characters to escape the forward-slash
      [fallback_content]$ book_ent ..\\/book_name
      
    3. All XML files in the fallback_content directory have now been changed.
    4. Repeat steps one and two for all other sub-directories in your book repository.

5.5.3. Configure pom.xml

The pom.xml file contains the processing instructions for your book. The recommended pom.xml to use is described in Appendix A, pom.xml Multi-Profile.
Procedure 5.8. Configure pom.xml
In this procedure, replace the book_name placeholder with the name of the book you created.
  1. Create a pom.xml file for your project

    Create an empty file named pom.xml in the book_name directory.
    The pom.xml file must be placed at the root directory of your book at the same level as the publican.cfg file.
  2. Copy the base pom.xml

    Take a copy of the base pom.xml described in Appendix A, pom.xml Multi-Profile.
  3. Paste the base pom.xml into the file

    Paste the base pom.xml information into the empty file.
  4. Update the <docname> and <bookname> elements in <properties>

    Replace the placeholder information in <docname> with the book_name XML file name, excluding the .xml file extension. Spaces are not permitted.
    Replace the placeholder information in <bookname> with the title of your book. Spaces are permitted.
    <properties>
        <translation>en-US</translation>
        <docname>JBoss_Documentation_Guide</docname>
        <bookname>JBoss Documentation Guide</bookname>
    </properties>
    
    Example 5.1. <property> block with sample values completed

  5. Save and close the pom.xml file

    Once you have made the required changes specified in this procedure, save and close the pom.xml file.

5.5.4. Publish with jDocBook

You have now added the jDocBook xi:fallback components to the XML in your front-matter, and configured your pom.xml project. You are now ready to publish your user guide using jDocBook.
If you are familiar with Maven and jDocBook you would have noticed the XML comments throughout the pom.xml source. These comments specify the publishing targets.
To publish your book, navigate to the book_name directory, and execute one of the following commands in a terminal.
Multi-output pom.xml Publishing Targets
mvn compile
Executes Maven and produces html, html-single, and PDF deliverables.
mvn compile -Phtml
Executes Maven and produces a HTML multi-page deliverable.
mvn compile -Phtml-single
Executes Maven and produces a HTML single page deliverable.
mvn compile -Ppdf
Executes Maven and produces a PDF deliverable.
Once your book is published, the output target can be viewed by navigating to the output type in the /target/docbook/publish/en-US directory. From this directory, select the target you want to view, and open it in the appropriate program.

Maven Recoverable Errors are OK

For each fallback you created in your documentation, Maven will advise you that it couldn't find the original xi:include, but is reverting to the fallback you specified. This may alarm you when you first see it, but rest assured it is normal behaviour.

5.5.5. Begin Authoring

You have now created your basic book, and can publish this book to both jDocBook and Publican. Now it is time to begin adding actual content to your book.
Before you begin, there are a number of things you need to be aware of. To maintain consistency across all JBoss projects, follow the guidelines specified in Chapter 6, Structure Guidelines, and Chapter 7, Language Guidelines.

Chapter 6. Structure Guidelines

In DocBook, the way some content appears when published relies on a consistently applied XML structure. There are certain additions to structure that can be useful to help the reader to quickly grasp information. The following sections are grouped into common areas that you will use regularly in XML authoring.
To keep book structure consistent, the following guidelines must be followed when creating XML structure in your JBoss user guide.

6.1. Disallowed Elements and Attributes

Supported, unsupported, and disallowed

Not every element and attribute that works with Publican is supported. Specifically, not every element has been tested with regards its effect on the presentation of a document once it has been built in HTML or PDF.
Publican works with almost all DocBook 4.5 elements and their attributes, and most of these elements are supported. Supported elements and attributes are those whose presentation in Publican HTML and PDF output has been tested and is of an acceptable quality.
Other elements and attributes that are not known to be harmful or redundant but which have not been tested for quality are unsupported. If material within a particular DocBook element does not look correct when you build a document in HTML or PDF, the problem could be that the transformation logic for that element has not yet been tested. Build the document again and examine Publican's output as the document builds. Publican presents warnings about unsupported elements that it encounters in your XML files.
Finally, a small group of elements and attributes are disallowed. These elements and attributes are set out below, each accompanied by rationale explaining why it is disallowed.

6.1.1. Disallowed elements

<caution>, <tip>
DocBook XML supports five admonitions of varying severity: <tip>, <note>, <important>, <caution>, and <warning>. Taken together, these represent a very fine-grained set of distinctions. It is unlikely that these fine distinctions can be applied consistently within a document, especially when more than one person writes or maintains the document. Moreover, this level of granularity is meaningless to readers. By design, Publican disallows the <tip> and <caution> elements, these elements being the two most redundant in the set.
Use <note> instead of <tip>, and use either <important> or <warning> instead of <caution>. Some criteria by which you might select a suitable level of severity are presented in the ‘Document Conventions’ section of the preface of books produced with Publican's default brand.
<entrytbl>
Publican depends on an external application, FOP, to render PDF documents. At present, FOP does not support nested tables, so attempts to build PDF files from Publican documents that contain nested tables fail.
Nested tables are therefore disallowed at least until they are supported in FOP. If you planned to include a nested table in your document, reconsider your data structure.
<glossdiv>, <glosslist>
This element set presents terms in glossaries in alphabetical order; however, the terms are sorted according to the original language of the XML, regardless of how these terms are translated into any other language. For example, a glossary produced with <glossdiv>s that looks like this in English:
A
Apple — an apple is…
G
Grapesgrapes are…
O
Orange — an orange is…
P
Peach — a peach is…
looks like this in Spanish:
A
Manzana — la manzana es…
G
Uva — la uva es…
O
Naranja — la naranja es…
P
Melocotonero — el melocotonero es…
In a translated language that does not share the same writing system with the original language in which the XML was written, the result is even more nonsensical.
<inlinegraphic>
This element presents information as a graphic rather than as text and does not provide an option to present a text alternative to the graphic. This element therefore hides information from people with visual impairments. In jurisdictions that have legal requirements for electronic content to be accessible to people with visual impairments, documents that use this element will not satisfy those requirements. Section 508 of the Rehabilitation Act of 1973[1] is an example of such a requirement for federal agencies in the United States.
Note that <inlinegraphic> is not valid in DocBook version 5.
<link>
The <link> element provides a general-purpose hyperlink and therefore offers nothing that the <xref> and <ulink> elements do not, for internal and external hyperlinks respectively. The <link> element is disallowed due to its redundancy.
<olink>
The <olink> element provides cross-references between XML documents. For <olink>s to work outside of documents that are all hosted within the same library of XML files, you must provide a URL for the document to which you are linking. In environments that use <olink>s, these URLs can be supplied either as an XML entity or with a server-side script. Publican produces documents intended for wide dissemination in which URLs are always necessary for cross-references. Therefore, the <olink> element offers no advantage over the <ulink> element, and is disallowed due to its redundancy.

6.1.2. Disallowed attributes

<[element] xreflabel="[any_string_here]">
The presence of an <xreflabel> attribute reduces the usability of printed versions of a book. As well, attribute values are not seen by translators and, consequently, cannot be translated.
For example, if you have the following:
<chapter id="ch03" xreflabel="Chapter Three">
 <title>The Secret to Eternal Life</title>
 <para>The secret to eternal life is…</para>
</chapter>

[more deathless prose here]     

…see <xref linkend="ch03"> for details.
when your XML is built to HTML, the <xref> element becomes an HTML anchor element as follows:
…see <a href="#ch03">Chapter Three</a> for details.
The text contained by the anchor element is the same as the data in the <xreflabel> attribute. In this case, it means that readers of printed copies have less information available to them.
You could work around this if you make the value of the <xreflabel> attribute the same as the text within the <title></title> element. However, this duplication increases the risk of typo-level errors and otherwise offers no underlying improvement. And it still reduces the amount of information presented to readers of printed copies.
The following XML:
<chapter id="ch03" xreflabel="The Secret to Eternal Life">
 <title>The Secret to Eternal Life</title>
 <para>The secret to eternal life is…</para>
</chapter>

[more deathless prose here]     

…see >xref linkend="ch03"> for details.
Will result in an HTML anchor element as follows:
…see <a href="#ch03">The Secret to Eternal Life</a> for details.
This is not as informative as the text presented to a reader if you do not use an <xreflabel> attribute. The following:
<chapter id="ch03">
 <title>The Secret to Eternal Life</title>
 <para>The secret to eternal life is…</para>
</chapter>

[more deathless prose here]  

…see <xref linkend="ch03"> for details.
transforms the <xref> element as follows when built to HTML:
…see <a href="#ch03">Chapter 3: The Secret to Eternal Life</a> for details.
More important, however, are the translation problems that <xreflabel> elements cause. Attribute values are not seen by translators. Consequently, they are not translated. Consider the second example above again:
<chapter id="ch03" xreflabel="The Secret to Eternal Life">
 <title>The Secret to Eternal Life</title>
 <para>The secret to eternal life is…</para>
</chapter>

[more deathless prose here]  

…see <xref linkend="ch03"> for details.
In English, the <xref> is still transformed into an anchor element as follows:
…see <a href="#ch03">The Secret to Eternal Life</a> for details.
Someone reading the German version, however, will have this as their underlying HTML:
…Sehen Sie <a href="#ch03">The Secret to Eternal Life</a> für Details.
If the <xreflabel> attribute is not used, the title and chapter indicator, both properly translated, appear to the reader. That is, the following:
<chapter id="ch03">
 <title>The Secret to Eternal Life</title>
 <para>The secret to eternal life is…</para>
</chapter>

[more deathless prose here]  

…see <xref linkend="ch03"> for details.
will, after translation, present thus to a German-speaking reader:
…Sehen Sie <a href="#ch03">Kapitel 3: Das Geheimnis des ewigen Lebens</a> für Details.
This is, not surprisingly, what we want.
The xreflabel attribute is therefore disallowed.
<[element] endterm="[any_string_here]">
The endterm attribute allows you to present hyperlinked text other than the name of the section or chapter to which the hyperlink points. As such, it decreases the usability of printed versions of documents, and causes difficulty for translators.
The text presented in an element (such as an <xref>) that contains the endterm attribute is taken from a <titleabbrev> element in the target chapter or section. Although the content of the <titleabbrev> element is available to translators in the document's PO files, it is removed from the context of the <xref>. The absence of this context makes reliable translation impossible in languages that mark prepositions or articles for grammatical number and grammatical gender.
For example, if you have the following:
<chapter id="The_Secret">
 <title>The Secret to Eternal Life</title>
 <titleabbrev id="final">the final chapter</titleabbrev>

 <para>The secret to eternal life is…</para>
</chapter>

[more deathless prose here]     

The solution is in <xref linkend="The_Secret" endterm="final"/>.
The text surrounding the <xref> presents in the English version of the document as:
The solution is in the final chapter.
A translator sees the <titleabbrev> in a PO file as:
#. Tag: titleabbrev
#, no-c-format
msgid "the final chapter"
msgstr ""
and sees the text that contains the <xref> elsewhere in the PO file (or, more likely, in a completely different PO file) as:
#. Tag: para
#, no-c-format
msgid "The solution is in <xref linkend="The_Secret" endterm="final"/>."
msgstr ""
The translator has no way of telling what will be substituted for <xref linkend="The_Secret" endterm="final"/> when the document builds, so a translation in Italian might read:
#. Tag: para
#, no-c-format
msgid "The solution is in <xref linkend="The_Secret" endterm="final"/>."
msgstr "La soluzione è in <xref linkend="The_Secret" endterm="final"/>."
Note the preposition in.
If the translator rendered the final chapter in Italian as l'ultimo capitolo, the result when the document builds will read:
La soluzione è in l'ultimo capitolo.
This result is comprehensible, but inelegant, because Italian combines some of its prepositions with its definite articles. More elegant Italian would be:
La soluzione è nell'ultimo capitolo.
Without knowing what text will appear in place of <xref linkend="The_Secret" endterm="final"/>, the translator into Italian cannot know whether to leave the preposition in to stand by itself, or which of seven different possible combinations with the definite article to use: nel, nei, nello, nell', negli, nella, or nelle.
Furthermore, note that the combined preposition and article also poses a problem with regard to whether this word should be placed in the text surrounding the <xref>, or in the <titleabbrev>. Whichever of these two solutions the translator selects will cause problems when the endterm appears in other grammatical contexts, because not all Italian prepositions can combine with the definite article in this way.
Due to the problems that endterm presents for translation, Publican disallows this attribute.

6.2. Entities

Use entities with extreme caution

Entities offer convenience but they should be used with extreme caution in documents that will be translated. Writing (for example) &FDS; instead of Fedora Directory Server saves the writer time but transformed entities do not appear in the portable object (PO) files that translators use. Complete translations of documents containing entities are, as a consequence, impossible.
Entities present special obstacles to translators and can preclude the production of high-quality translations. The very nature of an entity is that the word or phrase represented by the entity is rendered exactly the same way every time that it occurs in the document, in every language. This inflexibility means that the word or word group represented by the entity might be illegible or incomprehensible in the target language and that the word or word group represented by the entity cannot change when the grammatical rules of the target language require them to change. Furthermore, because entities are not transformed when XML is converted to PO, translators cannot select the correct words that surround the entity, as required by the grammatical rules of the target language.
If you define an entity — <!ENTITY LIFT "Liberty Installation and Formatting Tome"> — you can enter &LIFT; in your XML and it will appear as Liberty Installation and Formatting Tome every time the book is built as HTML, PDF or text.
Entities are not transformed when XML is converted to PO, however. Consequently, translators never see Liberty Installation and Formatting Tome. Instead they see &LIFT;, which they cannot translate.
Consider something as simple as the following English sentence fragment being translated into a related language: German.
As noted in the Liberty Installation and Formatting Tome, Chapter 3…
A translation of this might be as follows:
Wie in dem Wälzer für die Installation und Formatierung von Liberty, Kapitel 3, erwähnt…
Because there is no text missing, the title can be translated into elegant German. Also, note the use of ‘dem’, the correct form of the definite article ('the') when referring to a Wälzer ('tome') in this grammatical context.
By contrast, if entities are used, the entry in the PO file says:
#. Tag: para
#, no-c-format
msgid "As noted in the <citetitle>&LIFT;</citetitle>, Chapter 3…"
msgstr ""
The translation of this would probably run thus:
#. Tag: para
#, no-c-format
msgid "As noted in the <citetitle>&LIFT;</citetitle>, Chapter 3…"
msgstr "Wie in <citetitle>&LIFT;</citetitle>, Kapitel 3, erwähnt…"
And the presentation would be thus:
Wie in Liberty Installation and Formatting Tome, Kapitel 3, erwähnt…
This, of course, leaves the title in English, including words like 'Tome' and 'Formatting' that readers are unlikely to understand. Also, the translator is forced to omit the definite article ‘dem’, a more general construction that comes close to a hybrid of English and German that German speakers call Denglisch or Angleutsch. Many German speakers consider this approach incorrect and almost all consider it inelegant.
Equivalent problems emerge with a fragment such as this:
However, a careful reading of the Liberty Installation and Formatting Tome afterword shows that…
With no text hidden behind an entity, a German translation of this might be:
Jedoch ergibt ein sorgfältiges Lesen des Nachworts für den Wälzer für die Installation und Formatierung von Liberty, dass…
If an entity was used to save the writer time, the translator has to deal with this:
#. Tag: para
#, no-c-format
msgid "However, a careful reading of the <citetitle>&LIFT;</citetitle> afterword shows that…"
msgstr ""
And the translation would be subtly but importantly different:
#. Tag: para
#, no-c-format
msgid "However, a careful reading of the <citetitle>&LIFT;</citetitle> afterword shows that…"
msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle>&LIFT;</citetitle>, dass…"
When presented to a reader, this would appear as follows:
Jedoch ergibt ein sorgfältiges Lesen des Nachworts für Liberty Installation and Formatting Tome, dass…
Again, note the missing definite article (den in this grammatical context). This is inelegant but necessary since the translator can otherwise only guess which form of the definite article (den, die or das) to use, which would inevitably lead to error.
Finally, consider that although a particular word never changes its form in English, this is not necessarily true of other languages, even when the word is a proper noun such as the name of a product. In many languages, nouns change (inflect) their form according to their role in a sentence (their grammatical case). An XML entity set to represent an English noun or noun phrase therefore makes correct translation impossible in such languages.
For example, if you write a document that could apply to more than one product, you might be tempted to set an entity such as &PRODUCT;. The advantage of this approach is that by simply changing this value in the Doc_Name.ent file, you could easily adjust the book to document (for example) Red Hat Enterprise Linux, Fedora, or CentOS. However, while the proper noun Fedora never varies in English, it has six different forms in Czech, depending on one of seven ways that you can use it in a sentence:
Case Usage Form
Nominative the subject of a sentence Fedora
Genitive indicates possession Fedory
Accusative the direct object of a sentence Fedoru
Dative the indirect object of a sentence Fedoře
Vocative the subject of direct address Fedoro
Locative relates to a location Fedoře
Instrumental relates to a method Fedorou
Table 6.1. 'Fedora' in Czech

For example:
  • Fedora je linuxová distribuce. — Fedora is a Linux distribution.
  • Inštalácia Fedory — Installation of Fedora
  • Stáhnout Fedoru — Get Fedora
  • Přispějte Fedoře — Contribute to Fedora
  • Ahoj, Fedoro! — Hello Fedora!
  • Ve Fedoře 10… — In Fedora 10…
  • S Fedorou získáváte nejnovější… — With Fedora, you get the latest…
A sentence that begins S Fedora získáváte nejnovější… remains comprehensible to Czech readers, but the result is not grammatically correct. The same effect can be simulated in English, because although English nouns lost their case endings during the Middle Ages, English pronouns are still inflected. The sentence, 'Me see she' is completely comprehensible to English speakers, but is not what they expect to read, because the form of the pronouns me and she is not correct. Me is the accusative form of the pronoun, but because it is the subject of the sentence, the pronoun should take the nominative form, I. Similarly, she is nominative case, but as the direct object of the sentence the pronoun should take its accusative form, her.
Nouns in most Slavic languages like Russian, Ukrainian, Czech, Polish, Serbian, and Croatian have seven different cases. Nouns in Finno–Ugaric languages such as Finnish, Hungarian, and Estonian have between fifteen and seventeen cases. Other languages alter nouns for other reasons. For example, Scandinavian languages inflect nouns to indicate definiteness — whether the noun refers to 'a thing' or 'the thing' — and some dialects of those languages inflect nouns both for definiteness and for grammatical case.
Now multiply such problems by the more than 40 languages that Publican currently supports. Other than the few non-translated strings that Publican specifies by default in the Doc_Name.ent file, entities might prove useful for version numbers of products. Beyond that, the use of entities is tantamount to a conscious effort to inhibit and reduce the quality of translations. Furthermore, readers of your document in a language that inflects nouns (whether for case, definiteness, or other reasons) will not know that the bad grammar is the result of XML entities that you set — they will probably assume that the translator is incompetent.

6.3. Chapters and Sections

Chapters and Sections form the underlying skeleton for each guide. Therefore, structuring these important elements consistently is important.
New Chapter or Section
Over the life of a product, user guides often require content to be reorganized. Having sections directly included in a chapter, can make reordering book structure difficult. For this reason, when adding a <chapter> or <section> to an existing user guide, each <chapter> and <section> must be a separate XML file.
The file must be included in the book using a xi:include reference. See Section 5.5.1, “xi:include Fallbacks” for examples of xi:include syntax.
Naming Chapter or Section XML Files
A complete XML user guide may consist of a large number of XML files. Each file included in the book should be logically, and consistently, named so it is easy to include a file where it is required in the book's structure. For information about recommended file naming standards, refer to Table B.1, “Book Components” in Appendix B, Sample Project.
ID Attributes for Chapter or Section XML Files
To allow cross-referencing within the book, the id attribute must be set for each chapter or section. The format for the chapter or section ID is explicit, to ensure cross-referencing within each user guide is consistent. For more information about links and references, refer to Section 6.14, “Links and References”
The id attribute is applied to the <chapter> or <section> element, and uses the following format:
  • <chapter id="chap-Book_Name-Chapter_Title">
  • <section id="sect-Book_Name-Chapter_Title-Section_Title">
For example, the XML ID of this section would be <section id="sect-JBoss_Documentation_Guide-Structure_Guidelines-Chapters_and_Sections">.

6.4. Lists

The two most common list types in DocBook are not named according to such programs as Microsoft Word, or Open Office. You would think that for a bulleted list, you would start the list using <bullets> or <bulletedlist>. Likewise, for a numbered list, you might consider using <numlist> or <numberedlist>.
In DocBook, these types of lists are referred to according to the following nomenclature:
  • Bulleted List - <itemizedlist>
  • Numbered List - <orderedlist>

<orderedlist> is no substitute for <procedure>

If you are documenting a complex set of steps, you must use a <procedure> to contain the steps. Procedures can contain multiple steps, and offer greater content flexibility. For more information about <procedure>, refer to Section 6.5, “Procedures”

Lead-in Sentence is Mandatory

A list must have an introductory sentence, and it must not be a sentence fragment. Sentence fragments are very hard to translate.
<itemizedlist>
An itemized list is used to replace a semi-colon separated list in a sentence.
The XML form of an itemized list has a number of mandatory elements. For a complete list, refer to the DocBook.org <itemizedlist> page.
<itemizedlist>
    <listitem>
        <para>Item One.</para>
    </listitem>
    <listitem>
        <para>Item Two.</para>
    </listitem>
    <listitem>
        <para>Item Three.</para>
    </listitem>
</itemizedlist>
The XML Structure looks like this when published:
  • Item One.
  • Item Two.
  • Item Three.
Example 6.1. <itemizedlist> Mandatory Elements

You can further enhance the <itemizedlist> by adding in a <title> element after the opening <itemizedlist> element. A title might assist the reader with understanding what a large list contains. The XML structure looks like this when published:
<itemizedlist> Title
  • Item One.
  • Item Two.
  • Item Three.
<orderedlist>
An <orderedlist> is just like an <itemizedlist>, except it displays the content in number order. This type of list is better suited to listing small sub-steps in <procedure> lists.
The XML form of an itemized list has a number of mandatory elements. For a complete list, refer to the DocBook.org <itemizedlist> page.
<orderedlist>
    <listitem>
        <para>Item One.</para>
    </listitem>
    <listitem>
        <para>Item Two.</para>
    </listitem>
    <listitem>
        <para>Item Three.</para>
    </listitem>
</orderedlist>
You can further enhance the <orderedlist> by adding in a <title> element after the opening <orderedlist> element. A title might assist the reader with understanding what a large list contains.
The XML structure looks like this when published:
<orderedlist> Title
  1. Item One.
  2. Item Two.
  3. Item Three.
Example 6.2. <orderedlist> Mandatory Elements

<variablelist>
A <variablelist> can be used to define a list of terms, or in situations where a table of only two columns might be used. Variable lists can have optional titles.
<variablelist>
	<title>This Title is Optional</title>
	<varlistentry>
		<term>This is the first term</term>
		<listitem>
			<para>Here are the item details for the first term.</para>
		</listitem>
	</varlistentry>
	<varlistentry>
		<term>This is the second term</term>
		<term>this is the third term</term>
		<listitem>
			<para>Here are the item details for the second and third terms.</para>
		</listitem>
	</varlistentry>
</variablelist>

This Title is Optional
This is the first term
Here are the item details for the first term.
This is the second term, this is the third term
Here are the item details for the second and third terms.
Example 6.3. <variablelist> example

6.5. Procedures

When it is necessary to document a complex set of installation instructions, an <orderedlist> is usually not the best XML element to choose. It has limitations regarding what level of detail each <listitem> element can contain.
The best option for large work-flows, or detailed steps, is the <procedure> element.
You may not be aware, but this element is used extensively throughout this user guide to capture the steps involved in the Authoring Process.
The biggest advantage to using a <procedure> element is that it uses the <step> element. <step> elements can contain a much wider variety of child elements than the <listitem> element used in <itemizedlist> and <orderedlist>.
The XML form of a procedure has a number of mandatory elements. For a complete list, refer to the DocBook.org <procedure> page. Be sure to visit the pages of the child elements that the <procedure> element supports, particularly the <step> element.
The minimum set of elements required for all procedure lists in the Mobicents UDS are described in the following example:
<procedure>
  <title><procedure> Title</title>
  <step>
    <title>Step One Title</title>
    <para>Step one info.</para>
  </step>
  <step>
    <title>Step Two Title</title>
    <para>Step two info.</step>
</procedure>
The XML structure looks like this when published:
Procedure 6.1. <procedure> Title
  1. Step One Title

    Step one info.
  2. Step Two Title

    Step two info.
Example 6.4. <procedure> Mandatory Elements

You can further enhance the <procedure> by adding in any number of supported child elements into each <step>. Each <step> can contain any number of <para> elements, and also permits <itemizedlist> and <orderedlist> elements. Be sure that the elements inserted are not included in Section 6.1.1, “Disallowed elements”.
<procedure>
	<title>&lt;procedure&gt; Title</title>
		<step>
			<title>Step 1 Title</title>
			<para>Step one info.  You can have multiple <sgmltag>&lt;para&gt;</sgmltag> elements, in one step.</para>
			<para>Second para to further describe step.  </para>
		</step>
		<step>
			<title>Step 2 Title</title>
			<para>If you find you need sub-steps, use an <sgmltag>&lt;orderedlist&gt;</sgmltag> to capture these:</para>
			<para>The ordered list should have a lead-in sentence introducing the list:</para>
			<orderedlist>
				<listitem>
					<para>Sub-step one.</para>
				</listitem>
				<listitem>
					<para>Sub-step two, etc.</para>
				</listitem>
			</orderedlist>
		</step>
</procedure>

Procedure 6.2. <procedure> Title
  1. Step 1 Title

    Step one info. You can have multiple <para> elements, in one step.
    Second para to further describe step.
  2. Step 2 Title

    If you find you need sub-steps, use an <orderedlist> to capture these:
    The ordered list should have a lead-in sentence introducing the list:
    1. Sub-step one.
    2. Sub-step two, etc.
Example 6.5. <procedure> Extra Elements

6.6. Tables

Depending on the authoring tools you use to edit your XML documentation, inserting tables may take a few mouse clicks. If you prefer to author in plain text mode, you will need sound knowledge of XML table structure so the table you create is valid, and looks the way you want it to when published.
For many new XML authors, tables cause a lot of problems . This section describes the components of an XML table, and includes an XML sample of a three column table. The concept of splitting cells in a row is also discussed.
For the definitive list of table elements and attributes, refer to the Docbook.org <table> page.

Consider <variablelist> for two-column tables

In certain situations, a table that would otherwise only have two columns may be better implemented as a variable list, using the <variablelist> element (see Section 6.4, “Lists”).
The majority of tables used throughout JBoss documentation are classed as formal tables. In contrast to informal tables, formal tables always feature a <title> that gives the reader a basic summary of the table contents. A formal table consists of the following structural elements (in order):
<table>
The parent element of all formal tables, which contains all the child elements. <table> accepts attributes that control how the table is processed at publish time. The frame and pgwide attributes are applied to the <table> element.
<tgroup>
Below the <table> element, the <tgroup> element contains the information that governs the basic framework of your table. <tgroup> contains settings that govern the amount of columns in the table, along with the <row> structural information. <tgroup> also contains column and span specifications required to set the table geometry and cell formatting.
<thead>
Defines the column headers for the table. <thead> is also used if you include a table footer, however table footers are not common in JBoss documentation.
<colspec>
Defines the column specifications for the table. Column and row separators, and column widths, are specified as attributes of this element. <colspec> is also used if you include a header (<thead>)
<tbody>
<tbody> is a wrapper element for the <row> elements that comprise the table. Generally, no attributes are applied to the <tbody> element.
<row>
Defines a row in the table, and contains the <entry> elements that comprise each cell in the table.
<entry>
Defines a cell in the table. Each cell can contain block elements or inline elements, but not both concurrently.
For example, one <entry> might contain a paragraph or a list while another <entry> contains parsed character data (#PCDATA), but no single <entry> can contain a mixture of both.
<table frame="all" pgwide="1">
  <title>Three-column Table</title>
  <tgroup colsep="1" cols="3">
    <colspec colnum="1" colname="c0"/>
    <colspec colnum="2" colname="c1"/>
    <colspec colnum="3" colname="c2"/>
    <thead>
      <row>
        <entry>Header Row, Column 1</entry>
        <entry>Header Row, Column 2</entry>
        <entry>Header Row, Column 3</entry>
      </row>
    </thead>
    <tbody>
      <row>
        <entry>A</entry>
        <entry>B</entry>
        <entry>C</entry>
      </row>
      <row>
        <entry>D</entry>
        <entry>E</entry>
        <entry>F</entry>
      </row>
      <row>
        <entry>G</entry>
        <entry>H</entry>
        <entry>I</entry>
      </row>
      <row>
        <entry>J</entry>
        <entry>K</entry>
        <entry>L</entry>
      </row>
    </tbody>
  </tgroup>
</table>

Example 6.6. Three-column Table

When published, the XML structure described in Example 6.6, “Three-column Table” publishes in the following way.
Header Row, Column 1 Header Row, Column 2 Header Row, Column 3
A B C
D E F
G H I
J K L
Table 6.2. Three-column Table

Merging Cells Horizontally (spanning cells)
Merging cells horizontally is controlled by specifying the namest and nameend attributes in the <entry> element. The colname value of the starting column and the finishing column are specified in the <entry> element that you want the cell span to start from.
This example describes how to merge the B and C cells together in Table 6.2, “Three-column Table” using the namest and nameend attributes.
In the <thead> element of the table, the <colspec> element has two attributes specified: colnum and colname. By default, the colname attribute starts from c0.
To span the B and C cells, you need to specify namest="c1" as the starting cell (the second column) and nameend="c2" as the finishing cell (the third column).
<row>
  <entry>A</entry>
  <entry namest="c1" nameend="c2">BC</entry>
</row>
<row>
  <entry>D</entry>
  <entry>E</entry>
  <entry>F</entry>
</row>
Example 6.7. Cell spanning

6.7. Emphasis (Bold, Italic, Underline)

In DocBook v4.5, the <emphasis> element supports attributes that allow you to override default stylesheet behaviour. Do not use attributes such as bold, italic, or underline to alter text enclosed in <emphasis> elements.
Remember that XML authoring separates content from style. By applying attributes in this way, you are effectively introducing style into your content.
If you want to change the way the <emphasis> element formats the text at publish time, you should consider updating the stylesheet, and not "work around" the problem by applying attributes.

6.8. Graphics and Screenshots

There are a number of graphical elements that are supported in DocBook. For consistency, the best element to use is <figure>.
The <figure> element has the advantage of containing a well-formatted title for the image. It is suitable for both diagrams, and screenshots, which are included through the use of the <mediaobject> element. The <mediaobject> element must also contain a <textobject> element with a description of the image for accessibility purposes.

Screenshots increase user guide maintenance

Think carefully before inserting a screen shot. Often, you can explain what fields a user must complete in the user interface without a screen shot. If you can, you will save a lot of maintenance in the future.
Screenshots increase the maintenance of a user guide. What happens if the interface changes? What happens if the product logo is updated? These situations require the screen shot to be recaptured again.
<figure>
  <title>JBoss Community Logo</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/img-JBoss_Community_Logo.png" format="PNG"/>
    </imageobject>
    <textobject>
      <para>Logo for the JBoss Community<para>
    </textobject>
  </mediaobject>
</figure>
Example 6.8. <figure> element structure

The XML structure looks like this when published:
JBoss Community Logo
Logo for the JBoss Community
Figure 6.1. JBoss Community Logo

The <imagedata> element defines the image path, and sets the way the image is displayed in the published output. Use the following recommendations when inserting <figure> elements:
  • To scale large diagrams or screenshots to fit within page boundaries, set width="450" to scale the screen shot within the boundaries of an A4 page.
  • If you need to include a screen shot of a large user interface, consider including only the area that relates to what you are discussing. You can get a much better result if you capture a small section of a user interface, because the user can easily see the detail of the area referred to in the procedure or concept.
If you are using a Linux-based operating system, chances are you will be using a graphics package such as the GNU Image Manipulation Program (GIMP). You can use the GIMP to capture screenshots, and save them in a format that will provide the best output for both HTML and PDF.
Procedure 6.3. Correctly capturing screenshots using the GIMP
The following procedure describes how to correctly capture and save a screen shot using the Create Screenshot function in The GIMP. The procedure assumes that you have The GIMP installed, and the program is open.
  1. Prepare the Content to Capture

    Ensure you have the correct application open, and that the part of the application you need to capture is activated. The GIMP will capture the screen immediately, unless a delay is set.
  2. Select the Create Screenshot Option

    Click File Create Screenshot.
  3. Confirm Capture Options

    In the Screenshot dialog box, select the capture option you require according to the following guidelines:
    • Do not include window decorations in any of your screenshots.
    • Consider capturing only the section of the screen you need to refer to in the documentation. It will be clearer for the reader.
  4. Capture the Screen

    Click the Snap button to begin capturing the screen area. Select the program, or area of the screen you want to capture.
  5. Scale the Image

    Click ImageScale Image.
    If you need to scale a large screen shot or diagram, use the following settings:
    • In the Image Size group, set the Width to (no greater than) 450 pixels.
    • In the Quality group, set Interpolation to Sinc (Lancosz3).
    Click Scale to set the image scale.
  6. Save the Image

    Click FileSave As.
    Name the image according to the image file naming conventions. If in doubt, look at the naming convention in the Images folder of your user guide directory.
    In the Save Image dialog, select PNG image (*.png) from the Image Type drop down menu.
    Click Save.

6.9. Admonitions (Warning, Important, Note)

To alert readers to information that might otherwise be overlooked, DocBook v4.5 supports a number of admonitions you can use to highlight concepts for readers. The supported options are limited to:
  • Warning
  • Important
  • Note
The options are listed in order of priority, and alert the reader to the following conditions:
Warning
Warnings contain information that must not be ignored. Ignoring recommendations in Warnings may result in data loss, or other catastrophic issues.
Important
Includes information that might be easily overlooked and may cause unnecessary frustration when using the software. For example, configuration changes that only apply to the current session, or services that need restarting before an update will apply.
Note
Contains information that may be useful to the reader. Ignoring a note should have no negative consequences for the reader, but may result in the reader missing out on usability tips, or a shortcut that may help them complete a task.
The way these elements are formatted depends on what publishing system you use to produce a user guide. The Publican JBoss brand formats this information in a conspicuous way; lots of color, bold graphics, and a slightly different typeface to the normal content. The Publican jboss-community brand and the defalut jDocBook style formats the information slightly less aggressively by using softer colors, but each admonition is still quite conspicuous to the reader.
When writing information for any of these elements, you can maximize the effectiveness of the information by keeping the structure of the information consistent. Consider the following examples to see how effective this is.
Use the following XML structure when creating a Warning or Important admonition. See the sample Warning and Important in this example as a reference.
<warning>
  <title>Warning Summary</title>
  <para>Imperetive instruction to the user.  Reason why the user should obey the instruction.</para>
</warning>
<important>
  <title>Important Summary</title>
  <para>Information that will save the reader unnecessary frustration.</para>
</important>
Example 6.9. Warning and Important

Open Office Package Dependencies

Do not uninstall Open Office from Gnome Desktop systems. Open Office package dependencies may result in critical system files, including X Windows System files, being unintentionally removed.

Install MSS for JBoss 0.7 or Later

Only MSS for JBoss v0.7 bundles the Diameter JBoss Service (the Diameter SAR, or Servlet Archive), which is required to run the Diameter Event-Charging Service.

6.10. Special Characters (Symbols)

When writing XML documentation, certain symbols can prevent XML validating correctly. When parsing an XML document, the validator interprets symbols as XML processing instructions. As a rule, a good WYSIWYG XML Editor (for example, Syntext Serna) will correctly substitute special characters with their literal value entities automatically.
If you are editing XML using a basic text editing program, this automation may not exist. You must manually insert symbol entities when you need to insert a keyboard symbol (commonly) or non-keyboard symbols (copyright, etc).
The most common symbol entities that will break XML publishing are listed for reference.
&lt;
Inserts a left angle bracket "<" symbol. The left angle bracket is used to open all XML elements, therefore the parser will assume that the text directly proceeding the symbol is a DocBook XML element. This will cause the publish to fail. Use this symbol entity when writing menu paths, referring to XML elements within <para> or other character data (CDATA) elements, or within code samples.
&gt;
Inserts a right angle bracket ">" symbol. Use this symbol to close off XML elements when describing XML elements in CDATA elements such as <para> elements and within code samples.
&amp;
Inserts an ampersand "&" symbol. Ampersand is used to start an entity reference, so this will break the XML publish if you directly insert it into your document.

6.11. Menus, Buttons, and Labels

In DocBook 4.5, there are a number of elements that can be used to mark-up items that the user has access to in a program Graphical User Interface (GUI). A user appreciates consistency in the way user commands are represented because it allows them to quickly identify the sequence of menu transitions required to execute a product feature.
Use the following elements as appropriate when describing a GUI:
  • <guibutton>
  • <guiicon>
  • <guilabel>
  • <menuchoice>
  • <guimenu>
  • <guimenuitem>
  • <guisubmenu>
<guimenu>, <guisubmenu>, and <guimenuitem> elements can be listed inside a <menuchoice> to provide a simplified notation for traversing the menu hierarchy, as demonstrated in Example 6.10, “GUI elements example”. Alternatively each can be used individually to describe menus and menu items.
Choose <menuchoice><guimenu>System</guimenu><guisubmenu>Preferences</guisubmenu><guimenuitem>Mouse</guimenuitem> </menuchoice> from the main menu bar to launch <application>Mouse Preferences</application>. In the <guilabel>Buttons</guilabel> tab, click the <guilabel>Left-handed mouse</guilabel> check box and click <guibutton>Close</guibutton> to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).
Choose SystemPreferencesMouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, click the Left-handed mouse check box and click Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).
Example 6.10. GUI elements example

6.12. Applications and Utilities

This section lists helpful elements for use when describing and documenting the use of applications and utilities. Also refer to Section 6.11, “Menus, Buttons, and Labels” for details on documenting an application or utility with a Graphical User Interface (GUI).
File and Directory Names
Use for files and directories. For packages and modules, use <package>.
Packages and Modules
Use the <package> element for packages and modules, such as those which need to be installed for a particular application.
To install <application>Publican</application>, download the <package>publican</package> package.
To install Publican, download the publican package.
Example 6.11. <package> example

<package> requirements

The <package> element was introduced in DocBook version 4.4, so documents using older versions will need to update their DOCTYPE declaration to use it. A minimum version of DocBook version 4.5 is recommended. The DOCTYPE declaration can be updated with the following code at the top of the document:
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
...
]>
Parameter Names and Parameter Values
Use the <parameter> element when referring to the name of a parameter for a command. Use <literal> for the actual value of a parameter.
Use the <parameter>--help</parameter> parameter for assistance.
Use the --help parameter for assistance.
Example 6.12. <parameter> example

The <parameter> element can also be used for parameters in a method in a programming language. If both uses appear in the same document it may be necessary to differentiate them using the class attribute, which can be set to command, function, or option.
Program Names
Use the <application> element for software applications, for example, Mozilla Firefox.
Protocols
Use the <systemitem> element for protocols in general, such as SSH, TCP, telnet, CGI, and protocols in general.
User-replaceable Text
Use the <replaceable> element for marking descriptive text in a command or computer output which the user is expected to replace with text specific to their particular application. It describes what the user is expected to use, but not the actual text they should use.
Edit <filename><replaceable>filename</replaceable>.xml</filename>
Edit filename.xml
Example 6.13. <replaceable> example

Terminal Commands
Use the <command> element for entered commands, such as ls, top, find, mount, and bash. When referring to applications launched this way, also use <command>, for example, firefox. When describing lengthy commands it may be suitable to mark up additional parameters within the <command> element with the <parameter> element.
Terminal Command Output
Use the <computeroutput> element in-line with text to represent text that is shown on a computer screen, such as output from a command. For displaying output text in a block, use the <screen> element.
The application status will display <computeroutput>cleaning files</computeroutput>.
The application status will display cleaning files.
Example 6.14. <computeroutput> example

Text Displayed On-screen
Use the <screen> element to represent text that is shown on a screen, usually an output from a command. The text is shown in a block. For referring to display text in-line, use the <computeroutput> element.
<screen>
books        Desktop   documentation  drafts  mss    photos   stuff  svn
books_tests  Desktop1  downloads      images  notes  scripts  svgs
</screen>
books        Desktop   documentation  drafts  mss    photos   stuff  svn
books_tests  Desktop1  downloads      images  notes  scripts  svgs
Example 6.15. <screen> example

User Account Names
Use the <systemitem> element for user account names.

6.13. Code Examples

Code samples feature prominently throughout JBoss documentation. The correct XML element to use for XML and Java code block examples is the <programlisting> element.
<programlisting> has been used extensively throughout this user guide to highlight the XML structure you need to use in specific situations. There are two ways you will need to use this element within your user documentation.
An advantage of using <programlisting> is that you can specify the way Maven and Publican displays the information to the user. This is achieved using the language and role attribute. When language is defined, Publican will format the code example with highlighting that will assist the reader in understanding the code structure. The role attribute does the same when using Maven.
XML Samples
For XML samples, you must specify "XML" (in uppercase) as the language and role values.
The code for an XML program listing will look similar to the following example.
<programlisting language="XML" role="XML">
  <important>
    <title>Important Summary</title>
    <para>Information that will save the reader unnecessary
      frustration.</para>
  </important>
</programlisting>
When output, the XML elements are highlighted to assist the reader.
<important>
    <title>Important Summary</title>
    <para>Information that will save the reader unnecessary
      frustration.</para>
</important>
If XML is not specified, the output looks far less attractive.
<important>
    <title>Important Summary</title>
    <para>Information that will save the reader unnecessary
      frustration.</para>
</important>
Java Samples
For Java code samples, the same rules apply. Instead of "XML", "JAVA" is specified as the role attribute value and "Java" for the language attribute.
package org.jboss.book.jca.ex1;

import javax.naming.InitialContext;

public class ExClient
{
   public static void main(String args[]) 
       throws Exception
   {
      InitialContext iniCtx = new InitialContext();
      Object         ref    = iniCtx.lookup("EchoBean");
      EchoHome       home   = (EchoHome) ref;
      Echo           echo   = home.create();

      System.out.println("Created Echo");

      System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
   }
   
}
Long code samples
For lengthy code samples of more then a couple of lines, it is preferable to use an <xi:include> to an external file which contains only the code sample. These code sample files should end in the relevant extension and should be placed in an extras/ directory located in the source language directory.
  • Java files use the java extension.
  • XML files use the xml_sample extension. When referencing an external XML file with the xml extension, Publican formats the file as though it were DocBook text. Using xml_sample avoids this.
<example id="exam-JBoss_Documentation_Guide-Code_Examples-programlisting_example">
	<title>&lt;programlisting&gt; example</title>
<programlisting language="XML" role="XML">
<xi:include parse="text" href="extras/exam-JBoss_Documentation_Guide-Code_Examples-programlisting_example.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" />
</programlisting>
	<para>
		<xref linkend="exam-JBoss_Documentation_Guide-Code_Examples-programlisting_example"/> describes itself.
	</para>
</example>

Example 6.16. <programlisting> example

In-Line Code Samples
Where <programlisting> presents the code in a separate block, there are multiple elements to use when using code samples in-line with other text.
Attribute, Property, and Parameter Values
Use the <literal> element for values of attributes, properties and parameters. In the Directory Server documentation, for example, the nsslapd-accesslog-level attribute can have values of 0, 4, 256, and beyond. The <literal> elements should be used for these values.
Alternatively, the <option> element can be used for those attributes, properties and parameters with a limited set of possible values, for example, a boolean value of true or false, or an enumerated type.
Use the <parameter> element when referring to the name of the parameter, attribute, or property itself. When writing the parameter and its value together, or the parameter and its method or class together, use the <code> element.
Classes (Java or similar)
Use the <classname> element in-line with text to mark classes or similar objects in programming languages. Typically it refers to a class in an object-oriented language, such as Java.
Use the <classname>java.lang.Object</classname> class in an example.
Use the java.lang.Object class in an example.
Example 6.17. <classname> example

When writing the class together with a method or parameter, use the <code> element.
Computer Programming Code In-line With Text
Use the <code> element in-line with text to mark computer programming code.

<code> Compatible with DocBook 4.3 Onwards

The <code> element was introduced in DocBook version 4.3. For <code> to be supported, documents must reference the correct DocBook version in the DOCTYPE declaration. A minimum version of DocBook version 4.5 is recommended. The DOCTYPE declaration can be updated with the following code at the top of the document:
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
...
]>
The <code> element does not offer syntax highlighting. To provide sample code in a block, use the <programlisting> element instead.
For simplicity, do not mark individual elements within a <code> element. If you feel identifying elements of the code is necessary for readability, the following elements are available:
  • <classname>
  • <literal>
  • <methodname>
  • <option>
  • <parameter>
  • <sgmltag>
  • <type>
  • <varname>
  • Any other code-related elements not covered in this section.
Java
Use <code>a.equals(b)</code> to determine if object <parameter>a</parameter> is equal to object <parameter>b</parameter>.
Use a.equals(b) to determine if object a is equal to object b.
XML
Use <code>&lt;programlisting language="XML" role="XML"&gt;</code> to mark <acronym>XML</acronym> code.
Use <programlisting language="XML" role="XML"> to mark XML code.
Example 6.18. <code> example

Data Types
Use the <type> element for data types, such as int, char, or boolean. Although the markup is not styled by Publican, it clarifies the term's use for translation. For actual values for data types, use the <literal> element.
Used for data types, such as <type>int</type>, <type>char</type>, or <type>boolean</type>.
Used for data types, such as int, char, or boolean.
Example 6.19. <type> example

Method or Constructor Parameter Names
Use the <parameter> element when referring to the name of a parameter for a method or constructor in a programming language. Use <literal> for the actual value of a parameter.
When writing the parameter and its value together, or the parameter and its method or class together, use the <code> element.
The <parameter> element can also be used for parameters in a command. If both uses appear in the same document it may be necessary to differentiate them using the class attribute, which can be set to command, function, or option.
Programming Methods
Use the <methodname> element in-line with text to mark the name of a method in a programming language.
If including the class to clarify the method name, include the whole class in the <methodname> element rather than marking the class part with <classname>.
Use the <methodname>java.lang.Object.toString()</methodname> method to get a <type>string</type> representation.
Use the java.lang.Object.toString() method to get a string representation.
Example 6.20. <methodname> example

When writing the method together with its class or parameters, use the <code> element.
Variable and Attributes Names (all languages)
Use the <varname> element when referring to the name of a variable in an object-oriented language such as Java, or the name of an attribute of an XML element. Use <literal> (or <option> if appropriate) for the actual value of a variable or attribute.
Use the <varname>class</varname> attribute, which can be set to <option>command</option>, <option>function<option>, or <option>option</option>.
Use the class attribute, which can be set to command, function, or option.
Example 6.21. <varname> example

XML Elements
Use the <sgmltag> element in-line with text to mark XML elements.
When writing the element together with attributes, use the <code> element.
Use the <sgmltag>&lt;example&gt;</sgmltag> element for examples.
Use the <example> element for examples.
Use the <code>id="[section_name]"</code> attribute of the <sgmltag><section></sgmltag> element to set the ID for the section.
Use the id="[section_name]" attribute of the <section> element to set the ID for the section.
Example 6.22. <sgmltag> examples

Cross-references within the book
Use the <xref> element to cross-reference a chapter, section, or other content block. The linkend attribute points to the target block's id attribute.
For more details refer to <xref linkend="exam-JBoss_Documentation_Guide-Code_Examples-xref_example" />.
For more details refer to Example 6.23, “<xref> example”.
Example 6.23. <xref> example

Links to external URLs
Use the <ulink> element to link to an external URL. The url attribute points to the target link, and must be a complete URL.
For further information, refer to <ulink url="http://www.jboss.org" />.
For further information, refer to http://www.jboss.org.
By creating the link without providing a link alias, the reader can see the full URL. This is especially important to consider if you are producing both print-ready and online documentation.
Example 6.24. <ulink> example

When you need to include a <ulink> that resolves to a lengthy URL, you may wish to supply a link alias so the link is formatted cleanly. The reader can see the full URL, however the information wraps to the next line which can be distracting to the reader. If you
Long URL without an alias:
For further information, refer to <ulink url="http://docs.fedoraproject.org/installation-quick-start-guide/f12/en-US/pdf/Fedora_12_Installation_Quick_Start_Guide.pdf"/>.
PDF documentation handles link aliases by creating a footnote at the bottom of each page. This formatting can distract readers because they have to follow the footnote number and locate the link at the bottom of the page.
Long URL with an alias:
For further information about installing Fedora 12, refer to the <ulink url="http://docs.fedoraproject.org/installation-quick-start-guide/f12/en-US/pdf/Fedora_12_Installation_Quick_Start_Guide.pdf">Installation Quick Start Guide</ulink>.
By constructing the sentence differently, you can include the link for those readers that access the online version of the documentation. Readers who prefer PDF documentation are also supported, because they know what to search for when they are next online.
Example 6.25. <ulink> link alias examples

References to external content
Use the <citetitle> element when referring to another book, article, website, or other form of external content.
Unlike the <xref> element, <citetitle> does not link to the referenced section, so if the name of the referenced book is changed the <citetitle> element will need to be updated manually. External links such as those using the <ulink> element should not be used to reference another book, as an external link may become outdated at a later time.
Refer to <citetitle>DocBook: The Definitive Guide</citetitle> for further details.
Refer to DocBook: The Definitive Guide for further details.
Example 6.26. <citetitle> example

Chapter 7. Language Guidelines

To maintain language consistency across all JBoss Middleware user documentation, it is important for each content author to write in a similar tone. Maintaining consistent tone throughout the user guides will make your user guide a part of a unified suite of documents, rather than a separated group of user guides. From a user perspective, your documentation will be easy to understand because you have taken the time to write in a consistent, professional tone.
If your JBoss Middleware project is being productized by Red Hat, following the language guidelines will reap benefits beyond your community documentation. Because the language guidelines presented in this guide are taken directly from the Engineering Content Services Style Guide, the productization effort will be reduced. The team of Content Authors assigned to your project can focus on improving the product documentation, rather than spending time on correcting grammar issues in the upstream documentation source.
The reader will subconsciously notice the consistency, will be able to easily process the information contained within the user guide, and will appreciate the effort you have put in to keeping the writing style professional and consistent (even though they may not tell you directly).

Important

JBoss documentation uses the English (US), or en-US dictionary. Ensure that you follow the requirements of this dictionary when writing content for your team's documentation.

7.1. Dictionary

JBoss user documentation uses the American English dictionary. If your XML editing program has a spell-check function, ensure it is set to check for American English language requirements.

7.2. Active Voice

Use the active voice ("Start Linuxconf by typing...") rather than passive ("Linuxconf can be started by typing...") whenever possible. Active voice makes for more lively, interesting reading.
If you are unsure whether you are writing in the active voice, read your text aloud. If you are writing a procedure, does it sound like you are explaining it like you would if you were sitting next to someone? If it does, you are most likely writing in active voice.

7.3. Tense

Avoid future tense (or using the term "will") whenever possible. For example, future tense ("The screen will display...") does not read as well as the present tense ("The screen displays"). Remember, the users you are writing for most often refer to the documentation while they are using the system, not after or in advance of using the system.

7.4. Gender References

Do not use gender-specific pronouns in documentation. It is far less awkward to read a sentence that uses "they" and "their" rather than "he/she" and "his/hers".
It is fine to use "you" when giving instructions and "the user," "new users," etc. in more general explanations. Never use "one" in place of "you" when writing technical documentation. Using "one" is far too formal.

7.5. Sentence Structure

A sentence is one, complete thought. A sentence expresses something about a subject (a person, place, or thing) and a verb (what the subject is or does). There are two common problems that occur in sentence construction: Sentence fragments and run-on sentences.
Sentence Fragments
A sentence fragment is a sentence which cannot stand by itself; that is, it's out of context with the surrounding sentences.
Full Sentence
"We will release no upgrade before its time."
Fragment Sentence
"We will release no upgrade. At least, before its time."
Notice that the second sentence can not stand on its own if it is isolated from the first sentence.
Example 7.1. Full, and Fragment Sentences

Read each sentence you write aloud, as if each sentence were the "only" sentence on a piece of paper. If you hear a sentence that would not make sense all by itself, chances are you have got a sentence fragment. Change the fragment sentence to make it a complete thought.
Run-on Sentence
Two or more complete ideas that are joined without punctuation create a run-on sentence (also called a fused sentence). The sentence does not have to be long to be a run-on (although the longer your sentence, the more difficult it is to read).
Simple Run-on
The CDs both of which belonged to the developers were in the test lab.
Correct
The CDs, both of which belonged to the developers, were in the test lab.
Complex Run-on
The CDs, both of which belonged to the developers, were in the test lab, and because they were the only available CDs for the new release, the developers were anxious about keeping them clean.
Correct
The CDs, both of which belonged to the developers, were in the test lab. Because they were the only available CDs for the new release, the developers were anxious about keeping them clean
In the complex run-on, the previous run-on sentence was technically correct because of the punctuation; however, it could have been broken to help readability.
Example 7.2. Run-on Sentences

7.6. Conversational Language

It is often tempting to write like you are talking to someone face to face. It is an easy way of writing, and allows you to write using a stream of consciousness method.
The problem with this type of writing style, is that it is very hard for the reader to quickly grasp a concept. They must read through the content and try to extract the information that is relevant to them from the information you have provided them. The writing style often leads to verbosity (or wordiness) and this can quickly frustrate readers.
The following examples will show you how pruning your writing can cut down the word count, and allow readers to easily understand the information they are reading.
This (real-life) example shows how how you can increase the readability of the information by removing unnecessary words and restructuring content.
Original Wording
As the SIP Servlets Server employs JBoss Application Server as its servlet container and takes advantage of its capabilities, including clustering and failover, familiarity with the basics of JBoss Clustering is helpful. Refer to this chapter in the Clustering Guide for background or if you wish to dig further: JBoss Application Server Clustering Guide.
Suggested Wording
To further understand the complete clustering and failover capabilities of the JBoss Application Server, refer to the JBoss Application Server Clustering Guide.
Result
After the edit, notice how concise the paragraph is. Also notice how the colloquialism in the reference has been removed. Depending on the reader's language skills, the usage of "dig further" might not be understood. When this is translated to other languages, the meaning of this sentence might also be lost in translation.
Example 7.3. Reordering and Restructuring for Readability

This (real-life) example demonstrates how writing like you are speaking can result in unordered concepts, and reduces the effectiveness of the information you are writing about.
Original Wording
An important note here with regard to that second scenario that according to the SIP Servlets 1.1 specification, Sections 15.1.2 The Role of Applications and 15.1.4 Application Independence, the Call Blocking application cannot just do nothing with the request and expect the container to route the request in its place (either to a next application in chain if another one is present or to the outside world if none is present). The Application has to do something with request (either proxy it or act as a UAS)
Suggested Wording
For the second scenario, the Call Blocking application must be responsible for routing the request to the next chained application (internally) or to the outside world (externally). The application must either proxy, or act as a User Agent Server (UAS), for the request. This requirement is stated in greater detail within the SIP Servlets 1.1 specification's "The Role of Applications" and "Application Independence" sections.
Result
In the original wording, the main point (that the application must handle the routing, and how it must do this) was right at the end of the paragraph. In the suggested wording, the application requirement has been moved up to the front of the paragraph. This allows the reader to quickly decide whether the information relates to them. The references, which were interrupting the sentence flow, are now at the end of the paragraph.
Example 7.4. Writing Like You Are Speaking

pom.xml Multi-Profile

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.jboss.project</groupId>
  <artifactId>${docname}-${translation}</artifactId>
  <version>1.0</version>
  <packaging>jdocbook</packaging>
  <name>${bookname}-(${translation})</name>

  <properties>
    <translation>en-US</translation>
    <docname>NAME_OF_ROOT_XML_FILE</docname>
    <bookname>NAME OF BOOK IN THE TITLE TAG</bookname>
  </properties> 

  <repositories>
    <repository>
      <id>repository.jboss.org</id>
      <name>JBoss Repository</name>
      <layout>default</layout>
      <url>http://repository.jboss.org/maven2/</url>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </repository>
  </repositories>
  <pluginRepositories>
    <pluginRepository>
      <id>repository.jboss.org</id>
      <name>JBoss Repository</name>
      <layout>default</layout>
      <url>http://repository.jboss.org/maven2/</url>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </pluginRepository>
  </pluginRepositories>

  <profiles>

    <!-- mvn compile -->
    <profile>
      <id>all</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      <build>
      <plugins>
        <plugin>
          <groupId>org.jboss.maven.plugins</groupId>
          <artifactId>maven-jdocbook-plugin</artifactId>
          <version>2.2.0</version>
          <extensions>true</extensions>
          <configuration>
            <formats>
              <format>
                <formatName>pdf</formatName>
                <stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
                <finalName>${docname}.pdf</finalName>
              </format>
              <format>
                <formatName>html</formatName>
                <stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
                <finalName>index.html</finalName>
              </format>
              <format>
                <formatName>html_single</formatName>
                <stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource>
                <finalName>index.html</finalName>
              </format>
            </formats>
          </configuration>
        </plugin>
      </plugins>
      </build>
    </profile>

    <!-- mvn compile -Phtml -->
    <profile>
      <id>html</id>
      <activation>
        <activeByDefault>false</activeByDefault>
      </activation>
      <build>
      <plugins>
        <plugin>
          <groupId>org.jboss.maven.plugins</groupId>
          <artifactId>maven-jdocbook-plugin</artifactId>
          <version>2.2.0</version>
          <extensions>true</extensions>
          <configuration>
            <formats>
              <format>
                <formatName>html</formatName>
                <stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
                <finalName>index.html</finalName>
              </format>
            </formats>
          </configuration>
        </plugin>
      </plugins>
      </build>
    </profile>

    <!-- mvn compile -Phtml-single -->
    <profile>
      <id>html-single</id>
      <activation>
        <activeByDefault>false</activeByDefault>
      </activation>
      <build>
      <plugins>
        <plugin>
          <groupId>org.jboss.maven.plugins</groupId>
          <artifactId>maven-jdocbook-plugin</artifactId>
          <version>2.2.0</version>
          <extensions>true</extensions>
          <configuration>
            <formats>
              <format>
                <formatName>html_single</formatName>
                <stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource>
                <finalName>index.html</finalName>
              </format>
            </formats>
          </configuration>
        </plugin>
      </plugins>
      </build>
    </profile>

    <!-- mvn compile -Ppdf -->
    <profile>
      <id>pdf</id>
      <activation>
        <activeByDefault>false</activeByDefault>
      </activation>
      <build>
      <plugins>
        <plugin>
          <groupId>org.jboss.maven.plugins</groupId>
          <artifactId>maven-jdocbook-plugin</artifactId>
          <version>2.2.0</version>
          <extensions>true</extensions>
          <configuration>
            <formats>
              <format>
                <formatName>pdf</formatName>
                <stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
                <finalName>${docname}.pdf</finalName>
              </format>
            </formats>
          </configuration>
        </plugin>
      </plugins>
      </build>
    </profile>
  </profiles>

  <build>
    <plugins>
      <plugin>
        <groupId>org.jboss.maven.plugins</groupId>
        <artifactId>maven-jdocbook-plugin</artifactId>
        <version>2.2.0</version>
        <extensions>true</extensions>
        <dependencies>
          <dependency>
            <groupId>org.jboss</groupId>
            <artifactId>jbossorg-docbook-xslt</artifactId>
            <version>1.1.0</version>
          </dependency>
          <dependency>
            <groupId>org.jboss</groupId>
            <artifactId>jbossorg-jdocbook-style</artifactId>
            <version>1.1.0</version>
            <type>jdocbook-style</type>
          </dependency>
        </dependencies>
        <configuration>
          <sourceDocumentName>${docname}.xml</sourceDocumentName>
          <sourceDirectory>.</sourceDirectory>
          <imageResource>
            <directory>${translation}</directory>
            <includes>
              <include>images/*</include>
            </includes>
          </imageResource>
          <options>
            <xincludeSupported>true</xincludeSupported>
            <xmlTransformerType>saxon</xmlTransformerType>
            <!-- needed for uri-resolvers; can be ommitted if using 'current' uri scheme -->
            <!-- could also locate the docbook dependency and inspect its version -->
            <docbookVersion>1.72.0</docbookVersion>
            <transformerParameters>
              <property>
                <name>javax.xml.parsers.DocumentBuilderFactory</name>
                <value>org.apache.xerces.jaxp.DocumentBuilderFactoryImpl</value>
              </property>
              <property>
                <name>javax.xml.parsers.SAXParserFactory</name>
                <value>org.apache.xerces.jaxp.SAXParserFactoryImpl</value>
              </property>
            </transformerParameters>
          </options>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>


Sample Project

This user guide is hosted on <insert hosting location>. The SVN directory that contains the XML source for this guide, also contains a sample project created using Publican.
The sample project is provided to assist you in configuring your documentation repository to work with Maven and Publican. If you project decides to use the sample project, you will not technically need to install Publican in order to create your book repository.
Publican can create a docs repository pre-configured for your book. All you need to do is add the Maven components to your book repository (from the included sample project), and you are ready to produce cross-compatible documentation. You can learn more about cross-compatibility in Chapter 5, JDocBook and Publican Interoperability
The Sample Project can be used as a starting point for new projects, and contains the following components:
  • Publican-compatible folder structure
  • base pom.xml file configured for jDocBook
  • basic book files, including <chapter> and <section> files
  • files named according to the recommendations in this user guide
  • fallback_content directory containing XML xi:fallbacks for Maven jDocBook
  • customization instructions to make the project your own.

B.1. Default Folder Structure

At the top level of the sample project, the en-US folder contains the XML files used in a Publican compatible book.
Inside the en-US folder, there are two additional folders. The images folder stores the screen shots and diagrams that are used throughout the guide. The fallback_content folder stores the front matter information required by jDocBook.

B.2. Book Components

Table B.1, “Book Components” describes the mandatory files that must be present in a Publican book, including a description of the file contents, and where the XML file is commonly embedded into the finished user guide.
XML Book Component Description Order of Component in the Book
[Book_Name].xml Contains the structure of the user guide, represented by xi:include references to each chapter-[Chapter_Name].xml component, and other mandatory components in this table. Root Level (or Parent) component of any user guide.
[Book_Name].ent Contains all entities used within the user guide. The contents of the file is inserted as a parameter entity in the DOCTYPE header of each chapter and section of the book. Inserted by reference into all XML DOCTYPE declarations that contain a parameter entity declaration (refer to Section 5.5.2, “Insert .ent Parameter Entities”).
Book_Info.xml Contains information about the book title, book version number, abstract and copyright information. 1st Child. This is the opening information a reader will see in the user guide.
Author_Group.xml Contains contact information about the authors that contributed to the content of the book. 2nd Child. This component is included in the Book_Info.xml component.
Preface.xml Contains pre-defined content explaining the typographical standards used in the guide, and other information that will assist the reader with using the guide. 3rd Child. This component is included after the Book_Info.xml content.
chapter-[Chapter_Name].xml Contains XML markup and content included at a Chapter level in the document. The XML file is named only for human-readability. 4th. This is the top level element for each chapter in the user guide. The order of these files in the [Book_Name].xml file determines the structure of the guide.
section-[Section_Name].xml Contains XML markup and content included at a Section level in the document. The XML file is named only for human-readability. 5th. This component is included in chapter-[Chapter_Name].xml files by xi:include reference.
Revision History.xml Contains a record of the revisions made to the document over time. Top-level information about changes in the guide are provided to the reader. 6th.
Table B.1. Book Components

B.3. Customizing Book Structure

Using the sample project as the basis for your docs project requires a few changes to files in the directory. You need to remove some of the placeholder filenames, and tailor the sample repository to meet your needs.
Customizing Files
publican.cfg
You must change the brand: attribute to the brand package you wish to use for your project. Some common brand type have been included in the file. Uncomment the brand you wish to use, and comment out the rest. You must install the brand package you specify for the brand: attribute
All XML files in the en-US directory
Ensure you have changed (or added) the parameter entity in each XML file DOCTYPE declaration. For more information about parameter entities, refer to Section 5.5, “Build with jDocBook”.
Author_Group.xml
Change the placeholder information in this file to be the primary author of the guide. If there are multiple contributors, copy the <author> block and duplicate it.
JBoss_Sample_Project.xml
Change the name of this file to the new name of your book. Use underscores to separate words; spaces are not recommended in your book name.
Book_Info.xml
Change the id attribute according to the requirements in Section 6.3, “Chapters and Sections”
Change the <title> to the name of your book. Spaces are allowed.
Change the <subtitle> to content relevant to your book.
Change the <productname> to the correct overarching product name for your project.
Change the <abstract> to content relevant to your book.
Change the <imagedata> fileref to represent the location of your project's logo. Making this change is not mandatory, however a placeholder image will be inserted if you choose not to. The en-US/images folder should be used to contain a copy of your logo.
JBoss_Sample_Project.ent
Change the name of this file to the identical name you gave to the JBoss_Sample_Project.xml file. Use underscores to separate words; spaces are not recommended in your book name
Change the value for the PRODUCT system entity to the value you entered in the <productname> element in the Book_Info.xml file.
Change the value for the BOOKID system entity to the name that users will log bugs against for documentation enhancements.
Change the values for the HOLDER system entity to the trademark owner of the book content.
Preface.xml
Ensure you xi:include the relevant front matter sections in this file, following the recommendations in Section 5.5.1, “xi:include Fallbacks”
Revision_History.xml
Remove the placeholder <date> and <author> information, and update with information relevant to the current revision of the document.
All chapter- and section- files
Change the id attributes according to the requirements in Section 6.3, “Chapters and Sections”
When you rename the section- files referenced by your chapter- files to something more relevant, ensure you update the xi:include entries for all affected xi:includes.

Revision History

Revision History
Revision 0.2Fri Dec 4 2009Jared Morgan
Complete draft for comment. All sections completed.
Revision 0.1Thu Nov 19 2009Jared Morgan
Draft release for comment. Many sections still need to be completed.