Chapter 1. User doc conventions

1.1. Command-lines
1.2. Java
1.3. XML
1.4. Tips, notes, cautions, warnings
1.5. New or important terms

This page describes the common conventions used throughout the OGSA-DAI documentation.

1.1. Command-lines

Commands to be executed at the command-line, arguments and values are all shown in this teletype font.

Longer excerpts are shown as follows:

$ run-this-command

The character $ is used to denote a command or shell prompt.

The back-slash (reverse solidus) character (\) is used to denote a line continuation character. When typing in commands this should not be entered, i.e.:

$ this-is-a-command that is very long so requires use of a line continuation character to make it look better on the page

would be presented as follows

$ this-is-a-command that is very long so requires use of a \ 
                    line continuation character to make it \
                    look better on the page 

We use the Unix convention for setting and dereferencing environment variables as well as using the same for directory delimiters, e.g.

$ export MY_PATH=/home/mydir/mypath
$ export MY_PATH=myOtherDir/mypath:$MY_PATH
$ echo $MY_PATH

Windows users should use the corresponding DOS equivalents, e.g. the Windows equivalent of the above might be:

$ set MY_PATH=C:\home\mydir\mypath
$ set MY_PATH=myOtherDir\mypath;%MY_PATH%
$ echo %MY_PATH%

1.2. Java

Java classes, interfaces, methods, variables and packages are all shown in this teletype font

Longer excerpts are shown as follows:

public class SomeClass
{

...

}

1.3. XML

XML elements and attributes are all shown in this teletype font.

Longer excerpts are shown as follows:

<someElement someAttribute="someValue">
  <someSubElement>
    someContent
  </someSubElement>
</someElement>

1.4. Tips, notes, cautions, warnings

[Tip]Tip
Useful tips are shown like this!

[Note]Note
General notes and information about limitations are shown like this!

[Caution]Caution
Things we recommend you exercise caution over are shown like this!

[Warning]Warning
Things that can go wrong if you do not pay attention are shown like this!

1.5. New or important terms

New or important terms are emphasised.