top

COMP 402: Production Programming

← Documentation with DocBook →

Home — Spring 2009

Today's Menu:

Documentation with DocBook

Documentation with DocBook

The semester is coming to a close, and I would like to thank all of you for your hard work. This was one of the best Production Programming (COMP 402, formerly 312) classes in many years.

As you know there is no final in the class, so there are just two things left for you to do: One of them is to finish the tasks you are working on right now. The other is to document any changes you have made so that the user can understand them. This involves editing the DocBook files for the User Documentation and the Quick Start Guide.

DocBook is an XML dialect and somewhat similar to XHTML (which is an XML-ified HTML), but different. It can be rendered both into HTML files for the web and the help files inside DrJava, and into PDF files that can be printed. All of that is automated using ant scripts.

First, you need to add one line to your .bashrc file that I had forgotten to list in the DrJava build process lecture:

export DOCBOOK_XSL_HOME="/usr/share/sgml/docbook/xsl-stylesheets-1.65.1-2"

To check out the documentation, run

svn co https://drjava.svn.sourceforge.net/svnroot/drjava/trunk/docs

Then change into the docs directory and run

ant jar

This should compile the user documentation in src/user, the Quick Start guide in src/quickstart, and the developer documentation in src/developer, and then create a docs.jar file that can be copied into the drjava/lib directory. It also creates HTML files in the docs directory. You should open the generated files, look for the places you have edited, and check that the formatting makes sense.

The list below contains the tasks you have worked on and that have affected the user interface. You may have worked on more tasks then the ones listed, but many bug fixes were mostly behind the scenes. Please check the tasks and the user documentation and Quick Start guide to see where you need to edit the documentation. Please remember to describe the settings you may have added to the Preferences or the Project Properties dialog.

As for learning DocBook, I just suggest you just copy and paste existing parts and then modify them. There is also an online book available. I'll help you if necessary.

← Documentation with DocBook →