Document Formatting Standards and Tools

Please note: This documentation is for OSG 1.2. While we still provide critical security updates for OSG Software 1.2, we recommend you use OSG Software 3 for any new or updated installations. We are considering May 31, 2013 as possible OSG 1.2 End of Life (EOL).

ReleaseDocumentation
DocFormattingRules
Review Passed
by TedHesselroth
Released
by JamesWeichel

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.

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:

%STARTINCLUDE%
<your text to be included somewhere else here>
%STOPINCLUDE%

To re-use the text elsewhere use:

%INCLUDE{"<Web>/<PageName>"}%

  • 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 DocInstallTemplate) 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">
<code>%UCL_PROMPT_SHORT% /bin/date --help</code>
</pre>

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:

$> $VDT_LOCATION/vdt/setup/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-host gums.fnal.gov \
--gums-port 8443 \
--enable-gateway

The example above can be rendered in the following way:

<pre class="screen">
<code>%UCL_PROMPT_SHORT% $VDT_LOCATION/vdt/setup/configure_bestman \</br>
--server y \</br>
--user daemon \</br>
--cert /etc/grid-security/bestman_cert/bestmancert.pem \</br>
--key /etc/grid-security/bestman_cert/bestmankey.pem \</br>
--with-allowed-paths /cache \</br>
--gums-host gums.fnal.gov \</br>
--gums-port 8443 \</br>
%RED%--enable-gateway%ENDCOLOR%</code>
</pre>

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

ALERT! WARNING!
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
1282075042

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

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

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
</pre>

%TWISTY{%TWISTY_OPTS_OUTPUT%}%
<pre class="screen">
%UCL_PROMPT% /bin/date --help
... many more lines of output ...
</pre>
%ENDWTISTY%

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
1282075042

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%
%RED%1282075042%ENDCOLOR%
</pre>

HELP NOTE
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 opensciencegrid.org
%UCL_HOST_FQDN% full hostname client.opensciencegrid.org
%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
-->

ALERT! WARNING!
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!

HELP NOTE
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
</pre>

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
</pre>

HELP NOTE
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

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

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

Importants

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

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

Warnings

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

ALERT! WARNING!
If ignore me, you'll regret it.

Tips

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

HELP TIP
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_BESTMAN_GATEWAY% BeStMan-Gatway
%LINK_CERTS% Certificates
%LINK_CMP% Content Management Project
%LINK_DOC_AREA% Document Area
%LINK_DOC_ROLE% Document Role
%LINK_DOC_TYPE% Document Type
%LINK_GLOBUS_TOOLKIT% Globus Toolkit
%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_PACMAN% Pacman
%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% Glossary
%LINK_GLOSSARY_CA% Certificate Authority
%LINK_GLOSSARY_CE% Compute Element
%LINK_GLOSSARY_CONDOR% HTCondor
%LINK_GLOSSARY_CRL% Certificate Revocation List
%LINK_GLOSSARY_DN% Distinguished Name
%LINK_GLOSSARY_FT% Factory Type
%LINK_GLOSSARY_GATEKEEPER% Gatekeeper
%LINK_GLOSSARY_GIP% Generic Information Provider
%LINK_GLOSSARY_GRAM% GRAM
%LINK_GLOSSARY_GRAM_WS% GRAM-WS
%LINK_GLOSSARY_GRIDFTP% GridFTP
%LINK_GLOSSARY_GRID_PROXY% Grid Proxy
%LINK_GLOSSARY_GUMS% GUMS
%LINK_GLOSSARY_ITB% Integration Testbed
%LINK_GLOSSARY_JM% Job Manager
%LINK_GLOSSARY_PACMAN% Pacman
%LINK_GLOSSARY_PACMAN_CACHE% Pacman Cache
%LINK_GLOSSARY_SE% Storage Element
%LINK_GLOSSARY_SRM% Storage Resource Manager
%LINK_GLOSSARY_VDT% Virtual Data Toolkit
%LINK_GLOSSARY_VO% Virtual Organization
%LINK_GLOSSARY_VOMS_PROXY% VOMS Proxy
%LINK_GLOSSARY_WN% Worker Node

HELP NOTE
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:

%HELP_GRID_PROXY_INFO%

%HELP_GRID_PROXY_INIT%

%HELP_VOMS_PROXY_INFO%

%HELP_VOMS_PROXY_INIT%

%HELP_GLOBUSRUN%

%HELP_GLOBUSRUN_WS%

%HELP_GLOBUS_JOB_RUN%

%HELP_GLOBUS_URL_COPY%

ALERT! WARNING!
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.

Comments

A comment section (like the one below) should be added at the bottom of each page using a code like:
---++ Comments
%COMMENT{type="tableappend"}%

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

Comments

-- JamesWeichel - 27 Jan 2010

Topic revision: r27 - 15 Feb 2012 - 21:00:08 - KyleGross
Hello, TWikiGuest
Register

Introduction

Installation and Update Tools

Clients

Compute Element

Storage Element

Other Site Services

VO Management

Software and Caches

Central OSG Services

Additional Information

Community
linkedin-favicon_v3.icoLinkedIn
FaceBook_32x32.png Facebook
campfire-logo.jpgChat
 
TWIKI.NET

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