Publishing DocBook

Contents

DocBook as OLE help - pdf, html, webhelp

Peri worked with Jeff to add the documents to SVN. See Developing Rice DocBook Documentation
(Kuali OLE followed Rice and is currently using the DocBook 5 format for documentation and the docbkx-maven plugin to generate the documentation as part of our maven build.)
The difference between OLE and Rice documentation is that OLE has decided to use Webhelp output for our documentation whereas Rice uses only HTML. See the plugin documentation here: http://docbkx-tools.sourceforge.net/docbkx-maven-plugin/plugin-info.html.

Needed to change the image links. <Inlinemediaobject> is for images that occur within text. <screenshot><mediaobject> is for images that occur on their own line, separated from the text.
Example:

<inlinemediaobject>
                        <alt>Location Level</alt>
                        <imageobject>
                            <imagedata fileref="../images/DescribeNoTitlePage-178.png"/>
                        </imageobject>
                    </inlinemediaobject>
Or
<screenshot><mediaobject>
                            <alt>Location Level Document</alt>
                            <imageobject>
                                <imagedata fileref="../images/DescribeNoTitlePage-179.png"
                                    width="100%"/>
                            </imageobject>
                        </mediaobject>
                    </screenshot>

Set up links to other webhelp space, link to the anchor like this:
```
<link linkend:href="_searchingOLE">Searching OLE</link>
```
This assumes that you have an anchor at the space
```
<anchor xml:id="_searchingOLE"/>
```

Separated out the chapters into individual xml files and pasted the docbook document type declaration in the chapter element:

<chapter xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" version="5.0"
    xml:lang="en-US">

Created an index page

Additional steps for editing and committing documentation

Needed to complete a CLA (on the Subversion wiki page)
Needed to complete OWASP training
Checked out the project via Oxygen (Oxygen is available from iuware for those at IU, may be available through other universities also)

1. Tools > SVN client > Repository > host: https://svn.kuali.org/repos/ole > currently, the project is in branches/kole-{current release}-Docbook/src/site/docbook
2. Checked out to local computer
3. Modify
4. Check back in through Tools > SVN client > working copy > Refresh, then right click copy and "commit"

Once saved but before committing, you can view changes locally through the command line.

1. Enter your local OLE directory, once per day run
  1. svn update
  2. mvn clean install -DskipTests=true
2. Each time, to test type "mvn clean pre-site -N".
3. To view the changes, open Windows Explorer and dig into the correct folder: your local OLE directory > target > site > reference > pdf, html or html-multi.

DocBook as built-in help (webhelp)

Peri had to do some modifications to get the webhelp to display correctly. We had to modify images and tables to get them to display correctly. Webhelp pages are now linked with OLE.

See the plugin documentation: http://docbkx-tools.sourceforge.net/docbkx-maven-plugin/plugin-info.html