JBoss.orgCommunity Documentation

JBoss Documentation Guide

The canonical reference for JBoss developers and writers

PressGang Logo


Preface
1. License
2. Document Conventions
2.1. Typographic Conventions
2.2. Pull-quote Conventions
2.3. Notes and Warnings
3. Your feedback is vital
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
3.4. Project Documentation 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. DTD or XSD Validation
5.5.2. Change Author_Group.xml Structure
5.5.3. xi:include Fallbacks
5.5.4. Insert .ent Parameter Entities
5.5.5. Configure pom.xml
5.5.6. Publish with jDocBook
5.5.7. Begin Authoring
5.5.8. Troubleshooting
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.9.1. Default Titles
6.9.2. Custom Titles
6.10. Special Characters (Symbols)
6.11. Applications and Utilities
6.12. Menus, Buttons, and Labels
6.13. Code Examples
6.14. Links and References
7. Language Guidelines
7.1. Write Concisely
7.2. Dictionary
7.3. Active Voice
7.4. Tense
7.5. Gender References
7.6. Sentence Structure
A. pom.xml Multi-Profile
B. Sample Project
B.1. Default Directory Structure
B.2. Book Components
B.3. Customizing Book Structure
C. Revision History

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.

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.

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.

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:

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.

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.

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.

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.

Many thanks to the following Red Hat Engineering Content Services 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.6, “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.

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.

Choosing DocBook XML for your documentation over other formats has numerous benefits.

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

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.

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

You may need your community to contribute directly to documentation without the upskill time required to learn DocBook XML to the required level. Or you may need to seek heavy collaboration on a document your team is writing. In these cases, DocBook XML may not be the best choice for your project.

The JBoss Community Team offers an online Project Documentation Editor ( Confluence) that allows individual contributors and teams to quickly contribute community documentation using a web-based interface and clearly defined wiki markup.

The Authoring Guide describes which wiki markup to use, how to export it to DocBook XML, and how to transform the DocBook XML into a structure suitable for publishing.

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

