Introduction

The purpose of this document is to outline the documentation style to adopt when adding to or extending LaTeX documents. It assumes that there already exists a prior knowledge of LaTeX.

These general guidelines should be adhered to when creating all LaTeX documents to achieve consistency throughout all documents. The purpose of these guidelines is to create consistency throughout all documents created in the CMISS group.

Creating New Documents

Starting a Document

• The standard Latex_make file can be located in the directory ~cmiss/latex/. This should be copied to the directory of the current document an modified appropriately to compile new LaTeX documents.
• Various template documents can be located in the files ~cmiss/latex/shell_*.tex
• A sample paper can be located in the directory ~cmiss/documents/papers/coupledpaper/
• Latex tools (e.g.,macros.tex) can be found in the ~cmiss/latex/ directory.

There are three files containing predefined macros which have been written by the CMISS group. These three files should be included into your latex document. In order to keep up to date with any changes occuring to these files you should not take a local copy and include that. You can reference the files directly from the ~cmiss/latex/ directory or you can create a soft link from a local file to the global files. The three files are:

1. abbreviations.tex
2. acronyms.tex
3. macros.tex

In addition to this there is a file defns.tex which is in the same directory. This should also be included. It contains standard margin settings, paper size, packages etc.

NOTE It is important to use these predefined commands whenever possible.

Document Styles

The structure and layout definitions are stored in the style files located in the directory ~cmiss/latex. These files usually have the extension *.sty. LaTeX is distributed with standard document classes,

articles

are intended for short documents for publication. The title page will appear on the top of the first page and contains no chapters. A shell document can be located at ~cmiss/latex/shell_article.tex

reports

are intended for longer technical documents. The title page will appear on a page of its own. A shell document can be located at ~cmiss/latex/shell_report.tex

books

are intended as a basis for book publication. Page layout is adjusted assuming that the output will eventually be used to print on both sides of the paper.A shell document can be located at ~cmiss/latex/shell_book.tex

letters

are inteded for producing personal letters. A shell document can be located at ~cmiss/latex/shell_letter.tex

Directory & File Structure

• When dealing with large documents with multiple chapters, directories should be created for each chapter
• Macros used for LaTeX documents are located in the directory ~cmiss/latex/macros.tex

Style Conventions

English Style

