style-guide.tex

\documentclass[11pt,a4paper]{article}
\include{style}
\include{macros}
\title{Style Guide}
\author{Toon Willems}

\begin{document}
\maketitle

\section{File organisation}
\label{sec:file-organisation}

The main \texttt{intro-HPC.tex} file contains all the necessary setup for the rest of
the chapters. Each chapter should be written in a separate file. Give the
chapter a meaningful filename. For example: \texttt{ch\_introduction.tex}.

After following these conventions you only need to add the include in the main
\texttt{intro-HPC.tex} file.

\section{Sections and chapters}
\label{sec:sections-and-chapters}

Chapter titles should contain capitalised words. Section titles should only
have the first word capitalised. Every \texttt{\textbackslash{}chapter},
\texttt{\textbackslash{}section} and \texttt{\textbackslash{}subsection} should
be accompanied by a \texttt{\textbackslash{}label}.

The label name should start with \texttt{ch} for a chapter, \texttt{sec} for a
section and subsection. The label should have a name closely resembling the
title, spaces should be replaced by dashes. Example:

\begin{verbatim}
\chapter{This Is A Chapter Title}
\label{ch:chapter-title}

\section{This is a section title}
\label{sec:section-title}
\end{verbatim}

\section{Tables}
\label{sec:tables}

When defining tables spend some time to align them column-wise, this looks much more attractive.

\begin{verbatim}
\begin{tabular}{|l|l|} \hline
  short        & \textbf{\dots in human terms} \\ \hline
  short        & \dots                         \\ \hline
  short        & \dots                         \\ \hline
  a bit longer & \dots                         \\ \hline
\end{tabular}
\end{verbatim}

\section{Lists}
\label{sec:lists}

When defining lists make sure to indent the items.

\begin{verbatim}
\begin{itemize}
  \item indented item
  \item multi-line item which spans
    multiple lines
  \begin{enumerate}
    \item you can
    \item have multiple
    \item levels of indentation
  \end{enumerate}
\end{itemize}
\end{verbatim}

\section{Displaying example code}
\label{sec:displaying-example-code}

To display example code inside the document you can use the \lstinline|\examplecode|
command. The example code files should be organised in an \lstinline|examples|
subdirectory.  Each chapter should have its own directory. The directory name
is the same as the chapter name with spaces and slashes substituted by dashes.
(e.g., ``Multi-core Job Submission'' is turned into
``Multi-core-Job-Submission'').

The \lstinline|examplecode| takes 2 mandatory arguments. The first one is the
language of the code file (e.g., C or Python). The second is the basename of the
file. If you want you can organise the example files per chapter in
subdirectories, you then need to add the subdirectory to the filename argument.
The commands below illustrate how this works.

\begin{verbatim}
\examplecode{C}{mpi_hello.c}
\examplecode{Python}{subdir/file1.py}
\end{verbatim}


The macro \lstinline|\exampledir| will expand to the example directory used on a per
chapter basis.

\section{Displaying inline code}
\label{sec:displaying-inline-code}

To display inline code inside the document, you can use the \lstinline|\lstinline| command.
This should be used when talking about Linux commands, filenames, \ldots
When you want inline code inside a title, you can use the \lstinline|\texttt{}| command.
When using \lstinline|\texttt|, you will need to escape certain characters.

