Docbook HOWTO

Table of Contents

How to edit the docbook files

With Oxygen

Oxygen is an XML editor. While typing XML (docbook) code it will help you on the fly. For instance an opening tag will be automatically matched with the corresponding closing tag, and a live syntax checking is performed (a green square near the scrolling bar at the top right of your document means it is syntactically correct).

Oxygen offers several modes to edit a document "Text", "Grid" and "Author" (see the button at the bottom of the editor window). You can use the one you want, but after some time you will very likely find out that the "Text" mode is the more appropriate to edit docbook documents.

Installing Oxygen

Download and install Oxygen from the Oxygen Web Site.

With vi/emacs

The docbook (xml) files are ASCII files, therefore they can be edited with your preferred text editor. Despite the fact Oxygen does live syntax checking and help, it might be sometimes useful to use a normal text editor. For instance when you have only a tiny change to do or if you have repetitive editing commands which can be more easily done with a text editor you fully master.

How to use Oxygen on ROOT docbook tree

The ROOT's docbook documents are in $ROOTSYS/docbook. The Users' Guide is in $ROOTSYS/docbook/users-guide. This directory contains mainly xml ASCII files, one per chapter:

ALittleC++.xml		Histograms.xml		ROOTandQt.xml
AddingaClass.xml	InputOutput.xml		Threads.xml
CINT.xml		InstallandBuild.xml	Trees.xml
CollectionClasses.xml	Introduction.xml	TutorialsandTests.xml
Cover.xml		LinearAlgebra.xml	Users-Guide.xpr
ExampleAnalysis.xml	MathLibraries.xml	WritingGUI.xml
FittingHistograms.xml	Networking.xml		makeepub.sh
FoldersTasks.xml	ObjectOwnership.xml	makehtml.sh
Geometry.xml		PROOF.xml		makehtmlchunk.sh
GettingStarted.xml	PhysicsVectors.xml	makepdf.sh
Graphics.xml		Preface.xml		pictures
Graphs.xml		PythonRuby.xml
HTMLDoc.xml		ROOTUsersGuide.xml

The *.sh files are scripts to build the various formats of the ROOT User's Guide, (from the xml files). The pictures directory contains all the pictures in .png format. Users-Guide.xpr is the master file for the Users' Guide.

How to open files

Start Oxygen and open the file Users-Guide.xpr from the menu File->Open. Or go in the directory $ROOTSYS/docbook/users-guide and double click on Users-Guide.xpr. Next time Oxygen will remember that you are working on the ROOT User's Guide and it will be enough to start Oxygen in order to have Users-Guide.xpr ready.

How to edit files

Once the file Users-Guide.xpr is open in Oxygen, you can see all the chapters in the column on the left (see image below).

Double click on the chapter you want to edit ad it will appear in the central part of the Oxygen window. Then you can choose and the bottom with editing mode you want to use: "Text", "Grid" or "Author".

In "Text" mode you edit directly the xml file as you would in a normal text editor. The "Grid" mode gives a hierarchical view of the document. The "Author" mode is more "WYSIWYG". From now on lets assume we work in "Text" mode.

How to syntax check and fix errors

Several documents exist on the web describing the docbook syntax. The reference one being DocBook: The Definitive Guide.

But the simplest/best way to learn the syntax is surely to look at the ROOT User's Guide. Oxygen is a great help also to learn. Once you start typing a tag it automatically proposes you the valid ones and write the closing tag at the same time.

The tag attributes appear in the top right subwindow. A green square at the top right of the edited file tells that the file syntax is correct. As soon as a mistake appears, this square becomes red and a red mark on the slider on right locates it in the file.

For instance, if you type a piece of text outside any tags (this is a common mistake), you immediately see the red lights flashing !

How to generate preview of single file

In the bottom right subwindow you will find the various transformations you can apply on the xml documents in order to generate PDF or HTML outputs.

Three of them are related to the ROOT User's Guide. They allow to generate HTML or PDF versions of the chapter you are currently editing. To do that, just choose the transformation you want to perform and press the little red arrow top left.

  • "ROOT Docbook HTML" generates the HTML version in one single file.
  • "ROOT Docbook HTML - Chunk" generates the HTML version in several separated files (chunks).
  • "ROOT Docbook PDF" generates the PDF version in one single files.
HTML in chunks and the full PDF are the formats we put on the ROOT web site.

How to generate complete pdf

Double click on ROOTUsersGuide.xml in the left column. The file appears in the editor part of Oxygen and then procede as before ie: select "ROOT Docbook PDF" in the bottom right window and click on the red arrow top left.

How to generate complete html or in chapters

Double click on ROOTUsersGuide.xml in the left column. The file appears in the editor part of Oxygen and then procede as before ie: in the bottom right window select "ROOT Docbook HTML" to generate complete html, or "ROOT Docbook HTML - Chunk" to generate the HTML in chapters and click on the red arrow top left.

How to use vi/emacs on ROOT docbook tree

As the docbook xml files are ASCII files, you ca also use your preferred text editor to modify them. In some cases it might be more convenient than Oxygen. Also using them in parallel might be a good solution. As soon as you save the modifications you did in your text editor they will appear in Oxygen when the Oxygen window becomes active again.

How to generate complete pdf

$ cd $ROOTSYS/docbook/users-guide
$ ./makepdf.sh 

How to generate complete html or in chapters

Complete html in one file:

$ cd $ROOTSYS/docbook/users-guide
$ ./makehtml.sh 

Complete html in chapters:

$ cd $ROOTSYS/docbook/users-guide
$ ./makehtmlchunk.sh 

Miscelleneous

Once the complete PDF and complete HTML per chapters has been generated, it might be good to update the Users's guide on the web. The following script will do it:

cd $ROOTSYS/docbook/users-guide
scp ROOTUsersGuide.pdf username@root.cern.ch:doc/
scp pictures/*         username@root.cern.ch:doc/pictures/
scp chunks/*           username@root.cern.ch:doc/ROOTUsersGuideHTML/