Skip to end of metadata
Go to start of metadata

Overview

DocBook is an open standard of XML markup that allows you to structure documentation into books or articles. Since it is XML-based, it can be checked into version control just like source code and tagged with releases of software. Additionally, there are maven plugins available that will build many different formats of documentation (i.e. PDF, single-page HTML, multi-page HTML, etc.) from a single set of DocBook XML and image files. While DocBook comes with a standard set of stylesheets for each format, the style for each format can be tweaked with specific stylesheets.

Kuali Rice is currently using the DocBook 5 format for documentation and the docbkx-maven plugin to generate the documentation as part of our maven build.

To setup your system to develop Rice DocBook Documentation, follow the instructions at DocBook Environment Setup.

Getting Started

  1. Download an XML editor such as oXygen, and an SVN tool. There is already an SVN tool within oXygen. 
  2. Within SVN, download the latest release into a directory, preferably with the same release number (for example, Rice 2.3). The trunk version is found at https://svn.kuali.org/repos/rice/trunk/
  3. The initial checkout should take about 15 - 30 minutes, depending on your connection speed and operating environment. 
  4. After the checkout, edit the XML members found at your-directory\src\site\docbook\ (for example, Rice 2.3\src\site\docbook). The directory structure is explained in more detail below.

Rice DocBook directory structure

DocBook source code is found in the src/site/docbook directory. Subfolders are outlined below:

  • books - contains the top level book & article files, one for each book or article, e.g. IG.xml groups together all IG chapters with the glossary to generate the Install Guide
  • CDG - chapter files for the Client Developer Guide
  • common - files that are in more than one book, e.g. the common glossary which spans multiple guides
  • css - stylesheet overrides for HTML output
  • db_diagrams - static files for database diagrams
  • EDL_Guide - chapter files for the eDocLite Guide
  • help - chapter files for the Help Guide
  • IG - Installation Guide chapters
  • images - image files for screen shots and other diagrams included in documentation
  • Intro_to_Rice - chapter files for Introduction to Rice book
  • KEN_Guide - chapter files for the Kuali Enterprise Notification Guide
  • KEW_Guide - chapter files for the Kuali Enterprise WorkflowGuide
  • KRAD_Guide - chapter files for the Kuali Rapid Application Development Guide
  • KRMS_Guide - chapter files for the Kuali Rules Management System Guide
  • KSB_Guide - chapter files for the Kuali Service Bus Guide
  • stylesheets - style overrides for pdf output
  • TRG - chapter files for Technical Resource Guide
  • UG - chapter files for User's Guide

Most content editors will not need to make any style overrides. Additional information about the guidelines & purpose of each book/article are available on our Documentation Policy page.

Building the Documentation

Note: Building from a command line is the easiest way to apply the build properties and custom styles.

  1. Navigate to top level directory with pom.xml.
  2. Run the following command to build all the documentation in all formats:

    The documentation generation is attached to the pre-site phase in maven.
    If you would like to just generate the html while developing (which builds much faster), then run the following command:

  3. If the build is successful, you will see the following lines right before completion:

After the documentation is built, you can view the output files.

Rice 1.0.x

Icon

Please note that Rice 1.0.x only uses DocBook to generate a PDF file of the release notes which is then attached to a wiki page. In order to build the release notes for 1.0.x, use the following command.

# mvn clean install -DskipTests

You can then find the PDF file at doc/target/classes/release-notes.pdf

Getting the correct version number

Icon

In order to get the correct version number to appear in the documentation (as opposed to SNAPSHOT or milestone versions), check out the release after it's been tagged. Rice tags are currently found at http://svn.kuali.org/repos/rice/tags/.

 

Documentation Output Directory Structure

After build, the output files can be found in the target/site/reference directory. Relevant subfolders are outlined below:

  • html - here you will find single-page html versions of each item in the books file
  • html-multi - here you will find multi-page html versions of each item in the books file
  • pdf - here you will find pdf versions of each item in the books file

