Documentation Primer

8/6/2019 Documentation Primer

1/33

'RFXPHQWDWLRQ3ULPHU

Table of ContentsOverview of Globus Toolkit DocumentationWhy DocBook?Setting Up DocBook

Accessing Documentation via CVSIf You're A New Project...Converting Existing Files to DocBookCreating New Docs

1. Writing New Docs2. Adding New Docs to Your Release Manuals

Globus Toolkit Documentation Strategy

1. Fragments2. Standard organization3. Release cycle for documentation

Structure of a Component's Release Manuals

Requirements for Release Manuals1. Globus Toolkit General Documentation Requirements2. Key Concepts3. User's Guides

4. System Administrators Guides5. Developer's Guides6. Public Interfaces Guides

7. Release Notes8. Quality Profiles9. Migrating Guides10. Samples

Guide to XML files

1. Release Manuals2. Fragments List

Including Text1. XIncludes2. Replaceable Text

Paragraphs ( and )1. Brackets

Headings and Sections1. id attribute2. tag3. Example

Documenting Code ( and ) Links

1. Internal Linking ()2. External Linking ()

Graphics ()Lists

1. How to make an unordered list () 2. How to make an ordered list ()

3. How to make a definition list ()Tables ()Italics and Bold ()Calling attention to text

1. 2. 3.

4. 5.

GlossaryIndexing

Troubleshooting

2YHUYLHZRI*OREXV7RRONLW'RFXPHQWDWLRQ


2/33

This document includes the policies and guidelines behind the documentation for GT distributions, requirements

for documents and help for using the DocBook XML Schema for common documentation elements.

Our goal is to provide comprehensive documentation in a clear concise manner and in language that is not too

technical or obscure. To that end, we encourage all feedback, suggestions and comments for improving our

documentation and finding ways to make the information more easily understandable. For broken links and other

simple technical issues with using the docs online, send an email [email protected].

For everything else, you can file a bug in Bugzilla (use the Documentation project) or use the docfeedback box

available on each page of documentation online.

We thank you ahead of time for your help!

:K\'RF%RRN"

All Globus Toolkit documentation will be marked up to conform to the DocBook XML DTD. Theoretically, any strict

DTD would have been sufficient. However, DocBook is a publishing standard based on XML with similar goals to

the Globus Toolkit Documentation project. Some specific reasons why we are using DocBook:

y It is open-source.y A growing community surrounds DocBook (has mailing lists).y A number of free and commercial tools are available for editing and publishing DocBook documents.y It enables us to publish in a variety of formats (HTML, PDF, etc.)y XML separates content from presentation: It relieves each contributor of the burden of presentation, freeing

each writer to focus on content and sharing knowledge.

