# Writing Tips and Conventions

Rob MacLeod

For the collaborative writing of grants at SCI, there are some writing style conventions that make life at least a little simpler when observed by all.

# 1 Macros

Macros in LATEX are commands that do things within the document. The simplest form of a macro is a shortcut for some longer word or passage. In our case, the most popular macro has been \PSE, which stands for the name of the problem solving environment we are proposing. This macro can change daily and at the moment equals BioPSE but that just depends on its value at the time I made this document.

Here are some of the standard set of macros we use in SCI:

• \PSE{} = BioPSE
• \Center{} = CIBDAV
• \CenterFull{} = Center for Integrative Biomedical Data Analysis and Visualization
• \eg{} = e.g.,
• \ie{} = i.e.,
• \etal{} = et al.
• \map{} = map3d
• \scirun{} = SCIRun
• \PSE{} = BioPSE
• \Center{} = CIBDAV
• \degrees{} = o
• \muv{} = V
• \ohm{} =

Note: when using macros, (almost) always use the \Name{} form, i.e., with the curled braces. Without them, the macro will merge with the following word, e.g., \PSE components'' will produce BioPSEcomponents'' while \PSE{} components'' will produce the desired result of BioPSE components''.

# 2 Label names

Each element of a document in LATEX can have a label attached to which one can then refer at a later (or earlier) time in the document. For example, this section has a label assigned by the command \label{sec:sectionnames} and I can refer to it elsewhere as Section 2 with the command Section~\ref{sec:sectionnames}.

We have conventions for making labels that, like with bibliography citations, make it easier to track down errors and unresolved references to labels.

• All labels for sections of text begin with sec:''.
• All labels of figures begin with fig:''.
• All labels of equations begin with eqn:''.
• Try and place section labels close to their section comment to which they refer, usually right after the section command, as in
      \section{Section names}
\label{sec:sectionnames}

which is how I defined this section.
• In a document like a grant, embed the section into the label name, for example \label{sec:core3-intro} for the intro to Core 3. There are no hard rules here so just use common sense and try to keep the labels short at the risk of them not being perfect identifiers.

# 3 Section name capitalization

We should strive for consistent case (capitalization) of all section names. The following convention is one we have used in the past and seems to work well:
 Section name capitalization Section level Case rules chapter Book capitals, The Title of a Chapter section Book capitals, The Title of a Section subsection Sentence capitals, The title of a subsection subsubsection Sentence capitals, The title of a subsubsection paragraph Sentence capitals, The title of a paragraph

# 4 Figure Filenames

Please name your figures something that links them to the section of file in which they are supposed to live. If they do not arrived named this way, I will make them comply and adjust the .tex files accordingly.

The names do not have to be completely specific, e.g.,.,

 core1-2-section-D-part4-figure2.eps

is a little overkill but

core1-bridge.eps

is OK, and perhaps

core1-intro-bridge.eps

even better.

Environments

LATEX supports environments for specialized formatting and layout and we have some of these for the grant.

## 4.1 Figures

Perhaps the most (mis)used environment in LATEX is the figure environment. The uniform way to do this that makes use of the graphicx style in LATEX is as follows:

\begin{figure}[htbp]
%    \figspace{figures/aim-composite.eps}
\centerline{\includegraphics[width=.6\columnwidth]
{figures/aim-composite.eps}}
\caption{\label{fig:aims} Schematic diagram for the proposed Utah
training program in computational biology.  Panel A shows the typical
interaction between computing and a partner discipline X''.  In
Panel B Biomedical Computing is a free standing activity that draws
from bioengineering, computational sciences and from other related
disciplines.}
\end{figure}


This one sets the postscript file aim-composite.eps and gives it a width of 0.6 of the current width of the column. Place the label inside the caption.

\begin{figure}[htbp]
%    \figspace{figures/aim-composite.pdf}
\centerline{\includegraphics[width=.6\columnwidth]
{figures/aim-composite.pdf}}
\caption{\label{fig:aims} Schematic diagram for the proposed Utah
training program in computational biology.  Panel A shows the typical
interaction between computing and a partner discipline X''.  In
Panel B Biomedical Computing is a free standing activity that draws
from bioengineering, computational sciences and from other related
disciplines.}
\end{figure}


The example above looks very much like the one above it and it is--the only difference is that it assumes pdflatex, a slightly different version that accepts other image/figure file formats, most notably pdf, png, and jpg. Note the filename aim-composite.pdf. Unfortunately, it does not accept postscript!

The \figspace command that is commented out above is a good trick to set aside space for a figure and make sure it is obvious when viewing the file that the figure is still missing. We used to use \vspace for this situation but this new macro draws a nice box with the filename in the middle. So please use it instead of \vspace.

Thus a figure for which there is not yet a finished eps file could look like this

\begin{figure}[htbp]
\figspace{figures/aim-composite.eps}
%    \centerline{\includegraphics[width=.6\columnwidth]
%      {figures/aim-composite.eps}}
\caption{\label{fig:aims} Schematic diagram for the proposed Utah
training program in computational biology.  Panel A shows the typical
interaction between computing and a partner discipline X''.  In
Panel B Biomedical Computing is a free standing activity that draws
from bioengineering, computational sciences and from other related
disciplines.}
\end{figure}


Note that this time, the \centerline command is commented out rather than the \figspace.

There are many other options to the \includegraphics command, but rarely does one use them. Check out any decent LATEX book for more details.

# 5 Writing conventions

Here are some writing conventions we should try and follow:

• third party'' as noun or third-party software'' as adjective So We deal with a third party to get access to third-party software''
• The world is three dimensional so we live in a three-dimensional world.'' Try and avoid 2D and 3D as contractions, especially in biomedical applications.
• Jeroen is a thin client but Yarden makes thin-client software.''

Writing Tips and Conventions

This document was generated using the LaTeX2HTML translator Version 2002-2-1 (1.70)

Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The command line arguments were:
latex2html -split 3 -no_white -link 3 -no_navigation -no_math -html_version 3.2,math -show_section_numbers -local_icons writing-tips

The translation was initiated by Rob Macleod on 2004-12-20

Rob Macleod 2004-12-20