Do not use \lstinline|\verb|: text in \lstinline|\verb| might be rendered outside of the
page (\lstinline|\verb| doesn't wrap).

\section{Displaying prompts}
\label{sec:displaying-prompts}

To display prompt output you can use the prompt environment. To obtain a
consistent look-and-feel, put an empty line before the prompt environment.  In
case the prompt environment is part of an if--else construction, do not indent
the prompt environment to avoid an unwanted empty line at the end.  There
is the special command \lstinline|\shellcmd{}| which provides consistent styling. It
also includes a \$-sign. There is a special version of this command called
\lstinline|\captureshellcmd{}|. This behaves exactly the same as \lstinline|shellcmd| but
it writes its argument to \lstinline|shellcmds.sh|. All commands you want to capture
will be present here. This file will be updated each time you build the PDF.
You can use this to easily run commands and paste their output in the latex
file. NOTE: instead of \lstinline|\tilde| you should use a regular \tilde{} inside
\lstinline|\shellcmd| and \lstinline|\captureshellcmd|. Inside the prompt environment you
can use \% as escape character to type commands.

\begin{verbatim}
\begin{prompt}
%\shellcmd{bash --version}%
GNU bash, version 4.1.2(1)-release (x86_64-redhat-linux-gnu)
%\captureshellcmd{ls ~}%
\end{prompt}
\end{verbatim}

which will result in following output:

\begin{prompt}
%\shellcmd{bash --version}%
GNU bash, version 4.1.2(1)-release (x86_64-redhat-linux-gnu)
%\captureshellcmd{ls ~}%
\end{prompt}

If you want to display example output from a file, you can use the
\lstinline|\exampleoutput| command. This will look inside \lstinline|\exampledir| and
format the file in a prompt environment.

\begin{verbatim}
\exampleoutput{htop-output}
\end{verbatim}

\section{Job scripts}
\label{sec:job-scripts}

When including code of any kind you can use the code environment, there is a
required argument which sets the language. The following \LaTeX code:

\begin{verbatim}
\begin{code}{bash}
#!/bin/bash
#PBS -m e
echo test
\end{code}
\end{verbatim}

will result in following output:

\begin{code}{bash}
#!/bin/bash
#PBS -m e
echo "test"
\end{code}

\section{Windows and Mac-specific}
\label{sec:windows-and-mac-specific}

You can write Windows, Mac or Linux specific sections with the \texttt{ifwindows}, \texttt{ifmac}, \texttt{iflinux} and
\texttt{ifmacORlinux} commands.

\begin{verbatim}
\ifwindows
  Windows specific text
\fi
\end{verbatim}

\begin{verbatim}
\ifmac
  Mac specific text
\fi
\end{verbatim}


\section{Site-specific sections}
\label{sec:site-specific-sections}

Site-specific sections are very much like platform-specific sections. You use
the same constructs, but now instead of the \texttt{ifmac} and \texttt{ifwindows}
keywords you can use: \texttt{ifleuven}, \texttt{ifgent}, \texttt{ifantwerpen} or \texttt{ifbrussel}.

\begin{verbatim}
\ifgent
  Gent specific text
\fi
\end{verbatim}

If large pieces of text need to be included you can use the
\lstinline|includesite| command.
Note: this command will not fail if the site-specific section is missing.

\begin{verbatim}
\includesite{intro}
\end{verbatim}

The above example will not include intro.tex, but will include <site>/intro.tex (e.g., gent/intro.tex)

Because includes cannot be nested there is also the \lstinline|\inputsite| command
which works exactly the same as above only it uses \lstinline|\input| instead of
\lstinline|\include|. This command \emph{will} fail when a file is not present.

\subsection{Macros}
\label{sec:macros}

There is sometimes the need to write a general text segment, but include site
specific names. For example a section which includes the name of the login node.
To fix this problem, you can use a macro. For example:

\begin{verbatim}
you can connect to \loginnode with ssh.
\end{verbatim}

These macros are all defined inside \lstinline|macros.tex|. This file is located
inside the site-specific directory. You can define new macros like so:
\begin{verbatim}
\macro{\city}{Gent}
\end{verbatim}

Note: Adding new macros breaks the compilation process! Add them for all sites,
and do not abuse them.

% allow the style-guide to pick up on the macros.
\input{sites/gent/macros}

In this table you can see which macros are currently available. Here shown are
the macro names, with the values for UGent.

\begin{tabular}{|c|c|} \hline
  \strong{Macro name} & \strong{Example value} \\ \hline
  \maketabularrow{\thecnt} \\ \hline % We apparently need to end this here
\end{tabular}

\section{Misc.}
\label{sec:misc}

URLs should be embedded in a \texttt{url} command. This ensures they are clickable. As seen below:
\begin{verbatim}
\url{http://vscentrum.be}
\end{verbatim}

The end result is much nicer, compare http://vscentrum.be with \url{http://vscentrum.be}.

\subsection{Semantics}

Try using the best possible environment suited to your needs. For example instead of using:
\begin{verbatim}
\begin{enumerate}
  \item \textbf{item 1} Description
\end{enumerate}
\end{verbatim}

use:

\begin{verbatim}
\begin{description}
  \item[item 1] Description
\end{description}
\end{verbatim}

As this provides much more semantic value. Although \LaTeX\ provides
\lstinline|\textit| and \lstinline|\textbf| we suggest using \lstinline|\emph| and
\lstinline|\strong|.

\subsection{Tilde}
\label{sec:tilde}

The tilde (\tilde) in \LaTeX\ looks terrible by default. It is advised to use
\lstinline|\tilde| which is a much nicer version.

Compare \tilde\ (\lstinline|\tilde|) with \~\ (\lstinline|\~|)

\end{document}