y It is well tested technology. (It has been in development since the early 1990's).The following DocBook primer walks you through the basics, and should cover the needs for 95 percent of the

documentation we produce. Remember to:

y Always close your tags with corresponding end-tags and to not use other tag minimization.y Write all elements and attributes in lowercase.y Quote all attributes.6HWWLQJ8S'RF%RRN

There are many ways to work with the DocBook documentation. At its simplest, you needCVS access, then if you

know how the code works, you can edit the XML files in a text editor. However, many people are more comfortable

setting up a separate test environment. You'll need some things to duplicate the processing that occurs when

producing the HTML/PDF output.


3/33

The following can help you with the Globus Toolkit Docbook XML documentation:

y Docbook XML DTD version 4.4 - The document type definition for XML. You can find an RPM or DEB package oryou can download a zip file from the site linked from here.

y XSL Stylesheets version 1.69.1 (docbook-xsl) - The stylesheets to convert to HTML. We have been using astylesheet based upon NWalsh's"chunk.xsl".

y xsltproc - The processor that will take an XML document and, given a xslstylesheet, convert it to HTML. Itneeds libxml2 and libxslt (available in RPM and DEB formats or from xmlsoft.org). It comes with xmllint, which

will be very useful for debugging.

y Some editing tool. Some options are:o XMLMind Personal Edition This is a highly recommended WYSIWYG XML editor that works well with DocBook.

The Personal Edition is free and provides an excellent way to 'visualize' your docs before committing your

changes. It validates and shows xincluded frags (discussedbelow). For more information about using

XMLMind, read this article (to read about editing xincluded files in particular, read this page of the article).

o Oxygen XML Editor (there is also a plugin available for Eclipse)o Syntext Serna (WYSIWYG)o Emacs with the psgml modeo xmledit for vimo Vexo Authoring with Eclipseo For a comprehensive list of editing tools, click hereo

$FFHVVLQJ'RFXPHQWDWLRQYLD&96

Please read the dev.globus Wiki page: How to edit docs for the most up to date information.

,I


4/33

y HTML to DocBooko Html2DocBooko html2db

y Text to DocBooko txt2docbook

y Word to DocBooko Wordplay (this is *not* free open-source - current price is $195 USD although there is a trial version

available)

y LaTex to DocBooko tex4ht

y OpenOffice to DocBooko ooo2dbko http://xml.openoffice.org/xmerge/docbook/o http://www.tldp.org/LDP/LDP-Author-Guide/html/oo2docbook.html

y Comprehensive list:o http://wiki.docbook.org/topic/ConvertOtherFormatsToDocBook

&UHDWLQJ1HZ'RFV

Table of Contents1. Writing New Docs2. Adding New Docs to Your Release Manuals

For the most part, you only need to edit existing DocBook files. However, the following information is helpful if you

need to create a new standalone doc.

Note

We only encourage standalone docs to supplement information that is already in the templates for standard

documentation or for information that does not fit within the template's structure. If you're not sure, contact

the Documentation Coordinator.

:ULWLQJ1HZ'RFV

First, you need to define a title for your document. Try to use a title that is as informative as possible using the

fewest amount of words possible. Also, try to compose a title with certain 'keywords' that will catch the attention

of readers who are looking for this information.


5/33

Then start thinking about the possible sections and subsections you will have in your document. Make sure you

coordinate with the Documentation Coordinator to make sure you're not writing something that someone else has

already written.

$GGLQJ1HZ'RFVWR


6/33

Coordinator will comment out frags that do not apply (for example, very few components have a GUI, therefore, it

is confusing/misleading to consistently list GUI topics where there is no applicable information.

From time to time, there will be information that is not compatible with the standard organization. In these cases,

if you have a clear idea of where it should go and how to add it, go ahead and update it. If you're not sure how to

include the information, consult the Documentation Coordinator. For more information, seeCreating New Docs.

5HOHDVHF\FOHIRUGRFXPHQWDWLRQ

The following list outlines what happens with documentation in a typical GT release cycle:

1. Once development begins for the next major release (we'll use 4.2.0 as an example release), a new folder isadded to the development docs directory as follows: toolkit/docs/4.2/4.2.0/.

2. Documentation Coordinator updates files for the upcoming release (changes version numbers, etc.)3. Developers start updating documents in this development directory for the upcoming release.

4. For each development release leading up to the stable release:a. After source code freeze, a corresponding directory is added to the development docs directory- for

example, ../toolkit/docs/development/4.1.5.

b. The drafts directory is frozen and copied over to the new directory.c. Documentation Coordinator updates references to release numbers.d. Documentation Coordinator and Release Manager go over development documentation for any other

necessary revisions.

e. Release notes are completed and the development release is announced.f. Freeze is lifted for drafts directory.

5. Before final stable release:y A new directory is added to the docs directory - for example, .../toolkit/docs/4.2.0/.y After source code freeze, the drafts directory is frozen and copied over to the new directory.y Documentation Coordinator updates references to release numbers.y Documentation Coordinator and Release Manager go over development documentation for any other

necessary revisions.

y Release notes are completed and the final release is announced.y After final stable release, the drafts directory is removed.


7/33

y Starting with 4.2.0, we will now be releasing a new documentation directory with each incremental release.For example, before releasing 4.2.1, we will have a docs freeze, copy existing information to

toolkit/docs/4.2.1/, unfreeze, and then update documentation and release notes in the new directory. This

is a new procedure and it will take one or two releases before we stabilize it.

6WUXFWXUHRID&RPSRQHQWV5HOHDVH0DQXDOV

Each book under a project has its own subdirectory. The default list of subdirectories is now:

y admin (Admin Guide)y developer (Developer's Guide)y mig (Migrating Guide)y pi (Public Interfaces Guide)y qp (Quality Profile)y rn (Release Notes)y user (User's Guide)Each technology family shares one Key Concepts Guide available in the key directory of the family directory. For

example, the Key Concepts Guide for GRAM4 is located in this

directory: toolkit/docs/4.2/4.2.0/execution/key/.

The main xml file for each book is the index.xml file.

Note

This list of books may be customized per project. For example, if the project has no end-users, there should

not be a "User's Guide".

Each book is divided into chapters (within the element) and each chapter is output as a single web

page (this also applies to ,, and elements). Many of these pages include

fragments (which are separate XML files as described here).

Take a look at the files of existing DocBook documents, or see the following chapter to get an idea of how they are

tied together.

5HTXLUHPHQWVIRU5HOHDVH0DQXDOV

Table of Contents

1. Globus Toolkit General Documentation Requirements2. Key Concepts3. User's Guides4. System Administrators Guides5. Developer's Guides6. Public Interfaces Guides7. Release Notes8. Quality Profiles

9. Migrating Guides10. Samples


8/33

*OREXV7RRONLW*HQHUDO'RFXPHQWDWLRQ5HTXLUHPHQWV

y Clarity in presentation.y Use best practices learned from the print world, web, and other media, about use of grammar, space, writing

style, etc:

o Consistency. It's important to be consistent in the use of terms and names for your project. For example,make sure that when you name a project, you consistently use the same name throughout documentation

to avoid confusion.

o Use standardized language. Consider international readers by not using slang or colloquial terms - many ofyour readers use English as a second language. This also helps make translation easier for anyone

interested in translating the documentation for internationalization efforts.

o All jargon used in documentation needs to be defined (using theglossary feature). Use standardized termswhen available, avoiding implicit understanding of specific Globus Toolkit terms.

y Single source - This practice significantly reduces obsolescence in writing and the burden of maintaining up-to-date documentation:

o Show where to find information instead of duplicating information - use a link or include text from a Frag ora subset from a bigger doc using XIncludes- anywhere in the 4.2.0 release manuals.

o If the information is not found elsewhere, then create one place for it where others can refer to it(see Creating New Docs or contact the Documentation Coordinator if you need help).

y Consider Globus Toolkit documentation as a set of books. Each book contains chapters and sections, whereeach chapter is a web page.

.H\&RQFHSWV

Key Concepts guides are at the 'family' level (common/, data/, execution/, info/, and security/) and explain

important concepts about the technologies within that family.

There is a very basic outline for key concepts but they should be customized for the specific technology they're

describing.

We encourage the use of graphics to demonstrate your key concepts!

As necessary, we also encourage adding standalone files if you have a large amount of information you want to

break down into separate files.

TODO: add guidelines for writing key concepts: heavy use of graphics, should describe each component in the

family (for example, security does a great job of describing cryptology and such, but does not mention how the

underlying components are related).


9/33

The Key Concepts Guide has the following required topics:

1. Overview: Provides high-level overview of the features of the component, as well as a description of theproblem space of relevance to the component. The discussion should be aimed at readers who are non-experts.

2. Conceptual Details: The bulk of this guide, includes several paragraphs outlining the fundamental conceptsthat underly the component.

3. Related Documents: Link to other documents (internal or external, whitepapers, presentations, etc.) thatsupplement the Overview.

8VHUV*XLGHV

This guide is for the most challenging audience for our documentation: end users. Please always keep in mind that

end users may have little technical background/knowledge for your project.

There are certain components (such as C Common Libraries, the Aggregator Framework) that do not have end-

users and therefore do not have User's Guides.

The User's Guide has the following required topics:

1. Introduction: Introduces the project to end users and references to the (upcoming) Toolkit-level User's Guidewhere they can find general end user-oriented information. Should mention all common end-user issues. For

example, the introduction to the Message-level Security User's Guide mentions "The main user issues for this

component deal with configuring credential-related settings. There are multiple mechanisms for doing this:..."

and goes on to briefly list them.

2. Using [component]: describes the most common ways end-users interact with this component usingexamples.

3. Command-line tools: Includes the ...Interface_Commandline_Frag.xml , which gives details on allcommands.

4. Graphical user interface: Includes the ...Interface_Commandline_Frag.xml , which describes how theUI works including browser/interface strengths and limitations.

5. Troubleshooting: Describes user-friendly help on common problems they may encounter.6\VWHP$GPLQLVWUDWRUV*XLGHV

The System Administrators Guide at the project-level picks up where the top-level Installation Guide leaves off

and has the following required topics:

1. Introduction: Introduces the guide to sysadmins and points them to the top-level Installation Guide forcomprehensive basic installation/configuration info. Mentions common admin-specific issues.

2. Building and installing: Includes information about building and installing your project that is not covered inthe top-level Installation Guide.


10/33

3. Configuring: Includes the [project]_Interface_Configuring_Frag.xml fragment for full information onconfiguration settings [cris: should we also embed environmental variables frag?].

4. Deploying: Includes deploying information (into various containers/environments) for your project that is notcovered in the top-level Installation Guide. [fixme: include java ws core deploying frags?]

5. Testing: Includes procedures for how to test the configuration that is not covered in the top-level InstallationGuide. Must include examples of the tests.

6. Security Considerations: Embeds the SecurityConsiderations frag.7. Troubleshooting: Describes help for common problems sysadmins may experience.'HYHORSHUV*XLGHV

Keep in mind the following when you edit Developer's Guides:

y This documentation should be written for ongoing reference by developers.y List practical development and diagnostics tools and methodologies.y List and link to Globus Toolkit development resources, API docs, schema files, etc.. Remember you can use

ViewCVS to link to the latest versions of schema, WSDL, and other files.

The Developer's Guide has the following required topics:

1. Introduction: Introduces the project to developers (people who use the programmatic public interfaces of GT).Mentions the main developer-specific issues that this guide will address.

2. Before you begin: Collects information useful to developers before they start working with the technology.Includes the following fragments: Features Summary, Tested Platforms, Backward Compatibility, Tech

Dependencies, Associated Standards, and Security Consideration.

3. Usage scenarios: Describes different scenarios of developing with this component (should describe using theprogrammatic interfaces and provide examples).

4. Tutorials: Include tutorials. Can link to any developer tutorials. Tutorials do not conform to a template, butthey are strongly encouraged. The files can be in any format as long as they are available online.You can add

the files to your project's doc CVS repository or on your own web space. Keep in mind the following when

writing them:

y Use links to Developers Guide or use xincludes instead of duplicating information.y List suggestions for installing and setting up a development environment; these can be annotated links to

the top-level Installation Guide.

y Provide working examples.y Include general rules to follow for stability, scalability.y Include a summary of important links used by developers.


11/33

y Note any deprecated tools and methods by linking to prior versions instead of describing them in currentdocs.

y If there are no tutorials, write "There are no tutorials available at this time."5. Architecture and design overview: Describes the architecture and design at a high-level with links to

architecture and design docs. Diagrams are strongly encouraged.

6. API: Includes API Frag which links to API docs.7. Commandline tools: Includes Commandline Frag which details all commandline clients.8. Configuration: Includes Config Frag which details all configuration settings.9. Domain-specific interface (name it): Includes Domain Frag which describes any domain-specific interfaces

(such as the job descriptions for GRAM4).

10.Environmental Variables: Includes Environment Variables Frag which describes any project-specificenvironmental variables.

11.GUI: Includes GUI Frag which describes any GUI interfaces.12.Services and WSDL: Includes WSDL Frag which describes WSRF interfaces including schemas and WSDL (for

WS components only).

13.Debugging: Provides information for debugging the project.14.Troubleshooting: Describes help for common problems developers may experience.15.Samples: If available, includes ..._Samples.xml which includes sample code for your project.16.Related Documentation: Links to PDFs and whitepapers about protocols, etc., about the project.3XEOLF,QWHUIDFHV*XLGHV

A sub-set of the Developer's Guide, identifies the public interfaces for the project and includes the following topics:

1. APIs (includes the API frag)2. Services and WSDL (includes the WSDL frag)3. Command-line tools (includes the Commandline frag)4. Graphical User Interface (includes the GUI frag)5. Domain-specific interface (includes the Domain frag)6. Configuration interface (includes to the Config frag)7. Environment variable interface (includes the Environment Variables frag)5HOHDVH1RWHV

Describes implementation details to existing and potential users of a project distributed as part of a new stable

release.

Release notes include the following topics:

1. Component Overview (includes the Overview frag)


12/33

2. Feature Summary (includes the Features frag)3. Changes Summary (includes the Change Summary frag)4. Bug Fixes (includes the Fixed Bugs frag)5. Known Problems (includes the Known Problems frag)6. Technology Dependencies (includes the Dependencies frag)7. Tested Platforms (includes the Platform Summary frag)8. Backward Compatibility Summary (includes the Compatibility frag)9. Associated Standards (includes the Standards frag)4XDOLW\3URILOHV

Presents any current reports available on test coverage, resource and memory leak analysis, bounds checking,

and performance profiles.

Quality Profiles include the following required topics.

1. Test coverage reports2. Code analysis reports3. Outstanding bugs (includes the Known Bugs frag)4. Bug Fixes (includes the Fixed Bugs frag)5. Performance reports0LJUDWLQJ*XLGHV

TODO - do we need to update the versions we're covering?

1. Migrating from GT2 (includes the Migrating GT2 frag)2. Migrating from GT3 (includes the Migrating GT3 frag)6DPSOHV

Samples do not conform to a template; however, they are strongly encouraged. Samples provide test code for a

project, which makes it far easier to start developing with a project. Include your code in

a [project]_Samples.xml file and notify the Doc Coordinator (who will include it in the top-level Samples

guideand your project's Developer Guide).

*XLGHWR;0/ILOHV

Table of Contents1. Release Manuals2. Fragments List

The following is the default list of DocBook XML docs and files required for each project. First is a list of the files

that represent the standard standalone docs. Then we go through each of the fragments with a description and a

list of docs in which they are used.

5HOHDVH0DQXDOV


13/33

This section describes the various manuals available for most components. The following manuals are the default

list. Manuals may be tailored for specific components (for example, a tech preview or contribution without much

documentation support may only offer an Admin Guide and Release Notes). Others may be added as necessary.

Note

Paths are relative to your 'home' directory; for example, the GridFTP

'home' directory is toolkit/docs/4.2.0/data/gridftp/.File name Description Edit?

index.xml The home page This is the first

'page' of documentation for this

project and acts as the table of

contents - it's manually customized

for each component.

Usually no editing is

necessary unless you

are adding a link to an

important doc you

want to feature.

../key/index.xml Key Concepts Guide This guide coverskey concepts for the family of

technology (common/, data/,

execution/, info/ and security/). You

need to make sure that your

technologyis represented.

Edit the index.xml file

or add your own file

for your technology

and let the

Documentation

Coordinator where it

should appear in the

guide.

mig/index.xml Migrating Guide Includes information

about migrating from previous major

versions of GT.

No editing needed.

pi/index.xml Public Interfaces Guide Includes

information about all public interfaces

for this project.

No editing needed.

qp/index.xml Quality Profile Includes links to

various reports and bug information. You need to update

links to test coverage,code analysis and

performance reports.

rn/index.xml Release Notes Compiles information

about the project for this release. No editing needed.


14/33

admin/index.xml System Administrator's Guide Includes

information about installing, building

and deploying that is outside of the

top-level Admin Guide.

You need to update

information about

building and installing,

deploying, testing, and

troubleshooting.

developer/index.xml Developer's Guide Includes information

useful to developers of this project. You need to update

information about

architecture and

design, tutorials, usage

scenarios, debugging,

troubleshooting, and

any related documents.

user/index.xml User's Guide Includes information forend users of your project. You need to update

information about using

your technology (for

end-users),

troubleshooting, and

add anything else

useful to end users.

)UDJPHQWV/LVW

The list of fragments is provided in alphabetical order with a description of the contents as well as a list of the docs

in which it is included by default. You need to make sure all Frags are filled in.

File name Description Appears in...

[projectName]_Associated_Standards_Frag.xmlLists any

standards

associated with

this technology.

y Developer'sGuide

y ReleaseNotes

[projectName]_Change_Summary_Frag.xmlHigh level

description of

changes made to

this technology

since previous

release.

y ReleaseNotes


15/33


[projectName]_Compatibility_Summary_Frag.xml Lists protocol

changes, API,

exception and

schema changes

since previous

version.

y Developer'sGuide

y ReleaseNotes

[projectName]_Dependencies_Summary_Frag.xmlLists any other

GT projects and

third-party

software on

which this

project depends.

y Developer'sGuide

y ReleaseNotes

[projectName]_Feature_Summary_Frag.xmlLists new

features,

supported

features and

deprecated

features since

previous version.

y Developer'sGuide

y ReleaseNotes

[projectName]_Fixed_Bugs_Frag.xmlLists bugs fixed

since previous

release.

y QualityProfile

y ReleaseNotes

[projectName]_Interface_API_Frag.xmlDescribes API

programming and

provides links toAPI

documentation.

y Developer'sGuide

y PublicInterfaces

Guide

[projectName]_Interface_Commandline_Frag.xmlDocuments

commandline tools

for the

technology using

y Developer'sGuide

y Public


16/33


a specific

refentry format.Interfaces

Guide

y User'sGuide

[projectName]_Interface_Config_Frag.xmlDescribes and

provides details

about configuring

this technology.

y AdminGuide

y Developer'sGuide

y PublicInterfaces

Guide

[projectName]_Interface_Domain_Frag.xmlIdentifies the

domain-specific

interface data of

the project.

y Developer'sGuide

y PublicInterfaces

Guide

[projectName]_Interface_Env_Frag.xmlIdentifies the

interface toenvironmental

variables for this

project.

y Developer'sGuide

y PublicInterfaces

Guide

[projectName]_Interface_GUI_Frag.xmlDescribes any

Graphical User

Interface for the

technology.

y Developer'sGuide

y PublicInterfaces

Guide

y User'sGuide

[projectName]_Interface_WSDL_Frag.xmlDescribe any

WSDL protocols.

y Developer'sGuide


17/33


y PublicInterfaces

Guide

[projectName]_Known_Bugs_Frag.xml

(add releasenotes number for

clarity?) Lists

and links to

existing bugs at

the time of

release.

Embeddedin the

Known

Problems

Frag and

appears in:

y QualityProfile

y ReleaseNotes

[projectName]_Known_Problems_Frag.xmlHigh level

descriptions of

anylimitations

(followed bylist

of Known Bugs).

y ReleaseNotes

[projectName]_Migrating_GT2_Frag.xmlDescribes how to

migrate the

technology from

GT2 to current

release.

y MigratingGuide

[projectName]_Migrating_GT3_Frag.xmlDescribes how to

migrate thetechnology from

gt3 to current

release.

y MigratingGuide

[projectName]_Overview_Brief_Frag.xmlProvides a brief

overview of the

technology (1-2

y home pagey Release

Notes


18/33


sentences).

[projectName]_Platform_Summary_Frag.xmlSummarizes the

platforms on

which thistechnology has

been tested.

y Developer'sGuide

y ReleaseNotes

[projectName]_Resource_Properties_Summary_Frag.xmlLists and

describes

resource

properties for

this technology.

Embedded

in WSDL

Frag and

appears in:

y Developer'sGuide

y PublicInterface

Guide

[projectName]_Security_Considerations_Frag.xmlDescribes any

securityconsiderations

admin/dev should

know for this

technology.

y AdminGuide

y Developer'sGuide

[projectName]_Usage_Statistics_Frag.xml(optional) Only

for those

projects who can

publish usagestatistics.

Describes what

information is

published and

links to more

detailed

information,

including how to

y AdminGuide

y User'sGuide


19/33


opt-out.

,QFOXGLQJ7H[W

Table of Contents1. XIncludes

2. Replaceable Text

XIncludes are how we include information from other files (such as frags) into our documents. Text entities are

shortcuts that map to a value stored in one location.

;,QFOXGHV

If you are using the files as-is, you don't need to worry about xincludes. But if you want to break out your xml files

into more chunks or re-use your existing content in more places, read the following (more info can be found

here: http://www.sagehill.net/docbookxsl/ModularDoc.html ).

The following is an example of using XInclude to pull in the Overview Brief Frag:

ComponentOverview

Don't worry about the line starting with


20/33

y

y

For more information, see http://www.sagehill.net/docbookxsl/ModularDoc.html#XincludeSelect.

5HSODFHDEOH7H[W

Important

The following replaces text entities. This change was made in order to be more compatible with XMLMind

Personal Edition.

Replaceable text maps a 'nickname' to a string of text. We use them to refer to version numbers that will be

automatically updated from one place instead of having to manually update for each release.

To do this, we use the element with the role attribute set to entity:

For example:

version

y version - Maps to the current 3-digit version number (forexample, 4.2.0).

y shortversion - Maps to the current 2-digit version number(for example, 4.2).

y previousversion - Maps to the previous 2-digit versionnumber (for example, 4.0).

Important

The cannot be used in attributes - in other words, you cannot use this in a URL in a link. The

doc coordinator is currently working on another way to replace text in attributes.

3DUDJUDSKVSDUD!DQGVLPSDUD!

Table of Contents1. Brackets

Not surprisingly, the paragraph tag,, is the most used tag in our documentation. Not only can you use it

to separate your text into separate paragraphs, it may also contain block level structures (lists, figures, and so on).

But there is another, similar tag that is also used - . This tag also separates content into separate

paragraphs, however, it is more restrictive in that it can only contains text characters.


21/33

The main difference between them is there is more space between tags than tags.

Important

You also need or tags around text in the following

elements: , , , and .

For example, if you are using an itemizedlist, you need to write the code as follows:

your texthere

%UDFNHWV

Brackets (< and >) used within the flow of text (ie, within or elements) must be

represented in code as follows: the opening bracket is represented as< (short for "less than") and the closing

bracket is represented as > (short for "greater than".

+HDGLQJVDQG6HFWLRQV

Table of Contents1. id attribute2. tag3. Example

Headings are automatically created from elements directory following these DocBook elements:

y y y y y (in Commandline Frag)y (Sections nest recursively to make subsections - each section will correspond to a heading level in

the HTML/PDF output.)

Each of the abovementioned elements should also have theid attribute and be followed by a tag.

LGDWWULEXWH

The id attribute is standard and can be used with all elements. It comes in very handy when linking between

documents (more about this when talking aboutlinks). The value ofid must be unique throughout a book.

When it comes to creating unique ids for yours, please use the following naming convention:

[name of your project folder]-[shortname for doc]-[shortterm related to thissection]


22/33

For example, this would be a unique id for the "Introduction" section of the GridFTP System Administrator's

Guide: gridftp-admin-intro

WLWOH!WDJ

The opening tag is followed by the tag. The value of the tag is used as the link text

for olinks.

For example, the value of the tag for this section is "Headings and Sections", which is the heading above.

The level of the heading (h1, h2, etc) depends on how deeply the section is nested.

([DPSOH

For example, the topic you are reading right now looks like this in the DocBook XML file:

Headings and Sections ...

Inside this section, you can further nest tags, each with the same requirements: id attribute and

followed by the tag.

'RFXPHQWLQJ&RGHFRPSXWHURXWSXW!DQGILOHQDPH!

For displaying a snippet of code, a filename or anything else you just want to appear as a part of a sentence, we

normally use the or elements. They take the place of

the or HTML tags.

For bigger chunks of code, use the tag. Just wrap your code block in it, mono-spacing with indents,

and DocBook takes care of it automatically.Important

Brackets inside the tag must be represented in code: opening bracket is represented as< and

the closing bracket is represented as >.

/LQNV

Table of Contents1. Internal Linking ()

1.1. targetdoc2. External Linking ()

Linking falls into two different categories: internal linking within a version's documentation (ie, under

docs/4.2/4.2.0/) and any external links outside of that.

,QWHUQDO/LQNLQJROLQN!

Note

The 4.0 docs were set up differently; in those docs, you can only use this method of internal linking within the

same book (project).

When you want to control the link text, use the following format:


23/33

clickhere

and when you want to use an automatically generated link text, use the following format:

see

where:

y targetdoc refers to the doc id of the particular book you're linking to. To find the doc id, simply open theindex.xml file corresponding to the guide you want to reference and use the first id:.

See below for more information.

y targetptr refers to the specific id of the section you want to link to within a guide.Note

The empty olink element (2nd example) takes the value of the element of the section (chapter or

para tag) to which you are linking and uses that as the link text.

WDUJHWGRF

We've set up a convention where the id for the book = the targetdoc. So if we use gram4 as an example, the main

xml file for the developer's guide isexecution/gram4/developer/index.xml. If you opened that file now and

looked at the id attribute for the book element, it would say gram4Developer:

...

GTversion GRAM4:Developer's

Guide

...

The following is the naming convention. Note that thename = the folder name of the component; after the name

is the subdirectory for the book:

y nameAdminy nameDevelopery nameMigy namePIy nameQPy nameRNy nameUserException: The targetdoc id for the top-level installation guide is gtadmin.

([WHUQDO/LQNLQJXOLQN!

If you are linking outside of your version's documentation, use the tag:

Oracle Corporation


24/33

The output will create a hyper-link to Oracle in the HTML-version of the documentation:Oracle Corporation.

[also note use of &docpath; when you need to link to a non-DocBook file within documentation]

Important

Do NOT use ampersands in your hyper links. These are reserved for referencing entities; instead, use the

following code for ampersand:& .

*UDSKLFVILJXUH!

Note

Currently this section only takes HTML output into consideration - not a PDF version.

To insert a graphic we use the , , and elements. You should also

provide a brief description wrapped in - in HTML this will be the ALT text. If you want a caption to

appear below the graphic, use the element with a tag.

WebMDSInformationFlow

Thisis animage ofthe flowinWebMDS

Thisis animage ofthe flowinWebMDS

Note


25/33

The path to the graphic should be relative to the XML file you are editing.

The HTML output looks like this:

Figure 1. WebMDS Information Flow

This is an image of the flow in WebMDS

In addition to using the above code, do the following:

y In general, put your graphics in the same directory as the document.y Keep the width of the graphic no greater than 700px (500px is best)./LVWV

Table of Contents

1. How to make an unordered list () 2. How to make an ordered list ()3. How to make a definition list ()

In general, making a list in DocBook is similar to doing the same thing in HTML - except in

DocBook, becomes and the text in each must be wrapped in in either

a or element.

The following sections describe how to make the DocBook equivalent of the three usual HTML lists: unordered lists,

ordered lists and definition lists.

+RZWRPDNHDQXQRUGHUHGOLVWLWHPL]HGOLVW!

Stuff goeshere

More stuff goeshere


26/33

The HTML/PDF output looks like this:

y Stuff goes herey More stuff goes here+RZWRPDNHDQRUGHUHGOLVWRUGHUHGOLVW!

Stuff goeshere

More stuff goeshere


1. Stuff goes here2. More stuff goes here+RZWRPDNHDGHILQLWLRQOLVWYDULDEOHOLVW!

This kind of list is called a "variable list" in DocBook and is a little more complex than the previous lists. These are

the tags you'll need to make it happen:, , and :

Definitionterm goeshere

And definition/description goeshere


27/33

Another term goeshere

And more stuff goeshere


Definition term goes here

And definition/description goes here

Another term goes here

And more stuff goes here

Remember, each must be wrapped in in either a or element.

7DEOHVLQIRUPDOWDEOH!

DocBook supports several types of tables, but in most cases, the is enough:

header1

header2

header3


28/33

a1

b1

c1

a2

b2

c2

a3

b3

c3

The output is a simple HTML table:

header1 header2 header3

a1 b1 c1

a2 b2 c2

a3 b3 c3


29/33

If you want cells to span more than one row or column, it gets a bit more complicated - check out for

more information.

,WDOLFVDQG%ROGHPSKDVLV!

Our documentation uses two flavors of emphasis - italics and bold type. DocBook uses one -.

The tag defaults to italics when parsed. If you want to emphasize with bold type, use.

This little sentence uses just the tag.

This little sentence uses the tag.

&DOOLQJDWWHQWLRQWRWH[W

Table of Contents

1. 2. 3. 4. 5.

DocBook provides a few elements that can be very useful for calling attention to certain information by setting

them off from the text: , , , and .

FDXWLRQ!

The following are examples of each type (using the DocBook examples):

No User Servicable PartsInside

Breakingthisseal voids all warranties.

No User Servicable Parts Inside

Breaking this seal voids all warranties.

LPSRUWDQW!

No user-servicable partsinside.

Breakingthisseal voids all warranties.

Important


30/33

No user-servicable parts inside. Breaking this seal voids all warranties.

QRWH!

UpcomingChanges

Future versions ofthis feature maynotbe backward -compatible.

Consider implementingthe revised interface now.

Upcoming Changes

Future versions of this feature may not be backward-compatible. Consider implementing the revised interface

now.

WLS!

If youtie your shoelaces, you're lesslikelyto trip and fall down.

Tip

If you tie your shoelaces, you're less likely to trip and fall down.

ZDUQLQJ!

Striking your thumb with a hammer maycause severe pain and discomfort.

Warning

Striking your thumb with a hammer may cause severe pain and discomfort.

*ORVVDU\


31/33

The glossary for each version's release manuals is found online at [path to doc version]/glossary.html For example,

you can find this version's glossary page here: glossary.html.

Every project should make sure that any jargon or special terms appear in this list. To do so you need to add

some markup in two places:

1. glossary.xml - Located in the root folder of the documentation (for example, docs/4.2.0/glossary.xml) Thisfile acts as the centralized glossary database. Terms are added in tags that correspond to the

appropriate letter of the alphabet. For example, if you wanted to add the term "proxycertificate", you would

open glossary.xml, look for the P section and add the following markup in alpha

order with the other terms:

2. 3. proxycertificate4. 5. Ashortlived certificate issued using a EEC.Aproxy6. certificate typicallyhasthe same effective subject asthe EECthatissued it 7. and canthusbe used inits place.GSIuses proxycertificates for single sign 8. on and delegation of rightsto other entities.9. 10.

11.Next, within your project's documentation, add the tag to each instance you want that termlinked to the glossary:

proxycertificate

Important

If the term in your documentation varies at all from the value of in glossary.xml, you'll

need to add a baseform attribute that matches the value:

proxycertificates

12.Glossaries are added at the end of each book containing one or more glossary terms. When you commitchanges, if you see errors such as:


32/33

Warning: glossary.collectionspecified,butthere are 0 automatic glossaries

then an automatic glossary needs to be added to that book. Simply add the following right before the ending

book tag ():

A

Dummyterm

Thisis a dummy entry for the automatic glossary database.Do not edit.

The only thing you should update above is the id attribute. DocBook will handle the rest.

When using an automatic glossary database, there are problems with using the available (See)

and (See also) tags. Instead, if you want to refer to another glossary term within the database,

add something like this (using):

See also RLI.

where the text after the pound sign (#) is equal to the id attribute in the tag in glossary.xml.

,QGH[LQJ

Note

This is a very new feature in documentation and will probably not be fully implemented until final release of

4.2. The Documentation Coordinator will be sending emails to [email protected] this

subject.

You should mark up words in your documents that you would like to see show up in an index (which appears at

the end of a project's table of contents). We are working on using specialized indexes to consolidate certain

information (such as "how tos").


33/33

Use , and for this. See these links for an explanation.

7URXEOHVKRRWLQJ

TODO - need to show common XML (xmllint) and CVS errors and how to fix them

What are the most common errors people come across?