= Bytemark Symbiosis documentation guide
Patrick J. Cherry <patrick@bytemark.co.uk>

This document aims to list the standards to use whilst writing the
documentation.

== Naming conventions and style

This section covers way the documents should be written.

=== Name

The suite is called ``Bytemark Symbiosis'' or ``Symbiosis''.

=== Titles

All titles should be ``sentence case'', i.e. a capital letter at the
beginning, and no further capital letters other than those for proper
nouns.

========================================================================
 * Connecting from Microsoft Windows
 * Installing an email client
========================================================================

=== Internal Cross References

All parts, chapters, appendices, and sections should be given a unique
ID.  Each should be given a prefix which identifies what it is:

 * For parts, use +part-+,
 * chapters: +ch-+,
 * sections: +s-+,
 * appendices: +app-+.

It is important that we try and keep these predictable to ease putting in
cross-references.

========================================================================
e.g. A section called ``Completing foo'' might have an ID of
+s-completeingfoo+
========================================================================

== Layout and compilation

=== Toolchain

The documentation will be compiled into PDF and HTML forms.  To do
this you must have the following packages installed.

 * make
 * asciidoc
 * dblatex
 * xsltproc
 * libxml2-utils
 * rsync (for uploads) 

=== Make targets

To compile the documentation, there is a 'Makefile' in the top level
directory.  All the following commands should be run from that
directory.

There are intermediate build files generated in [directory]'build/'.
All the output ends up in [directory]'output/'.

`make all`::    To make all versions of the documentation.
`make pdf`::    To make just the PDF version, found at 'output/symbiosis.pdf'.
`make html`::   To make just the HTML version, found at 'output/symbiosis.html'.
`make xml`::    To make just the XML version, found at 'output/symbiosis.xml', and viewable with `yelp`.
`make clean`::  To clean up the build and output directories.
`make upload`:: To upload the documentation to symbiosis.bytemark.co.uk

=== Filenames

It has been decided to use a split configuration for writing the
documentation.  On compilation, the documents are ordered by filename,
and only documents with an extension of +txt+ will be included.  By
convention the files should start with a number, followed by a dash,
and then the ID of the first part, chapter, section, etc. they
contain, as described above.

If a file gets too big, it can be split into smaller chunks, preferably
around parts, chapters, sections, and appendices.  In this case directory
should be created, named after the part, chapter, &c, which it contains, and
the first file named after that same chapter.
+
========================================================================
e.g. A typical chapter and section layout might look like:

--------------------------------------
|- 10-ch-foo.txt
|- 20-ch-bar
|     |- 00-ch-bar.txt
|     \- 10-s-quux.txt
\- 30-ch-jam.txt
--------------------------------------

In this example, the top file +10-ch-foo.txt+ would contain:

--------------------------------------
[[ch-foo]]
== Foo

Some stuff..
--------------------------------------

Then +00-ch-bar.txt+ would contain:

--------------------------------------
[[ch-bar]]
== Bar

In this chapter ...
--------------------------------------

Then +10-s-quux.txt+ would contain:

--------------------------------------
[[s-quux]]
=== Quux

This section describes...
--------------------------------------

========================================================================

== Asciidoc tags

For help with Asciidoc, see http://www.methods.co.nz/asciidoc/chunked/index.html

It is important that we are consistent in our layout and formatting.

=== Parts and sections
The hierarchy should normally be part -> chapter -> section and so on.
Asciidoc uses prefixes of +=+ to determine what is what.  Throughout
our documentation the following is used:

[width="50%"]
|=========================================
| Part (top level)              | +=+
| Chapter                       | +==+
| Section                       | +===+
| Subsection                    | +====+
| Sub-subsection (bottom level) | +=====+
|=========================================

The previous example shows some chapter and section headings in
action.

=== Text formatting

See http://www.methods.co.nz/asciidoc/userguide.html#_text_formatting[the
Asciidoc documentation]

=== Procedures

When showing a series of steps to be followed, use the
procedure tag.  This has been specially defined for our use in
Asciidoc.  See "Connecting using WinSCP" in
txt/30-part-userguide/30-ch-connecting.txt for an example of its use.

=== Screenshots 

should be tagged with screenshot.  The image should be saved in
static/figures, but the reference in the text should just be figures/.
Again, see the above procedure for an example of how this works.  Note
in the above example, that there is an empty line with just a "+" on
it between procedure steps and screenshots.  This is important to get
the formatting correct.

=== Filenames

should be tagged with apostrophes.  For example:
   +'/srv/example.com/config/antispam'+

If the filename is a directory, you should additionally tag it with
[directory].  e.g.

     [directory]'/srv/example.com/mailboxes'

Other options (instead of directory) are:

 * devicefile (i.e. a file -- the default)
 * directory
 * extension
 * headerfile
 * libraryfile
 * partition
 * symlink

=== Applications (software)

These should be tagged with @ signs.  The appelation “application” is
usually reserved for larger software packages—WordPerfect, for
example, but not grep.  

================================================================================
  @MacFusion@ can be used to connect to your VM via ssh.

@MacFusion@ can be used to connect to your VM via ssh.
================================================================================

=== Graphical User Interfaces

When describing uses of buttons and labels in a GUI, you should
mark things up appropriately.  

================================================================================
     Click |Save| so you don't have to re enter these details every time
     you start `winscp`

Click |Save| so you don't have to re enter these details every
time you start `winscp`
================================================================================

In this case "Save" is a button in the gui, and "winscp" is the
command.  If you just want to point out something else in a GUI, i.e.
something other than a button, you can describe it as:

    [label]|Some label in the gui|

Other possibilities for this are

button::   The text on a button in a GUI (the default)
label::    The text of a label in a GUI
icon::     Graphic and/or text appearing as a icon in a GUI
menu::     The name of a menu in a GUI
menuitem:: The name of a terminal menu item in a GUI
submenu::  The name of a submenu in a GUI

=== Cross Reference

Adding chapter/section labels and referring back is important.  To add
a label to a chapter use a double set of square brackets.  E.g.

     [[ch-somethingimportant]]
     Something Important
     -------------------

Ideally this should be done before *every single*
part/chapter/section/subsection to allow easy referrals.  
   
Then later this "Something Important" chapter can be referred to as
follows:

     This is described in <<ch-somethingimportant>>.

That will be rendered as (where X is the real chapter number).

     This is described in Chapter X.

=== "Index Terms"

Adding index terms is also important.  This can be done by using three
sets of round brackets.  E.g.

     (((MacFusion,connecting to your server)))

Please try and use this as often as possible, so we get a good
index!

=== Glossary terms

There is also a glossary available to describe technical terms.  To
add a new glossary term, the format is as follows:

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
[[TLA]]
[glossentry]
.Three Letter Acronym, TLA
=====================================================================
This is a common acronym used ironically to illustrate when too many
acronyms are being used.
=====================================================================
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Note that the reference inside the double-square-brackets is the same
as the abbreviation.  Now to reference this in the text, the following
format is used:

  glossaryterm:TLA[]

Which will get simply presented as "TLA", with a link to the glossary.
If you wish to use other text as the link, then write

  glossaryterm:TLA[Three Letter Acronym]

The XML will not validate properly if a glossaryterm does not exist in
the glossary that is referenced in the text.

