How to edit docs

This page includes information on how to edit the GT Release Manuals via the CVS repository.

Background

Our docs are stored in the CVS repository that houses the Globus website files (note this is a separate repository than the source code).

Doc files are in DocBook XML format and processed in both html and PDF formats.

Once you have checked out your desired directory, see the docbook primer for more information on how the files are organized.

Who has access?

Only those with commit access have the ability to check in (make changes, also known as "commit") changes to the doc code.

CVS Details

This page assumes you have some basic experience with "Concurrent Versioning System" otherwise known as CVS. To learn more about CVS in general, visit ximbiot.com, or read the tutorial.

The following are details about the repository to help you run your CVS commands:

The following is a typical example of a command a commiter named 'johndoe' might run to check out the code for gridftp docs:

First, johndoe sets the CVSROOT environment variable to the repository's path (the following is one example of setting CVSROOT - it depends on your environment):

% CVSROOT=:ext:johndoe@cvs.globus.org:/home/globdev/CVS/alliance-web

Then, he checks out the GridFTP docs directory for v 4.0 as follows:

% cvs co alliance/toolkit/docs/4.0/data/gridftp

Editing can be done using a simple text editor. However, there are numerous free and commercial programs available that can be especially useful for DocBook editing. TODO (add links).

Once changes are committed to the repository, they are automatically copied over to the web - so your changes should be live as soon as they are committed.

The URL for the online docs follows this pattern:

www.globus.org/toolkit/docs/<version>/<area>/<component>/

Note: the version number is changing from 4.0 to 4.2. We used to collect all documentation under the version minor number (4.0). Starting with 4.2, we will be releasing docs for each point version (4.2.0, 4.2.1, etc).

When replacing binary files such as pdfs or images - make sure you overwrite the file in your checkout and then commit the new version.

Special note for development docs

Documentation of development releases is found in a special subdir:

alliance/toolkit/docs/development/

During our development cycle (the current one is leading up to 4.2 final) documentation is refined in:

alliance/toolkit/docs/development/4.2-drafts/

With each development release, a branch of the existing doc code is made. For example, the docs for the 4.1.0 development release are found in:

alliance/toolkit/docs/development/4.1.0/

The URL for the development docs draft area is:

www.globus.org/toolkit/docs/development/4.2-drafts/<area>/<component>/

Directory organization

Underneath the version number, docs are organized by 'functional family' (the following is in alphabetical order).

Organization under 4.2.0

The doc root for 4.2.0 is: alliance/toolkit/docs/4.2/4.2.0/

common/
ccommonlib (C Common Libraries)
cwscore (C WS Core)
javacog (CoG jglobus)
javawscore (Java WS Core)
pyglobus (pyGridware)
pythonwscore (Python WS Core)
xio (XIO)

data/
datarep (Data Replication Service)
gridftp (GridFTP)
rft (Reliable File Transfer)
rls (Replica Location Service)
wsrls (Web Services Replica Location Service)

execution/
gram2 (Pre-WS GRAM)
gram4 (WS GRAM)
gridway (GridWay)
gtcp (Globus Teleoperations...)

info/
aggregator (WS MDS Aggregator Framework)
archive (WS MDS Archive Service)
index (WS MDS Index Service)
providers (Information Providers)
trigger (WS MDS Trigger Service)
usefulrp (WS MDS UsefulRP Framework)
webmds (WS MDS WebMDS)

security/
cas (WS A&A Community Authorization Service)
delegation(WS A&A Delegation Service)
gsic (GSI C)
myproxy (MyProxy)
openssh (GSI-OpenSSH)
simpleca (SimpleCA)
wsaac (WS Authentication and Authorization in C)</br> wsaajava (WS Authentication and Authorization in Java)

Organization under 4.0

The doc root for 4.0 is: alliance/toolkit/docs/4.0/

common/
ccommonlib (C Common Libraries)
cwscore (C WS Core)
javawscore (Java WS Core)
xio (XIO)

contributions/
csf (Community Scheduler Framework)
gridway (GridWay)
javacog (CoG jglobus)
pyglobus (pyGridware)
pythonwscore (Python WS Core)

