Document Formatting Standards and Tools

About This Document

hand This document is intended for those people who write, edit, or review documents in the official OSG documentation TWiki. It describes the formatting standards, methods used to structure composite documents, and formatting tools that automatically format certain types of information.

General TWiki formatting information

  • A description of the TWiki concepts for controlling formatting, creating lists, creating tables, etc. can be found in TextFormattingRules.
  • All the "rules" that follow should be used in most cases, but always use your best judgment.

Rules for topics and section headings

  • All topics have a bold heading at Level 1 (---+ *Title*) and first letters of words are capitalized (eg. Rules For Formatting Documents).
  • The level one heading is taken as its twiki topic name, separated into words (e.g., MyTopic becomes My Topic). Choose the twiki name carefully! If you want to spell out a title whose TWiki name has abbreviations, do that.
  • All level two sections should be in title case. Eg: ---++ Details on the Installation
  • All sections (level three and below) have the first word capitalized, the rest lower case. Eg: ---+++ Details on the installation (except for proper nouns)
  • To prevent the Table of Contents from becoming too long and confusing, exclude from the TOC detailed sections (typically level three or four) and below. To accomplish this, use %TOC{depth="2"}% or %TOC{depth="3"}% to produce the table of contents.

Documentation Standards

The following is a list of standards adopted for official documentation:
Item Standard Example
Document Location General documents that have no (or almost no) Release dependencies and apply to the current; and, most likely, all future releases should be put in the Documentation Web. Those that are release dependent belong in the corresponding Release sub Web under the Documentation Web. Documentation.StorageOverview, Documentation.GridUsersGuide, Documentation/Release3.InstallOSGClient, Documentation/Release3.LocalStorageConfiguration
Document Name All documents should use Wiki words as names (2 or more capitalized words, concatenated WikiWord
Document Parent Unless there is a particular hierarchy, documents should use WebHome as their parent. Some documents (e.g. technology description documents) may use the appropriate Navigation page as parent CertificateGetWeb's parent is NavUserJoin or Trash.ReleaseDocumentationBestmanGateway parent is Documentation/Release3.BestmanOverview
Document Reference Documents should always be referenced with Webname.DocumentName (or simply DocumentName if in the same web). If a url is copied, remember to change Webname/DocumentName to Webname.DocumentName. Trash.ReleaseDocumentationDocHowTo or Documentation/Release3.ReleaseNotes
Document Includes Items common to many documents should be done with includes. Install documents use
%INCLUDE{"YumRepositories" section="OSGRepoBrief"}%
%INCLUDE{"InstallCertAuth" section="OSGBriefCaCerts"}%

Install Document Standards (Also see DocInstallTemplate)

Requirements Section

The Requirements are broken into these subsections (at the appropriate level) with the following formatting.
Host and OS

  • A host to install the RSV Service (Can be the CE or a separate, standalone computer)
  • OS is Red Hat Enterprise Linux 6, 7, and variants (see details...).
  • Root access


The RSV installation will create two users unless they are already created.

User Comment
rsv Runs the RSV tests. The RSV certificate (below) will need to be owned by this user.
cndrcron Runs the HTCondor Cron processes to schedule the running of the tests.


Certificate User that owns certificate Path to certificate
RSV service certificate rsv /etc/grid-security/rsv/rsvcert.pem


The Networking table should is defined in the FirewallInformation document. To include relevant information in an install document, use:

%INCLUDE{"FirewallInformation" section="FirewallTable" lines="comma_separated_list"}%
All the predefined lines are: 

You can add custom lines using a backslash "\" after the include and adding your lines (remember the 2 "space" on each side to center the cell), e.g.:
%INCLUDE{"Documentation/Release3.FirewallInformation" section="FirewallTable" lines="gram,portrange"}% \
| HTTP |  tcp  |  80  |  %ICON{choice-yes}%  | | My custom HTTP server with special explanation |
will produce an output (table and line) like this:

For more details on overall Firewall configuration, please see our Firewall documentation.

Service Name Protocol Port Number Inbound Outbound Comment
GRAM tcp 2119 Y    
GRAM callback tcp GLOBUS_TCP_PORT_RANGE Y   contiguous range of ports
HTTP tcp 80 choice-yes   My custom HTTP server with special explanation

Additional Requirements
Can be added if needed

Services Startup/Shutdown

This is a partial example to show what is included and the formatting. This goes after the Configuration section of Install documents. See also DocInstallTemplate


This is a partial example to show what is included and the formatting.
Services brief description

Starting and Enabling Services

To start VOMS you need to start several services:

  1. Start voms server
    [root@client ~]$ service voms start

You should also enable the appropriate services so that they are automatically started when your system is powered on:

  • To enable the other services:
    [root@client ~]$ /sbin/chkconfig voms on

Stopping and Disabling Services

To stop VOMS you need to stop voms,... , and also the services they use if nothing else is using them:

  1. Stop voms server
    [root@client ~]$ service voms stop

In addition, you can disable services by running the following commands. However, you don't need to do this normally.

  • To disable the other services:
    [root@client ~]$ /sbin/chkconfig voms off

Useful Configuration and Log Files

In the troubleshooting section of each Install Document, the file locations should be specified as follows:
Service/Process Configuration File Description
Service1 /etc/Service1.cfg Configuration information for this service
Service2 /etc/Service2.cfg Configuration information for this service

Service/Process Log File Description
Service1 /var/log/service.log Records all service errors
  /var/log/service1b.log Records all service updates
Service2 /var/log/service2.log Records all service errors

Release Variables

A set of standard variables are provided so that items that may change with each release of software are automatically updated in the documentation. You should use the variables any time you want to refer to the corresponding item rather than the verbatim numbers or text. The variables are set in the WebPreferences TWiki page.

  • OSG release variable: %OSG_VERSION% = 3.x
  • OSG grid: %OSG_GRID% = 3.x
  • Supported OS: %SUPPORTED_OS% = Red Hat Enterprise Linux 6, 7, and variants (see details...)
  • ITB Version: %ITB_VERSION% = 3.0
  • Release Status: %RELSTATUS% = Not Released
  • OSG Release: %OSG_RELEASE% = OSG

Compose Documents using Includes

Twiki provides the possibility to re-use already written text on several documents. There exist two different ways to mark text on a page to be included on other pages:

  1. by defining includes
  2. by defining sections

About Includes

Includes are less flexible than sections and should be avoided! It is only possible to define one include per page and it is not possible to hand over variables or dynamically shift the table of contents for the included text. To mark written text and make it available to be included elsewhere use:

<your text to be included somewhere else here>

To re-use the text elsewhere use:


  • DocExampleMainTopic for a main topic not likely to be used with STARTINCLUDE/STOPINCLUDE so as to be included in other topics.
  • Wherever possible TWiki editing should be used rather than raw HTML.
  • Here is the WebTopicEditTemplate (now ReleaseDocumentationDocInstallTemplate) for newly created pages in this twiki. Once you create the new page, any other template (or content of your choice) can be pasted into the new page.

About Sections

Sections provide a greater flexibility than includes. It is possible to define more than one section per page and each section may be handed variables to be used. To mark written text and make it available to be included elsewhere use:

%STARTSECTION{"<name of the section>"}%
<your text to be included somewhere else here>
%ENDSECTION{"<name of the section>"}%

To re-use the text elsewhere use:

%INCLUDE{"<Web>/<PageName>" section="<name of the section>"}%

Adjusting Heading Level for Sections

Text marked to be included on a page utilizing an include or a section will be displayed just as written. In particular the level of headings remain to be fixed. It is however desirable to shift the included sections according to the current table of contents. This can be achieved using sections in the following way:

%STARTSECTION{"<name of the section>"}%
---%SHIFT%+ My Level 1 Heading in this Section
%ENDSECTION{"<name of the section>"}%

To re-use the text elsewhere and not shift the heading use:

%INCLUDE{"<Web>/<PageName>" section="<name of the section>"}%

To shift the heading by one level use:

%INCLUDE{"<Web>/<PageName>" section="<name of the section>" TOC_SHIFT="+"}%

Formatting Tools

The following sections describe tools available to easily format certain information to make it consistently recognizable and useful to the reader.

Presenting the Unix Command Line

Some technical documents may require the presentation of the Unix command line. A non-complete lists of reasons may be:

  • to show a command and its arguments that the reader can copy-and-paste to his own command line
  • to show the output of commands executed on the command line
  • to show a series of steps on the command line as part of a procedure

It is desirable to use a common format for the presentation of the command line on every document so the user easily recognizes the presentation as such.

Single Command Line

The following example illustrates the presentation of a single command line that the reader may copy-and-paste to his own command line:

$> /bin/date --help

Here is the Twiki code used to render the command line:

<pre class="screen">
%UCL_PROMPT_SHORT% /bin/date --help</code>

Multiline Command Line

A Unix command and its arguments can grow to considerable size. This makes it difficult to display the entire command line without scrolling. One solution is to break down the command line while maintaining copy-and-paste functionality:

$> configure_bestman
--server y
--user daemon
--cert /etc/grid-security/bestman_cert/bestmancert.pem
--key /etc/grid-security/bestman_cert/bestmankey.pem
--with-allowed-paths /cache
--gums-port 8443

The example above can be rendered in the following way:

<pre class="screen">
%UCL_PROMPT_SHORT% configure_bestman
--server y
--user daemon
--cert /etc/grid-security/bestman_cert/bestmancert.pem
--key /etc/grid-security/bestman_cert/bestmankey.pem
--with-allowed-paths /cache
--gums-port 8443

By using the html </code> tag it is possible to use all text formatting tools while maintaining copy-and-paste functionality.

Please make sure to end lines without additional white spaces after </br>. Otherwise copy-and-paste will not work!

Command Line and Output

By showing the complete prompt and output of a command line you virtually enable the reader to 'look over your shoulder'. By comparing his own results on the command line and the output presented as part of the documentation he will more likely detect errors during the execution of the command.

[user@client ~]$ /bin/date +%s

Again the Twiki code used to render the command line is simply:

<pre class="screen">
%UCL_PROMPT% /bin/date +%s

Notice how the Twiki Variable %UCL_PROMPT% is used to render a complete prompt such as used by the Bash Shell.

Output generated by the Unix command line can become quiet long. In order to maintain a good readability of the document long output should be hidden, but accessible to the user. For that purpose we will use the Twisty Plugin. The Twisty Plugin generates JavaScript code that collapses text into clickable links:

[user@client ~]$ /bin/date --help
Usage: /bin/date [OPTION]... [+FORMAT]
  or:  /bin/date [-u|--utc|--universal] [MMDDhhmm[[CC]YY][.ss]]
Display the current time in the given FORMAT, or set the system date.

[user@client ~]$ /bin/date --help
Usage: /bin/date [OPTION]... [+FORMAT]
  or:  /bin/date [-u|--utc|--universal] [MMDDhhmm[[CC]YY][.ss]]
Display the current time in the given FORMAT, or set the system date.

  -d, --date=STRING         display time described by STRING, not `now'
  -f, --file=DATEFILE       like --date once for each line of DATEFILE
  -r, --reference=FILE      display the last modification time of FILE
  -R, --rfc-2822            output date and time in RFC 2822 format
      --rfc-3339=TIMESPEC   output date and time in RFC 3339 format.
                            TIMESPEC=`date', `seconds', or `ns' for
                            date and time to the indicated precision.
  -s, --set=STRING          set time described by STRING
  -u, --utc, --universal    print or set Coordinated Universal Time
      --help     display this help and exit
      --version  output version information and exit

FORMAT controls the output.  The only valid option for the second form
specifies Coordinated Universal Time.  Interpreted sequences are:

  %%   a literal %
  %a   locale's abbreviated weekday name (e.g., Sun)
  %A   locale's full weekday name (e.g., Sunday)
  %b   locale's abbreviated month name (e.g., Jan)
  %B   locale's full month name (e.g., January)
  %c   locale's date and time (e.g., Thu Mar  3 23:05:25 2005)
  %C   century; like %Y, except omit last two digits (e.g., 21)
  %d   day of month (e.g, 01)
  %D   date; same as %m/%d/%y
  %e   day of month, space padded; same as %_d
  %F   full date; same as %Y-%m-%d
  %g   last two digits of year of ISO week number (see %G)
  %G   year of ISO week number (see %V); normally useful only with %V
  %h   same as %b
  %H   hour (00..23)
  %I   hour (01..12)
  %j   day of year (001..366)
  %k   hour ( 0..23)
  %l   hour ( 1..12)
  %m   month (01..12)
  %M   minute (00..59)
  %n   a newline
  %N   nanoseconds (000000000..999999999)
  %p   locale's equivalent of either AM or PM; blank if not known
  %P   like %p, but lower case
  %r   locale's 12-hour clock time (e.g., 11:11:04 PM)
  %R   24-hour hour and minute; same as %H:%M
  %s   seconds since 1970-01-01 00:00:00 UTC
  %S   second (00..60)
  %t   a tab
  %T   time; same as %H:%M:%S
  %u   day of week (1..7); 1 is Monday
  %U   week number of year, with Sunday as first day of week (00..53)
  %V   ISO week number, with Monday as first day of week (01..53)
  %w   day of week (0..6); 0 is Sunday
  %W   week number of year, with Monday as first day of week (00..53)
  %x   locale's date representation (e.g., 12/31/99)
  %X   locale's time representation (e.g., 23:13:48)
  %y   last two digits of year (00..99)
  %Y   year
  %z   +hhmm numeric timezone (e.g., -0400)
  %:z  +hh:mm numeric timezone (e.g., -04:00)
  %::z  +hh:mm:ss numeric time zone (e.g., -04:00:00)
  %:::z  numeric time zone with : to necessary precision (e.g., -04, +05:30)
  %Z   alphabetic time zone abbreviation (e.g., EDT)

By default, date pads numeric fields with zeroes.
The following optional flags may follow `%':

  - (hyphen) do not pad the field
  _ (underscore) pad with spaces
  0 (zero) pad with zeros
  ^ use upper case if possible
  # use opposite case if possible

After any flags comes an optional field width, as a decimal number;
then an optional modifier, which is either
E to use the locale's alternate representations if available, or
O to use the locale's alternate numeric symbols if available.

Report bugs to .

This is the skeleton of the Twiki code that is used to render the output above:

<pre class="screen">
%UCL_PROMPT% /bin/date --help
Usage: /bin/date [OPTION]... [+FORMAT]
  or:  /bin/date [-u|--utc|--universal] [MMDDhhmm[[CC]YY][.ss]]
Display the current time in the given FORMAT, or set the system date.

<pre class="screen">
%UCL_PROMPT% /bin/date --help
... all the lines of output rather than just the first 3 lines ...

Here a couple of tips about TWISTY. Note that the result of a TWISTY section may be affected by several elements and may affect the whole page:
  • If you want a twisty section to be aligned with the item in the list put the twisty header on the same line of the text and the endtwisty on the same line where you end the content
    something like here <br> %TWISTY{%TWISTY_OPTS_OUTPUT% showlink="click to see how I did"}% <pre class="screen">
    All your lines
    </pre> %ENDTWISTY%
  • If the whole page layout is confused (menus, doctable, ...), probably you put endtwisty on a new line
  • If you want the twisty message on the same line of a sentence then leave no empty line before the paragraph (after the title or the items before). <br> tags are OK but empty lines change the layout. This may be browser dependent but is true at least in Chrome and Firefox. E.g. see the following 2 paragraph that share practically the same code
Paragraph one, no empty line before it and
This worked

Paragraph two, with empty line before it and

Not really - this did not work

Highlighting Command Line Options

Color can be used to highlight the command line options that are currently being discussed. It can also be used to visually tie a command line option to its expected output:

[user@client ~]$ /bin/date +%s

This may not be very useful for /bin/date used in the example above. It becomes useful for long outputs where the color can be used to help the reader find the important parts of the output. See here.

Again the Twiki code used to render the command line is simply:

<pre class="screen">
%UCL_PROMPT% /bin/date %RED%+%s%ENDCOLOR%

See the complete list of color definitions available here.

Important Twiki Variables

A number of Twiki Variables are used to control the rendering of the Unix Command Line:

Variable Description Default Value
%UCL_USER% username or login displayed by UCL_PROMPT user
%UCL_CWD% current working directory displayed by UCL_PROMPT ~
%UCL_HOST% hostname displayed by UCL_PROMPT client
%UCL_DOMAIN% domain name
%UCL_HOST_FQDN% full hostname
%UCL_PROMPT% the full prompt to be displayed [user@client ~]$
%UCL_PROMPT_ROOT% the full prompt to be displayed for the root user [root@client ~]$
%UCL_PROMPT_SHORT% a short prompt to be displayed $>

It is possible to change the display of the prompt by locally changing the definition of the variables on the document:

<!-- my local variable definitions used on this document only
    * Local UCL_USER = griduser
    * Local UCL_HOST = se

The * has to be preceded by exactly 3 white spaces! Unlike one would expect, it is not possible to define a local variable more than once on a document. Twiki will only use the last definition of the variable on the entire document!

It is often convenient to copy-and-paste the command line output into a text editor first and to find-and-replace pieces of text such as the prompt. Surprisingly this basic functionality is not supported by the online editor currently in use.

Root Command Line

It is often desirable to highlight that the current command line requires root privileges. Using the CSS class rootscreen instead of screen changes the background of the enclosing box to red which makes it more recognizable. By using the %UCL_PROMPT_ROOT% instead of %UCL_PROMPT% the prompt will be displayed using the root user rather than the user specified by %UCL_USER%

[root@client ~]$ mount -t xfs /dev/sdb1 /ecache

Here is the Twiki code used to render the command line:

<pre class="rootscreen">
%UCL_PROMPT_ROOT% mount -t xfs /dev/sdb1 /ecache

Presenting File Content

Technical documents frequently refer to files. It may be necessary to display the content of a file as part of the documentation. A non-complete list of reasons may be:

  • to display the content of a configuration file that has to be adjusted
  • to display parts of a log or output file for illustrative purposes

For this purpose the file class from the CSS definitions of the Twiki can be used:

line 1
line 2

The Twiki code to render the box above is simply:

<pre class="file">
line 1
line 2

If the lines in the file contain html or TWiki variables, you will have to use the verbatim tag (enclosed in <>) to prevent them from being interpreted.


Notes are asides about the contents of the text that provide specific information that particular, but not all, users may need. Notes are less necessary than Importants and unlike Warnings, may not cause harm if ignored.

  • Usage
    To create a note, insert the %NOTE% variable, followed by a single space and your text:
     %NOTE% Here is my note text. 
  • Example

Something that I want you to know about and pay some attention to.


Importants are asides from your normal text that you want to highlight so that skimming users will not ignore them. Unlike Warnings, they will not cause grave harm to the system or the person if ignored. The difference between a Note and an Important is up to the writer.
  • Usage
    Importants are included by putting, on a new line, %IMPORTANT% followed by a single space and your important text:
     %IMPORTANT% Some text about the important thing. 
  • Example

Don't forget to include a single space or the Important will not work.


Warnings are set off from the regular flow of the text to especially warn the reader about an action that could cause harm to the system or to the user. It's less than something that should be labeled DANGER but more harmful than something that you would put into an Important.

If something that you are instructing a user to do could take up the CPU for several minutes, you should put in a Warning.

  • Usage
    Warnings are added by putting, on a new line, %WARNING% followed by a single space and your text.
     %WARNING% Some text here. 
  • Example

If ignore me, you'll regret it.


Tips might be used to suggest an alternative that would be better under certain circumstances.
  • Usage
    Tips are added by putting, on a new line, %TIP% followed by a single space and your text.
     %TIP% Some text here. 
  • Example

It is really best if you do it this way.

Frequently Used Links

For a number of links the Content Management Project created Twiki variables defining the links:

Variable Example
%LINK_BESTMAN% Berkeley Storage Manager (BeStMan)
%LINK_CERTS% Certificates
%LINK_CMP% Content Management Project
%LINK_DOC_AREA% Document Area
%LINK_DOC_ROLE% Document Role
%LINK_DOC_TYPE% Document Type
%LINK_GOC_OPEN_TICKET% Grid Operation Center
%LINK_IGTF% International Grid Trust Federation
%LINK_OIM% OSG Information Management System
%LINK_OSG% Open Science Grid
%LINK_VDT% Virtual Data Toolkit
%LINK_XROOTD% xrootd

Quick Links to Glossary Pages

Technical documents use their own vocabulary which may be unfamiliar to some readers making it more difficult for them to understand the content. The Glossary defines the OSG specific vocabulary in a central place from where definitions can be linked into the text where they are used. We recommend to link to a Glossary definition when:

  • a term or acronym is first used on a page
  • a term or acronym is used on the page and a previous link to its Glossary definition is out of sight to the reader

In order to make this as easy as possible, the content management project provides variable definitions that quickly create links to the definition of terms within the Glossary:

Variable Example
%LINK_GLOSSARY_CA% Certificate Authority
%LINK_GLOSSARY_CE% Compute Element
%LINK_GLOSSARY_CRL% Certificate Revocation List
%LINK_GLOSSARY_DN% Distinguished Name
%LINK_GLOSSARY_GIP% Generic Information Provider
%LINK_GLOSSARY_ITB% Trash/Trash/Integration Testbed
%LINK_GLOSSARY_SE% Storage Element
%LINK_GLOSSARY_SRM% Storage Resource Manager
%LINK_GLOSSARY_VDT% Virtual Data Toolkit
%LINK_GLOSSARY_VO% Virtual Organization

Besides being easier to memorize the quick links above serve another important reason. They enable editors to maintain definitions of OSG vocabulary in one place. Once a definition gets refined in the Glossary it is going to be up-to-date on every page using the term!

Quick Man Pages

Documentation on software and procedures often refers to tools being used on the Unix command line. It is desirable to provide a manual page for the tool to the reader within the text without cluttering its description. The Twisty plugin provides this functionality. We have created Twiki variables that can be used for that purpose. To render a man page for grid-proxy-info use %HELP_GRID_PROXY_INFO%. Other supported definitions include:









The quick man pages currently do not render correctly in Safari and Chrome. The use should be avoided till further notice from the Content Management Project.


A comment section (like the one below) should be added at the bottom of each page using a code like:
---++ Comments

Comments made during document review/testing should be addressed by the owner and removed prior to release.


-- JamesWeichel - 27 Jan 2010

Topic revision: r27 - 07 Feb 2017 - 20:07:19 - BrianBockelman
Hello, TWikiGuest!


TWiki | Report Bugs | Privacy Policy

This site is powered by the TWiki collaboration platformCopyright by the contributing authors. All material on this collaboration platform is the property of the contributing authors..