• Computer code should be enter under the environment of \compcode in order to distinguish it from the rest of the text. This will produce output of the form text.
• Common ions can be generated using predefined macros. e.g.,using \ionbicarbonate will produce output of the form . A more extensive list can be located in the macros.tex file.
• Section headings should contain capital letters for the first letter of key words and lower case for all others. Subsections and any subsequent section below should only be capitalised on the first letter.
• Colloquialisms are denoted using \colloq{text} to produce output of the form `text'.

Maths Style

• All numbers are to be entered in math font.
• Numbers located within text and less than 20 should be written out fully. e.g.,four, ten, twelve.
• When a suffix for denoting the order of numbers such as `th' is required, use the pre-defined macro for `th's, \nth{i}, which produces an output of the form .
• When denoting the dimension, a hyphen should always be placed between the number and `dimension', e.g.,three-dimensional.
• Numbers with units should be generated using the predefined macro of the form \nunit{5}{\mps}. This will produce the output appearing as . For a more extensive list of units refer to the latex macro file located in the directory: ~cmiss/latex/macros.tex.
• If a range of value is be required use the macro of the form \nrunit{5}{7}{\mps} producing output appearing as .
• Integral symbols are created using the predefined macro of \gint{w}{x}{y}{z} which produces output of the form or for evaluating integrals use \evalat{x}{y} to create output of the form .
• Derivative symbols are created in a similar fashion using the macro of the form \dby{x}{y} to produce output of the form .
• Many other forms of macros are created for producing mathematical symbols. These can be located in the file macros.tex.

Referencing

The standard file for bibliography references are located in the directory
~cmiss/documents/references/references.bib.

Texts are cited using the last name of the first author of the book, a colon, followed by the year published. If there are multiple publications in a year, then a letter (e.g.,b, c) is added to the year of publication. How this system works is that the when your document is compiled, the references section will automatically be generated from the articles you have cited. If you want to have a reference in your document which is not cited in the main body of the text the \nocite command can be used.

The most common way of including a reference list is to create a file references.tex which is included into the main file after the body of the text (or the chapter inclusions). A sample references file can be found in the ~cmiss/latex/ directory.

To add a reference, open the references.bib file. At the top there are abbreviations for most of the common journals. If the journal you require is there please use the abbreviation given to ensure consistency. If the name of the journal is not there, create a new one. If the references file is opened in emacs, there are two extra menu bar headings which may be useful. The Entry Types menu has a list of many types of document to be referenced. Selecting one of these items creates a template for you to fill in the blanks. Before the template appears you must type in the key for the reference which is the string you will quote when referencing the item. The template will be placed in the correct place in the database. Usually only four fields are compulsory for the reference (this may depend on what you are referencing). You should try to fill out as many of the optional fields as you can.

The second menu is the Bibtex Edit menu. As the name suggests it has a list of editing commands which you can use in the database. The most useful few items are the clean up entry, the sort entries and the validate entries options. The clean option removes the unused fields and so 'cleans up' your new reference. The sort option will sort the entries into alphabetical order if, for example, you have decided to change the key. The validate option checks that all the entries have all the fields required and that the syntax is acceptable.

NOTE: This database is not like CMS, if you are saving the file something comes up such as File Changed on Disk, do not force a save, someone has been editing the file at the same time as you and saving will delete their changes.

Abbreviations & Units

Common abbreviations have been created in macros so that their formats may be kept consistent. Some of these abbreviations include

   Abbreviations

   e.g.,\eg

   et. al.\etal

   etc.\etc

   i.e.,\ie

   n.b.\nb

   Dr\Dr

   Units

   \degC

   \mps

   \mpsps

   \kNpm

   \mtwo

   \mmthree

Equations

• Ensure math fonts are used throughout the equation
• Vectors are indicated using the \vect command
• Matrices are denotes using the \matr command

Commenting

There are two general comment blocks. They are to be used for marking the locations where changes are to be made. To indicate that

work needs to be done

, the command \todo{text} is used, which produces the output in square brackets of the form: [text]

general comments

within the text use the command \remark{text}, which produces the output of the form: [Remark: text]

Graphics

Graphics are either generated using the XFIGure and gnuplot packages. The XFIGure package is used for creating general diagrams. The gnuplot is used for generating graphs from data.

• Labelling of items throughout the document should also follow a similar formats. All labels are three letters long e.g.,fig:, tab: and eqn: for the appropriate objects
• Different graphics files should be located in appropriate subdirectories corresponding to the document e.g.,
  ~/ <directory of the document> /figs
~/ <directory of the document> /epsfiles
~/ <directory of the document> /plots
• Figures should be inserted using the predefined macros for each type of figure.
  1. For a pstex figure i.e.,created from xfig or gnuplot e.g.,
     \pstexfigure{figure}{short caption}{long caption}{label}
     or \pstexfigure{figure}{}{caption}{label}
  2. For an eps figre i.e.,postscript file e.g.,
     \epsfigure{epsfig options}{short caption}{long caption}{label}
     or \epsfigure{epsfig options}{}{caption}{label}
• Ensure that maths font is used for all numbers and symbols. Especially when labelling
  1. Axes
  2. Numerical scales on axes
  3. Variables (e.g.,x, y, u)
• Arrow heads to be used are solid and have a chiselled point (i.e.,the fifth option in XFIG).
• Labels of axes should be located at the tip of the arrow.

Compiling

There is a program written to compile your documents into a dvi file which can be viewed in xdvi, a postscript file or an html file. It uses a file called Latex_make.sh. The main copy is in the ~cmiss/latex directory. This should be copied to each directory where you have a main TEX file. The file must be edited to show your file names, directories etc. Instructions for setting this file up are contained within the file itself. You can compile by typing Latex_make.sh but it is most common to create an alias in your .cshrc of the form

alias latexmake './Latex_make.sh'

The program can now be run by typing latexmake. To find out exactly what the compiler can do type latexmake help and a list of commands will be given.