db_diagrams, images, and css folders here are copies of the source folders so that the generated documentation can access them.

Documentation Portal Page

The target/site/reference.html/portal.html page is designed to be an automatically generated portal page for release and will be linked to from the Rice Documentation Portal. It is a good place to start when testing the documentation and any new documentation should be linked to from this page.

References

Some Common Documentation Development Tasks

Adding a Book or Article

The simplest way to add a new book and article is to look in the books folder and copy a similar file and change the pertinent information. New books or articles need to be in the books folder to be processed at build time.

Adding a Chapter to a Book

  1. The simplest way to add a new chapter is to copy a chapter file in an existing book and change the pertinent information.
  2. Add the new chapter file to the top level book file in the books directory.

Adding Sections

  1. Sections are added with the <section> tag.
  2. Sections can be nested within sections.
  3. Each section has a title. The structure is as follows:

    <section>
    <title>Section Level One</title>
       <section>
       <title>Section Level Two</title>
       </section>
    </section>

  4. Depending on the level, sections will usually appear in the table of contents.
  5. To prevent a section from appearing in the table of contents, use this construct:

    <section role="NotInToc"><title>Do Not Show In TOC</title>

Adding an Image File

  1. Create the image file and add to the images directory.
  2. Use oXygen to link to the image file and you should be able to navigate to the image file in the GUI and the path will be generated for you. Image paths should be relative, i.e. "../images/image_name.png" and use underscores instead of spaces since they are more web friendly.

    Icon

    Make sure the image is sized properly by building the HTML and PDF versions and ensuring that they show up ok. Improperly sized images can look pretty bad, especially in the PDF output. Tools like Gimp are free and can be used to do the resizing.

  3. Image files are inserted in 2 ways into docbooks. The first method is an inline media object which will not appear in the list of figures. The second method creates an entry in the list of figures at the beginning of the document.

     <inlinemediaobject><imageobject><imagedata fileref="../images/EDL_Guide/example1.png" align="left" scalefit="1" width="100%" contentdepth="100%"/></imageobject></inlinemediaobject>

     -OR-

    <figure>
      <title>labelPlacement Options</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="../images/KRAD_Guide/labelPlacement.png"/>
        </imageobject>
      </mediaobject>
    </figure>

  4. At times, images have a larger image available. Here is the way we code for this in docbook:

    <figure>
      <title>Eclipse: Select maven project</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="../images/archetype/2_eclipse_dbk.png"/>
        </imageobject>
      </mediaobject>
    <para><link xlink:href="http://site.kuali.org/rice/${project.version}/reference/images/archetype/2_eclipse.png">Click to enlarge</link></para>
    </figure>

  5. To fix alignment and page fitting issues with images
    1. first try making the image span the page with scalefit="1" as follows:

       <imagedata fileref="../images/KRAD_Guide/column_calc_3.png" scalefit="1"/>

    2. Next try changing contentwidth or contentdepth (only one or the other, otherwise the image will be distorted in some way: stretched, shrunk, or truncated). For example:

       <imagedata fileref="../images/KEW_Guide/BlanketApproveParallelTest.png" scalefit="1" contentdepth="600"/>#  

In DocBook 5, the preference is to have xlinks for hyperlinks. If you use the oXygen GUI to add the link, you'll need to right-click on the link and add the xlink:href property with the url of your link as the value.

To get the link to open in a new window, add the xlink:show property with a value of "new":

<link xlink:show="new" xlink:href="KRMS_Guide.html">HTML</link>

 

Links to external documents within a release should be entered like this:

 <link xlink:href="http://site.kuali.org/rice/${project.version}/reference/html/UG.html#reporting_rice_jira">report it in Jira</link>

Note: In the above example, this presumes we have the following within one of the UG books:

<section xml:id="reporting_rice_jira">

 