data/
gridftp (GridFTP)
rft (Reliable File Transfer)
rls (Replica Location Service)

execution/
prewsgram (Pre-WS GRAM/GRAM2)
wsgram (WS GRAM/GRAM4)
wsrendezvous (WS Rendezvous)

info/
aggregator (WS MDS Aggregator Framework)
index (WS MDS Index Service)
prewsmds (Pre-WS MDS)
providers (Information Providers)
trigger (WS MDS Trigger Service)
usefulrp (WS MDS UsefulRP)
webmds (WS MDS WebMDS)

security/
authzframe (WS Authorization Framework)
cas (Community Authorization Service)
delegation (Delegation Service)
message (Message/Transport-level Security)
myproxy (MyProxy)
openssh (OpenSSH)
prewsaa (Pre-WS Authentication and Authorization)
simpleca (SimpleCA)

techpreview/
datarep (Data Replication Service)
gtcp (Globus Telecontrol Protocol)
ogsadai (OGSA-DAI)
sgas (SweGrid Accounting Service)
wms (Workspace Management Service)

Editing in DocBook

See the docbook primer for more in depth information about how the documentation is written/organized in docbook as well as best practices for using the tags.

Building docs locally (coming soon)

We have changed the implementation of DocBook for 4.2+ and will need to re-assess how to build docs locally.

<xsl:import href="/usr/share/xml/docbook/stylesheet/nwalsh/html/chunk.xsl"/></pre>

to

<!-- Which DocBook standard xsl file should we use as the default? --> <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"/>

B) Download the following files and save them in the directory ABOVE yours (either common/, data/, execution/, info/, or security/):

• http://www.globus.org/toolkit/docs/templates/testing/_test.xml (right click link and Save Link As..)
• http://www.globus.org/toolkit/docs/templates/testing/Makefile (right click link and Save Link As..)

IMPORTANT: do not add the above files to CVS!

Then modify _test.xml as follows:

change the entity ref:

&javawscore;

to the entity ref for your project (it's the same name as your directory) - for example, if your project is GridFTP and your directory is under gridftp/, change the entity ref to:

&gridftp;

Now you're ready to either just run xmllint to check for errors or to make the html set for your project in your environment.

To check your XML for errors without building the HTML

In the same directory you saved the _test.xml and Makefile files (for example, data/), run:
make xmllint

To generate the HTML for your project as well as check for errors

In the same directory you saved the _test.xml and Makefile files (for example, data/), run:
make html

Debugging DocBook

You may have a learning curve understanding the xmllint errors are first, but feel free to ask the Documentation Coordinator for help deciphering them.

Here's a good reference of DocBook elements to help with debugging: http://www.docbook.org/tdg/en/html/part2.html

Limitations

Because the entire set of release manuals is one valid XML file, when you test on just one part of it, you will receive some errors that you can disregard.

Errors you may encounter include:

• Errors for all links that go outside of your component (for example, everyone should get an error for "gtadmin" as that is the top-level sysadmin guide) and in your html, those links will be broken.
• Errors for glossary terms (as it won't be hooked up to the glossary database at the set level)

xmllint

TODO: show examples of xmllint error and how to decipher them. -->

Committing your changes

FYI, commits will trigger Makefiles as follows:

• In your root directory (for example, docs/4.2/4.2.0/data/gridftp/), a commit on any file or files will trigger make and build docs in the root directory (which builds the TOC) and then all subdirs (which correspond to each guide).
• A commit in any of the subdirs will trigger make and build docs only in that subdir.

This is what happens after you commit your changes:

NOTE: The following commands reflect what's happening on the Globus side, *not* in your test environment as described above.

1) First, xmllint is run to catch errors against the DTD:

xmllint \
--valid \
--noout \
--noent \
index.xml

If there are errors in the DocBook, descriptive errors will be output and the HTML will not be built.

TODO: add information on deciphering xmllint errors.

2) If there are no errors, the html is generated using xsltproc:

xsltproc \
custom_html.xsl \
index.xml

And then DocBook starts writing the HTML pages.

Troubleshooting

TODO mention common errors I/O resulting in make error html not made