How to edit docs

From Globus

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:
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).

Note: The following reflects the organization for 4.1.x (leading up to 4.2.0). [add section for 4.0 organization]

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)
ogsadai (OGSA-DAI)
rft (Reliable File Transfer)
rls (Replica Location Service)
wsrls (Web Services Replica Location Service)

execution/
csf (Community Scheduler Framework)
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/
authzframe (WS A&A Authorization Framework)
cas (WS A&A Community Authorization Service)
delegation(WS A&A Delegation Service)
gridshib (GridShib)
message (WS A&A Message-/Transport-level Security)
myproxy (MyProxy)
openssh (GSI-OpenSSH)
prewsaa (Pre-WS A&A)
sgas (SweGrid Accounting Service)
simpleca (SimpleCA)

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 in 4.2-drafts/

We have changed the implementation of DocBook under 4.2-drafts/ and will need to re-assess how to build docs locally. However, the new code does easily allow transformation in many XML editors (check and see if your editor supports transformation and xincludes). This is usually enough for most writers. Basic transformation usually does not include styles from our stylesheet. However, I would recommend *not* relying on how your content looks in the stylesheets. Just focus on the actual content - the stylesheet will take care of the rest.

Committing your changes

FYI, commits will trigger Makefiles as follows:

• In your root directory (for example, docs/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