Links to internal documents (i.e. another section of the same document) should be entered as:

 <link linkend="linkAndLinkField">Uif-Link</link>

where elsewhere in the document there exists:

 <section xml:id="linkAndLinkField">

 

To link to a figure, set up the figure to have an xml id as follows:

 <figure xml:id="fig1"><title>Service Based Architecture</title>

Then link to it from anywhere within the same book, with the auto generated figure number and given title "My Figure" as follows:

The SOA architecture is depicted in <xref linkend="fig1"></xref>.

The above text will be rendered as (something like)

The SOA architecture is depicted in Figure 1.1, "Service Based Architecture".

(except that the figure number may be different depending upon the context, since it is dynamically generated)

Formatting Code Snippets

In order to have code snippets formatted properly, you will need to use the <programlisting></programlisting> XML tags. You can switch to XML view and add them inside the <para></para> tags. If you want to add line numbers to your code listing, the easiest way is to simply type them in manually on each line. The method for automatically producing line numbers for both PDF and HTML output is very complex and prone to errors.  

Note that when adding code snippets containing the character "<", DocBook and XML will always attempt to interpret that as the start of a new tag. In order to bypass that, change all occurrences of "<" in the code snippet to "&lt;".

Callouts

Sometimes it is helpful to insert callouts from code snippets to provide extra information. To do so, on the line of code you wish to have a callout, enter <co xml:id="sometag-co" linkends="sometag"/>. Then, in the body of the text, enter:

<calloutlist>
   <callout arearefs="sometag-co" xml:id="sometag"><para>Some useful explanation of the code</para></callout>
</calloutlist> 

Callouts will automatically generate numbers, starting at 1 and up to 30, for each callout within each document. Additional callout numbers will be generated after 30, but you will need to provide or generate the icon images and place them into the images/callouts directory (since DocBook only provides up to 30). The callout images appear as black circles with white numbers in the middle. HTML output uses .png files, and PDF output uses .svg files. In addition to the graphic icons, callouts provide active links between text and code (the callout images are the links). 

Tables

Using "CALS" tables instead of "HTML" tables appears to produce better looking output if you want a table with borders.

Tables are tricky, especially in PDF, since the processor will not split up words (unlike HTML), causing words to be truncated or to overrun the table boundaries. The output for PDF needs to be manually adjusted by the following methods:

  1. Striping may be added for readability: <table frame="all" tabstyle="striped">
  2. Make a table span the width of a page: <table pgwide="1"> <?dbfo table-width="100%" ?>
  3. Adjust the column width of each column:

     <colspec colname="c1" colnum="1" colwidth="0.8*"/>
     <colspec colname="c2" colnum="2" colwidth="1.0*"/>
     <colspec colname="c3" colnum="3" colwidth="1.2*"/>

  4. Generate and review the PDF output, and make any further adjustments
  5. Since the generation of PDFs can take some time, it is recommended to copy the table(s) in question into a smaller docbook that will run sooner in the PDF generate process, such as release-notes.xml. After the PDF has generated release-notes.pdf, the generate process can be cancelled by entering <CTRL-C> and typing "y" when prompted by the console. In this manner, the review of the table changes can be done in about 5 or 10 minutes. Once satisfied, the table(s) can be copied and pasted back into the original document(s), and the release-notes.xml restored from HEAD.

Lists

