Table of Contents
- How to edit the docbook files
- How to use Oxygen on ROOT docbook tree
- How to open files
- How to edit files
- How to syntax check and fix errors
- How to generate preview of single file
- How to generate complete pdf
- How to generate complete html or in chapters
- How to use vi/emacs on ROOT docbook tree
- Miscelleneous
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 [2].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 [3].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.
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/