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 L^ATEX 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{} = $\mu$ V
\ohm{} = $\Omega$

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 L^ATEX 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

L^ATEX 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 L^ATEX is the figure environment. The uniform way to do this that makes use of the graphicx style in L^ATEX 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 L^ATEX 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.''

About this document ...

Writing Tips and Conventions

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

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

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