Apache Maven (or Maven, as it is commonly referred to) is a project management tool used extensively throughout JBoss Middleware. As a JBoss developer, you are probably quite familiar with Maven from a software project management perspective.

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-plugin (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 the Maven dependency mechanism to import the components it requires to execute the publish. SAXON is used as the transformer factory for the XML source.

The following prerequisites 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.

jDocBook local installation not required

If you use the pom.xml file recommended in Appendix A, pom.xml Multi-Profile, Maven jDocBook is called as a dependency at publish time. A local copy of jDocBook is therefore not required.

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

Procedure 5.1. Install Maven

  1. Verify Java Developer 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. For more information regarding setting environment variables, refer to the Setting Environment Variables step in this procedure.

    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

    Visit http://maven.apache.org/download.html.

    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 including M2 at the beginning of your path, the Maven version you just installed will be the default version used. You may also want to set the path of your JAVA_HOME environment variable to the location of the Java OpenJDK on your system.

    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.

You have created your book, and verified that it publishes using Publican. The next step is to add the Maven elements to your book, and make minor changes to the default publican front matter.

Each docbook XML file starts with a DTD or XSD declaration that is used during validation to ensure the contents meet the structure requirements. If you are using an XML authoring tool, this information is usually added automatically.

The default Author_Group.xml file uses the <orgname> element to capture the name of the organization (for example, Red Hat, Ltd). The structure as output directly after you create a new book using Publican is described in Example 5.1, “Default Author_Group.xml Structure”.


Because the base PressGang styles were originally not designed to handle this element, the XSLT publishes the information in an incorrect order. Using Example 5.1, “Default Author_Group.xml Structure”, the output would publish to Dude (Somewhere) McPants.

To ensure your Authors are formatted correctly in Publican and Maven documentation builds, use the <shortaffil> element instead of the <orgname> element, as described in Example 5.2, “Cross-compatible Author_Group.xml Structure”. Using the cross-compatible structure results in the author name and company they work for publishing to Dude McPants (Somewhere). The <shortaffil> element must be declared first in the <affiliation> element, otherwise the structure is invalid according to Publican validation standards.


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.

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 Inserting xi:fallback links for instructions relating to including xi:fallbacks. Table 5.1, “jDocBook Content” describes the fallback files in more detail.


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>

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 declared in each XML file's DOCTYPE declaration.

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.

  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.

book_ent script alternative location

If you are having difficulty copying the book_ent script in this procedure, you may find it easier to check-out the file directly from the SVN repository and customize it according to this procedure.

svn co http://anonsvn.jboss.org/repos/pressgang/JBoss_Documentation_Guide/en-US/extras/book_ent

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.

    [home]$ mkdir /bin
    [home]$

    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.

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.

pom.xml alternative location

If you are having difficulty copying the pom.xml, you may find it easier to check-out the file directly from the SVN. Ensure you change the name from pom.xml_sample to pom.xml before using.

svn co http://anonsvn.jboss.org/repos/pressgang/JBoss_Documentation_Guide/en-US/extras/pom.xml_sample

5.5.8.1. I can build documents fine but from some point onward the text is all bold. What is wrong?

5.5.8.1.

I can build documents fine but from some point onward the text is all bold. What is wrong?

This can occur if Maven encounters empty tags, unresolved entities or images in SVG format. Resolve this by correcting the empty tags and/or unresolved entities. For images, convert them to PNG format.

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.

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.

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

looks like this in Spanish:

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.

<[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:

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:

This result is comprehensible, but inelegant, because Italian combines some of its prepositions with its definite articles. More elegant Italian would be:

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.

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. For example, 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.

A translation of this might be as follows:

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:

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:

With no text hidden behind an entity, a German translation of this might be:

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:

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:


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

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.3, “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">.

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:

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.


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.


<variablelist>

A <variablelist> can be used to define a list of terms, or in situations where a two column table is required. Variable lists can have optional titles.


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.

For each procedure, add a lead-in sentence which clarifies the procedure's purpose, for example: "Complete <xref linkend="proc-Example_procedure" /> to correctly install the television".

ID Attributes for Procedures

To allow cross-referencing within the book, the id attribute must be set for each procedure. The format for the procedure 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 format to use for <procedure> IDs throughout your documentation is as follows:

<procedure id="proc-[procedure_title]">

The minimum set of elements required for all procedure lists in JBoss Documentation are described in the following example:

Replace the [procedure_title] text with the actual title of the procedure. Exclude any XML special characters from your ID.


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

Example 6.5. <procedure> Extra Elements


<procedure id="proc-Procedure_Title">
    <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>

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.

ID Attributes for Tables

To allow cross-referencing within the book, the id attribute must be set for each table. The format for the table 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 format to use for <table> IDs throughout your documentation is as follows:

<table id="table-[table_title]">

Replace the [table_title] text with the actual title of the table. Exclude any XML special characters from your ID.

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


When published, the XML structure described in Example 6.6, “Three-column Table” publishes in the following way.


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.

Example 6.7. Cell spanning

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>

The result is displayed in Table 6.3, “Three-column table with spanning”.



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 diagrams and screenshots that 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.

ID Attributes for Figures

To allow cross-referencing within the book, the id attribute must be set for each figure. The format for the figure 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 format to use for <figure> IDs throughout your documentation is as follows:

<figure id="figure-[figure_title]">

Replace the [figure_title] text with the actual title of the figure. Exclude any XML special characters from your ID.

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.


The XML structure looks like this when published:

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 clearly 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 directory of your user guide directory.

    In the Save Image dialog, select PNG image (*.png) from the Image Type drop down menu.

    Click Save.

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 in order of priority are limited to:

The way these elements are formatted depends on what publishing toolchain style package you select to publish your user guide.

When writing information for any of these elements, you can maximize the effectiveness of the information by keeping the structure of the information consistent. Section 6.9.1, “Default Titles” describes the basic structure used in admonitions. Section 6.9.2, “Custom Titles” describes situations where a customized title would be more appropriate, and what effects on translation these titles inherently introduce.

By default, admonitions contain automatically generated text describing the admonition level. An example of each admonition is included below, including the structure to use and the resulting output.


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.

You can add a <title> element to admonitions so the reader has a terse summary of the admonition contents. The custome text overrides the default text provided in the basic titles.


Warning - Warning Summary

Imperative instruction to the user. Reason why the user should obey the instruction.

Important - Important Summary

Information that will save the reader unnecessary frustration

The following are examples of a warning and an important admonition using this structure.

Warning - Open Office Package Dependencies

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

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

This section lists helpful elements for use when describing and documenting the use of applications and utilities. Also refer to Section 6.12, “Menus, Buttons, and Labels” for details on documenting an application or utility with a Graphical User Interface (GUI).

File and Directory Names

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


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


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. Do not use <productname> to mark-up the name of a computer program or other product. <productname> can insert a trademark symbol into published output, which may not be correct for the progam in particular legal jurisdictions.

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.


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.


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.


User Account Names

Use the <systemitem> element for user account names.

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:

<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.18, “GUI elements example”. Alternatively each can be used individually to describe menus and menu items.


Code samples feature prominently throughout JBoss documentation. The correct XML element to use for XML and Java code block examples is the <programlisting> element.

There are a number of advantages with using <programlisting> to capture code samples. You can specify the way Maven and Publican formats the code sample when published by using the language attribute. When language is defined, Publican will format the code example with highlighting that will assist the reader in understanding the code structure.

Code highlighting in Publican is generated with the Syntax::Highlight::Engine::Kate Perl module. Refer to http://search.cpan.org/~szabgab/Syntax-Highlight-Engine-Kate-0.06/lib/Syntax/Highlight/Engine/Kate.pm#PLUGINS for the full list of languages that Syntax::Highlight::Engine::Kate supports, including their expected capitalization and punctuation.

Important

Maven jDocBook can only render XML and Java syntax highlighting. This is a limitation of the pressgang-highlighter package that the pressgang-jdocbook-style packages use.

Another advantage is that you do not need to XML escape special characters used as part of XML mark-up (refer to Section 6.10, “Special Characters (Symbols)” for a list of symbols that must be escaped in normal CDATA elements).

Within <programlisting>, all whitespace is rendered literally.

<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: XML Samples, and Java Samples.

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">
  <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 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 code samples, it is preferable to use an <xi:include> to an external file which contains only the code sample. This aids maintainability of the code samples, by making them easy to update separate from the documentation as a whole. These code sample files should end in the relevant extension and should be placed in an extras/ directory located in the source language directory.

Important

When using <xi:include> inside a <programlisting>, no linebreaks or spaces should be used between the tags, to avoid rendering extra whitespace.

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


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.


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.

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:


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.


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


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.


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.


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.


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.

Example 6.27. <ulink> example



For further information, refer to <ulink url="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.


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

Example 6.28. <ulink> link alias examples

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

For further information about installing Fedora 12, refer to the Installation Quick Start Guide.

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.


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.


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.

Writing concisely is key to effective technical communication. Readers do not want to wade through prose: they want facts, and they want it now. Remember: "Documentation exists to reduce the user's uncertainty". As we give information we need to measure whether the information reduces overall uncertainty or increases it.

Read the examples in this section to learn how writing terse, efficient prose improves your procedural and conceptual information.









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.


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 sentence fragment 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).



<?xml version="1.0" encoding="utf-8"?>
<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.myproject</groupId>
    <artifactId>myProject</artifactId>
    <packaging>jdocbook</packaging>
    <version>1.0</version>
    <name>My Project</name>

  <properties>
    <translation>en-US</translation>
    <docname>JBoss_Documentation_Guide</docname>
  </properties> 

  <repositories>
    <!-- Conventions are described in http://community.jboss.org/wiki/MavenGettingStarted-Developers -->
    <repository>
      <id>jboss-public-repository-group</id>
      <name>JBoss Public Repository Group</name>
      <url>http://repository.jboss.org/nexus/content/groups/public/</url>
      <releases>
        <enabled>true</enabled>
        <updatePolicy>never</updatePolicy>
      </releases>
      <snapshots>
        <enabled>true</enabled>
        <updatePolicy>daily</updatePolicy>
      </snapshots>
    </repository>
  </repositories>
  <pluginRepositories>
    <pluginRepository>
      <id>jboss-public-repository-group</id>
      <name>JBoss Public Repository Group</name>
      <url>http://repository.jboss.org/nexus/content/groups/public/</url>
      <releases>
        <enabled>true</enabled>
      </releases>
      <snapshots>
        <enabled>true</enabled>
      </snapshots>
    </pluginRepository>
  </pluginRepositories>

  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.jboss.maven.plugins</groupId>
          <artifactId>maven-jdocbook-plugin</artifactId>
          <version>2.3.5</version>
          <extensions>true</extensions>
          <dependencies>
            <dependency>
              <groupId>org.jboss.pressgang</groupId>
              <!--Non-namespaced version for DocBook 4.5 compatibility. For XSD namespaced version, use pressgang-xslt-ns-->
              <artifactId>pressgang-xslt</artifactId>
              <version>2.0.0</version>
            </dependency>
            <dependency>
              <groupId>org.jboss.pressgang</groupId>
              <artifactId>pressgang-jdocbook-style</artifactId>
              <type>jdocbook-style</type>
              <version>2.0.0</version>
            </dependency>
          </dependencies>
          <configuration>
            <sourceDirectory>${project.basedir}</sourceDirectory>
            <sourceDocumentName>${docname}.xml</sourceDocumentName>
            <masterTranslation>en-US</masterTranslation>
            <imageResource>
              <directory>${project.basedir}/en-US</directory>
              <includes>
                <include>images/*.png</include>
              </includes>
            </imageResource>
            <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>
            <options>
              <xmlTransformerType>saxon</xmlTransformerType>
              <xincludeSupported>true</xincludeSupported>
              <docbookVersion>1.72.0</docbookVersion>
              <useRelativeImageUris>true</useRelativeImageUris>
            </options>
          </configuration>
        </plugin>
      </plugins>
    </pluginManagement>
    <plugins>
      <plugin>
        <!-- Entry needed to enable jdocbook packaging -->
        <groupId>org.jboss.maven.plugins</groupId>
        <artifactId>maven-jdocbook-plugin</artifactId>
      </plugin>
    </plugins>
  </build>

</project>

This user guide is hosted in the JBoss.org anonsvn. 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 your 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 directory 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.

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.

Table B.1. Book Components

XML Book ComponentDescriptionOrder 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.4, “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 Child. 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 Child. 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 Child.

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 reference the location of your project's logo. The en-US/images directory should be used to contain a copy of your logo. A placeholder image will be inserted if you choose not to specify a project 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.3, “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 1.6-0Fri Feb 25 2010Jared Morgan
Incorporated project fixes, including the following JIRA.
PRESSGANG-3 - Added section explaining how to correctly structure the Author Group info for cross compatibility.
PRESSGANG-13 - Added link to the highlighter package Publican uses. Removed references to the role attribute, due to a fix implemented in the base style highlighter package. Noted that the base style highlighter package only renders XML and Java highlighting.
PRESSGANG-31 - Added sample edits to the Grammar Guidelines chapter. Thank you to Joshua Wulf for this contribution.
PRESSGANG-32 - Refreshed all Publican User Guide links in the guide.
Revision 1.4-1Fri Dec 10 2010Jared Morgan
Incorporated project fixes, including the following JIRA.
PRESSGANG-2 - Updated information about title element usage in Section 6.9, “Admonitions (Warning, Important, Note)”
PRESSGANG-4 - Clarified that xi:included code samples must not contain whitespace in Section 6.13, “Code Examples”.
PRESSGANG-12 - Specified the location of the publican common content files in Section 5.5.3, “xi:include Fallbacks”.
PRESSGANG-23 - Updated example for <orderedlist> for consistency in Section 6.4, “Lists”.
PRESSGANG-24 - Updated example for <varlist> for consistency in Section 6.4, “Lists”.
Revision 1.3-0Tue Aug 10 2010Jared Morgan
Updated repo links in Maven Interoperability section.
Section discussing XSD compatibility as per JDOCBOOKSTYLE-15
Revision 1.1-0Fri Feb 12 2010Jared Morgan
Incorporated minor editing comments from Misty Stanley-Jones
Revision 1.0-0Mon Feb 1 2010Jared Morgan
First Edition Released
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.