There are 4 kinds of lists used in DocBook:

  • itemizedlist: A list where each item is displayed with a bullet or other symbol, like a ul list in HTML. Example: 

    <itemizedlist>
      <listitem>
        <para>The link content element component renders an html label tag</para>
      </listitem>
      <listitem>
        <para>The text for the label is specified using the <emphasis role="keyword">labelText</emphasis> property</para>
      </listitem>
      <listitem>
        <para>The <emphasis role="keyword">labelForComponentId</emphasis> property on a label
          specifies the component id the label is associated with</para>
      </listitem>
    </itemizedlist>

  • orderedlist: A list where each item is numbered sequentially, like a ol list in HTML. Example:

    <orderedlist>
      <listitem>
      <para>Sending email to specified individuals </para>
      </listitem>
      <listitem>
      <para>Turning off some of the Rice "back doors" </para>
      </listitem>
    </orderedlist>

  • variablelist: A list where each item has a term and an associated description, like a dl list in HTML. Example:

    <variablelist>
      <varlistentry>
      <term>showLightboxUrl(url)</term>
      <listitem>
        <para>The content for the lightbox is loaded from the specified url.</para>
      </listitem>
      </varlistentry>
    </variablelist>

  • simplelist: A simple list of elements, which can be listed horizontally or vertically. Ideal for lists of small items. Example:

    <simplelist>
      <member>If more than 8 Candidates are to be interviewed, an additional Interview Request should be created.</member>
      <member>The OAA number used is the same as the one provided by the Office Affirmative Action for the corresponding Vacancy Notice. </member>
    </simplelist>

Program listings with line numbers

By default blocks of program listings do not have associated line numbers.  To turn this on use the following...

Icon
Adding in the startinglinenumber = "n" within the programlisting tag will allow you set the line number to start with for that block of program.
Icon
Note: You need to do this for each programlisting you create in a document.

Use of Project Variables from pom.xml

In the documentation, you will likely want to make use of some project variables like version number so that it is automatically generated each time the pom.xml is changed. Some common project variables are listed below:

Adding new styles

To add a new style for both HTML and PDF output, follow these steps.

  1. For the HTML document, edit the stylesheet.css file located in the docbook\css folder.
  2. Say your style is named "newstyle", which you want to be monospace, bold, and with a light gray background. At the end of stylesheet.css, you would add these lines like the following which will appropriately format the HTML document:

     .newstyle { 
        background: #EEEEEE;
        font-family:Monaco, Menlo, Consolas, "Courier New", monospace;
        font-weight:bold;}

  3. Now to add the same effects to the PDF document, you would add the following to the fo-stylesheet.xsl found in the docbook\stylesheets folder:

    <xsl:template match="*[@role = 'newstyle']" mode="class.value">
      <xsl:value-of select="'newstyle'"/>
    </xsl:template>
    <xsl:template match="emphasis[@role = 'newstyle']">
      <fo:inline> 
        <xsl:call-template name="dbfo-attribute"/>
        <xsl:attribute name="background-color">#EEEEEE</xsl:attribute>
        <xsl:attribute name="font-family">monospace</xsl:attribute>
        <xsl:attribute name="font-weight">bold</xsl:attribute>
        <xsl:apply-templates/>
      </fo:inline>
    </xsl:template>

  4.  Finally, surround your selected text in your xml document using the new style "newstyle" as follows:

    <emphasis role="newstyle">my text</emphasis>

  5. Save your changes and generate your HTML and PDF files. 
  6. Review and make any necessary adjustments.

Other Useful Information

  1. <CTRL-B> key combination will bold highlighted text (wraps the tag <emphasis role="bold"></emphasis> around the text)
  2. To highlight a keyword, use <emphasis role="keyword">my keyword</emphasis>. This will make the text my keyword stand out from the other text by using a monospace font, which is bolded and shaded with a light gray background color. 
  3. Always do a compare before committing changes to ensure you are changing the latest version and will not have any conflicts 
  4. It is recommended to do a local generate especially when changing multiple sections

