History for Latex Style Guide
changed:
-
<h1><a name="SECTION00010000000000000000">Introduction</a></h1>
<p>
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. <br> <br>
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.
</p><p>
</p><h1><a name="SECTION00020000000000000000">Creating New Documents</a></h1>
<p>
</p><h2><a name="SECTION00021000000000000000">Starting a Document</a></h2>
<p>
</p><ul><li>
The standard <tt>Latex_make</tt> file can be located in the directory
<code>~cmiss/latex/</code>. This should be copied to the directory of the
current document an modified appropriately to compile new LaTeX documents.
</li><li> Various template documents can be located in the files
<code>~cmiss/latex/shell_*.tex</code>
</li><li> A sample paper can be located in the directory
<code>~cmiss/documents/papers/coupledpaper/</code>
</li><li> Latex tools (<i>e.g.,</i>macros.tex) can be found in the <code>~cmiss/latex/</code> directory.
</li></ul>
<p>
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 <code>~cmiss/latex/</code> directory or you can create a soft link
from a local file to the global files. The three files are:
</p><ol><li> <a name="tex2html1" href="http://www.esc.auckland.ac.nz/Groups/Bioengineering/CMISS/help/programmer/latex_style/abbreviations.txt">abbreviations.tex</a>
</li><li> <a name="tex2html2" href="http://www.esc.auckland.ac.nz/Groups/Bioengineering/CMISS/help/programmer/latex_style/acronyms.txt">acronyms.tex</a>
</li><li> <a name="tex2html3" href="http://www.esc.auckland.ac.nz/Groups/Bioengineering/CMISS/help/programmer/latex_style/macros.txt">macros.tex</a>
</li></ol>
<p>
In addition to this there is a file <a name="tex2html4" href="http://www.esc.auckland.ac.nz/Groups/Bioengineering/CMISS/help/programmer/latex_style/defns.txt">defns.tex</a> which is in the same
directory. This should also be included. It contains standard margin settings,
paper size, packages etc. <br>
</p><p>
<b>NOTE</b> It is important to use these predefined commands whenever possible.
</p><p>
</p><h2><a name="SECTION00022000000000000000">Document Styles</a></h2>
<p>
The structure and layout definitions are stored in the style files located in
the directory <code>~cmiss/latex</code>. These files usually have the extension
<tt>*.sty</tt>. LaTeX is distributed with standard document classes,
</p><dl><dt><b>articles</b>
</dt><dd> 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 <code>~cmiss/latex/shell_article.tex</code>
</dd><dt><b>reports</b>
</dt><dd> are intended for longer technical documents. The title page
will appear on a page of its own. A shell document can be located at
<code>~cmiss/latex/shell_report.tex</code>
</dd><dt><b>books</b>
</dt><dd> 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
<code>~cmiss/latex/shell_book.tex</code>
</dd><dt><b>letters</b>
</dt><dd> are inteded for producing personal letters. A shell document
can be located at <code>~cmiss/latex/shell_letter.tex</code>
<p>
</p></dd></dl><h2><a name="SECTION00023000000000000000">Directory & File Structure</a></h2>
<p>
</p><ul><li> When dealing with large documents with multiple chapters, directories
should be created for each chapter
</li><li> Macros used for LaTeX documents are located in the directory
<code>~cmiss/latex/macros.tex</code>
<p>
</p></li></ul><h1><a name="SECTION00030000000000000000">Style Conventions</a></h1>
<p>
</p><h2><a name="SECTION00031000000000000000">English Style</a></h2>
<p>
</p><ul><li> Computer code should be enter under the environment of <code>\compcode</code>
in order to distinguish it from the rest of the text. This will produce
output of the form <tt>text</tt>.
</li><li> Common ions can be generated using predefined macros. <i>e.g.,</i>using
<code>\ionbicarbonate</code> will produce output of the form .
A more extensive list can be located in the <tt>macros.tex</tt> file.
</li><li> 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.
</li><li> Colloquialisms are denoted using <code>\colloq{text}</code> to produce
output of the form `text'.
</li></ul><h2><a name="SECTION00032000000000000000">Maths Style</a></h2>
<p>
</p><ul><li> All numbers are to be entered in math font.
</li><li> Numbers located within text and less than 20 should be written out
fully. <i>e.g.,</i>four, ten, twelve.
</li><li> When a suffix for denoting the order of numbers such as
`th' is required, use the pre-defined macro for `th's, <code>\nth{i}</code>,
which produces an output of the form <img alt="tex2html_wrap_inline1532" src="http://cmiss.bioeng.auckland.ac.nz/development/help/programmer/latex_style/img49.gif" align="bottom" height="16" width="19">.
</li><li> When denoting the <img alt="tex2html_wrap_inline1534" src="http://cmiss.bioeng.auckland.ac.nz/development/help/programmer/latex_style/img50.gif" align="bottom" height="16" width="23"> dimension, a hyphen should always be placed
between the number and `dimension', <i>e.g.,</i>three-dimensional.
</li><li> Numbers with units should be generated using the predefined macro of
the form <code>\nunit{5}{\mps}</code>. This will produce
the output appearing as <img alt="tex2html_wrap_inline1536" src="http://cmiss.bioeng.auckland.ac.nz/development/help/programmer/latex_style/img51.gif" align="bottom" height="17" width="54">. For a more extensive list of
units refer to the latex macro file located in the directory:
<code>~cmiss/latex/macros.tex</code>.
</li><li> If a range of value is be required use the macro of the form
<code>\nrunit{5}{7}{\mps}</code> producing output appearing as
<img alt="tex2html_wrap_inline1538" src="http://cmiss.bioeng.auckland.ac.nz/development/help/programmer/latex_style/img52.gif" align="bottom" height="17" width="73">.
</li><li> Integral symbols are created using the predefined
macro of <code>\gint{w}{x}{y}{z}</code> which produces output of the form
<img alt="tex2html_wrap_inline1540" src="http://cmiss.bioeng.auckland.ac.nz/development/help/programmer/latex_style/img53.gif" align="middle" height="72" width="57"> or for evaluating integrals use <code>\evalat{x}{y}</code> to
create output of the form <img alt="tex2html_wrap_inline1542" src="http://cmiss.bioeng.auckland.ac.nz/development/help/programmer/latex_style/img54.gif" align="middle" height="31" width="23">.
</li><li> Derivative symbols are created in a similar fashion using the macro of
the form <code>\dby{x}{y}</code> to produce output of the form <img alt="tex2html_wrap_inline1544" src="http://cmiss.bioeng.auckland.ac.nz/development/help/programmer/latex_style/img55.gif" align="middle" height="53" width="21">.
</li><li> Many other forms of macros are created for producing mathematical
symbols. These can be located in the file <tt>macros.tex</tt>.
</li></ul><h2><a name="SECTION00033000000000000000">Referencing</a></h2>
<p>
The standard file for bibliography references are located in the directory <br>
<code>~cmiss/documents/references/references.bib</code>.
</p><p>
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 (<i>e.g.,</i>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 <code>\nocite</code> command can be used.
</p><p>
The most common way of including a reference list is to create a file
<code>references.tex</code> 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
<code>~cmiss/latex/</code> directory.
</p><p>
To add a reference, open the <code>references.bib</code> 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
<b>Entry Types</b> 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.
</p><p>
The second menu is the <b>Bibtex Edit</b> 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 <b>clean up entry</b>, the <b>sort entries</b> and the
<b>validate entries</b> 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.
</p><p>
<b>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.</b>
</p><p>
</p><h2><a name="SECTION00034000000000000000">Abbreviations & Units</a></h2>
<p>
Common abbreviations have been created in macros so that their formats may be
kept consistent. Some of these abbreviations include<br>
</p><p>
</p><blockquote> <pre><tt><br></tt><p><br><tt> <i>Abbreviations</i>
</tt></p><p><br><tt> <i>e.g.,</i><code>\eg</code>
</tt></p><p><br><tt> <i>et. al.</i><code>\etal</code>
</tt></p><p><br><tt> <i>etc.</i><code>\etc</code>
</tt></p><p><br><tt> <i>i.e.,</i><code>\ie</code>
</tt></p><p><br><tt> <i>n.b.</i><code>\nb</code>
</tt></p><p><br><tt> Dr<code>\Dr</code>
</tt></p><p><br><tt> <i>Units</i>
</tt></p><p><br><tt> <code>\degC</code>
</tt></p><p><br><tt> <code>\mps</code>
</tt></p><p><br><tt> <code>\mpsps</code>
</tt></p><p><br><tt> <code>\kNpm</code>
</tt></p><p><br><tt> <code>\mtwo</code>
</tt></p><p><br><tt> <code>\mmthree</code>
</tt></p><p><br></p></pre></blockquote><h2><a name="SECTION00035000000000000000">Equations</a></h2>
<p>
</p><ul><li> Ensure math fonts are used throughout the equation
</li><li> Vectors are indicated using the <code>\vect</code> command
</li><li> Matrices are denotes using the <code>\matr</code> command</li>
</ul><h2><a name="SECTION00036000000000000000">Commenting</a></h2>
<p>
There are two general comment blocks. They are to be used for marking the
locations where changes are to be made. To indicate that
</p><dl><dt><b>work needs to be done</b>
</dt><dd>, the command
<code>\todo{text}</code> is used, which produces the output in
square brackets of the form: <b>[text]</b>
</dd><dt><b>general comments</b>
</dt><dd> within the text use the command
<code>\remark{text}</code>, which produces the output of the form: <b>[Remark: text]</b>
<p>
</p></dd></dl><h1><a name="SECTION00040000000000000000">Graphics</a></h1>
<p>
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.
</p><ul><li> Labelling of items throughout the document should also follow a
similar formats. All labels are three letters long <i>e.g.,</i>fig:, tab: and
eqn: for the appropriate objects
</li><li> Different graphics files should be located in appropriate subdirectories
corresponding to the document <i>e.g.,</i><br>
<code> ~/ <directory of the document> /figs</code> <br>
<code> ~/ <directory of the document> /epsfiles</code> <br>
<code> ~/ <directory of the document> /plots</code>
</li><li> Figures should be inserted using the predefined macros for each type
of figure.
<ol><li> For a pstex figure <i>i.e.,</i>created from xfig or gnuplot <i>e.g.,</i><br>
<code>\pstexfigure{figure}{short caption}{long caption}{label}</code><br>
or <code>\pstexfigure{figure}{}{caption}{label}</code>
</li><li> For an eps figre <i>i.e.,</i>postscript file <i>e.g.,</i><br>
<code>\epsfigure{epsfig options}{short caption}{long caption}{label}</code><br>
or <code>\epsfigure{epsfig options}{}{caption}{label}</code>
</li></ol>
</li><li> Ensure that maths font is used for all numbers and symbols.
Especially when labelling
<ol><li> Axes
</li><li> Numerical scales on axes
</li><li> Variables (<i>e.g.,</i>x, y, u)</li></ol>
</li><li> Arrow heads to be used are solid and have a chiselled point
(<i>i.e.,</i>the fifth option in XFIG).
</li><li> Labels of axes should be located at the tip of the arrow.
</li></ul><h1><a name="SECTION00050000000000000000">Compiling</a></h1>
<p>
There is a program written to compile your documents into a <b>dvi</b> file
which can be viewed in xdvi, a postscript file or an <b>html</b> file. It
uses a file called <code>Latex_make.sh</code>. The main copy is in the
<code>~cmiss/latex</code> 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 <code>Latex_make.sh</code> but it
is most common to create an alias in your <code>.cshrc</code> of the form
</p><p>
<code>alias latexmake './Latex_make.sh'</code>
</p><p>
The program can now be run by typing <b>latexmake</b>. To find out exactly
what the compiler can do type <b>latexmake help</b> and a list of commands
will be given.
</p>
Forgot your password?
New user?