Release Notes

  1. Release notes are located in the src\site\docbook\books directory.
  2. They are a combination of resolved JIRAs and additional notes added by the Development Managers (DMs).
  3. When a release is complete (or "cut" or "frozen"), that is the time to get the list of JIRAs and create the Release Notes for all the resolved JIRAs. 
  4. Before the release is finished, obtain the necessary information to fill out the other non-JIRA portions of the Release Notes from the DMs. Update and get feedback from the DMs as necessary. Note especially any upgrade scripts that need to be run.
  5. Upgrade scripts are usually in a separate folder, for instance: scripts/upgrades/2.1.3 to 2.2.1/final/update_final_mysql.sql
  6. Another necessary step is to review all the JIRAs to ensure the selected ones for the release are the ones that should be included, as per the recently added "Include in Release Notes" check-box. Make any necessary adjustments to include or exclude specific JIRAs as needed. 

To create the JIRA list:

  1. Download and install PHP on your local machine (if not already there) 
  2. Download the php executable program release-notes.php and place it in the php/dev folder (note: this program was initially created by Farooq Sadiq and later modified by Grant Trudel)
  3. Download and edit the config.ini file in the php/dev folder
  4. In the [user] section set name and password to the ones you use when logging into the JIRA system
  5. in the [release] section enter any new release in the list, such as 2.4 = 2.4 (this list allows a release to contain lesser release JIRAs, for example, 2.3.1 = 2.3,2.3.1)
  6. In your php/dev folder run the command 

     php release-notes.php > rnxyz.txt x.y.z

  7. (where x.y.z = release). For example, for release 2.3.1, you would run:

     php release-notes.php > rn231.txt 2.3.1

    Note: this runs query or filter number 18018, which reads:

     project = KULRICE AND status in (Resolved, Closed) AND resolution in (Complete, Fixed) AND type != "Sub Task" AND "Include in Release Notes?" = Yes ORDER BY type ASC, key ASC

  8. After a successful run (which usually takes about a minute), the xml formatted JIRAs will be in, for example, rn231.txt. Using any text editor, simply copy and paste directly into the release-notes.xml file in the "items addressed in Rice" section.
  9. Verify changes by executing a local generate.
  10. Commit changes through SVN.
  11. The advantages to using this method include:
    1. Automatic inclusion of all completed JIRAs for a release
    2. Automatic exclusion where the "Include in Release Notes" is unchecked
    3. Automatic exclusion of sub-tasks
    4. Automatic formatting in standard XML
    5. Automatic substitution of "<", ">", "&" characters in JIRA titles

Alternatively, the JIRA list for the release can be manually downloaded and edited as follows:

  1. Go to https://jira.kuali.org/browse/KULRICE
  2. Click on the appropriate release
  3. Click on 'Release Notes' in the upper right corner of the Summary tab
  4. Select all the text area in the Edit/Copy Release Notes section
  5. Copy and paste into release-notes.xml
  6. Remove sub-tasks
  7. Search/replace the following:
    1. <h2> with <section><title> 
    2. </h2> with </title>
    3. <ul> with <para><itemizedlist>
    4. </ul> with </itemizedlist></para>
    5. <li>[<a href with <listitem><para>[<link xlink:href
    6. </li> with </para></listitem>
    7. </a> with </link>
  8. Manually add the </section> tags
  9. Remove JIRAs that weren't 'Fixed'. Find these with a query like:

     project = KULRICE AND  fixVersion = "2.3.1" AND resolution != 'Fixed'

  10. Substitute "<", ">", "&" characters in JIRA titles (replace with "& lt;", "& gt;", and "& amp;" respectively, without the space after the ampersand)
  11. Review what's there & update

Testing/Sharing the Documentation

Once you've built and verified locally that the documentation builds, you may want to share with others. While we use the site.kuali.org links for public consumption, internally we should use site.origin.kuali.org to ensure that reviewers get the latest changes. There is a lag time between updates between site.origin.kuali.org and site.kuali.org.

  1. http://www.docbook.org/
  2. http://docbook.sourceforge.net/
  3. http://sourceforge.net/projects/docbook/
  4. http://www.oasis-open.org/docbook/
  5. http://www.oxygenxml.com/
  6. http://us.php.net/
  7. http://php.net/downloads.php
  • No labels