• Intro
• Downloads
• Community
• Development
• News
• TALK

Documentation/Maemo Documentation Guidelines/Formatting in LaTeX

Revision as of 10:44, 15 July 2010

This chapter includes information about how to format Maemo documentation text in LaTeX environment.

Basic instructions on how to use LaTeX can be found here: WikiBooks LaTex.

To be able to create a reference to a specific element in a document, you must label that element with the unique LaTeX special characters and especially spaces in the label name. Position \label tag on the next row after the referenced element tag (like \section).

For references, use \ref tag with a unique label.

Using LaTeX formatting commands

Using list of tables

Use \listoftables to create a list of tables automatically. Used for PDF documents to get a more book like result.

Using list of figures

Use \listoffigures to create a list of figures automatically. Used for PDF documents to get a more book like result.

Using LaTeX special characters

LaTeX has special characters _$#%{}^~{} that need to be handled in text with a special marking like \_, \$, \#, \%, \{, \}, \^ and \~{}.

Using highlight for example code

Use \textraw{Example text} or \verb|Example text| to highlight command line examples, function names, and file names in base text. The difference between these two is that \textraw allows normal LaTeX commands inside text will be ignored and handled as plain text.

Both \textraw and \verb will display given text in an appropriate fixed-width font.

For example:

• Function \textraw{example\_function\_name()}.
• Function example_function_name().

• Command \textraw{\$ mkdir \~{}/folder}.
• Command $ mkdir ~/folder.

• File \verb|~/folder/example_file.txt|.
• File ~/folder/example_file.txt.

Using highlight for important words

Use Italics for other than command line examples and function or file names.

For example:

• This is \textit{important example text}.
• This is important example text.

Using highlight for user interface component names

Use Bold for UI element names in text. UI element name in text is the same as UI element caption in UI.

For example:

• This is \textbf{UI Element Caption}.
• This is UI Element Caption.

Using normal headings

Use the chapter tag for level 0 chapters (a) together with a unique label. Use the section (for a.b), subsection (for a.b.c) or subsubsection (for a.b.c.d) tag together with unique label for other headings.

For example:

Chapter:
  \chapter{Example chapter title}
  \label{cha:example-chapter-title}

Section:
  \section{Example section title}
  \label{sec:example-chapter-title-example-section-title}

Subsection:
  \subsection{Example subsection title}
  \label{sec:example-chapter-title-example-subsection-title}

Subsubsection:
  \subsubsection{Example subsubsection title}
  \label{sec:example-chapter-title-example-subsubsection-title}

Using level 4 headings

Use Bold without a label for level 4 (a.b.c.d.e) headings. This way, level 4 titles are not numbered or included in the table of contents.

For example:

• \textbf{Example level 4 title}
• Example level 4 title

Using command line and screen output examples

Use {graybox} environment for command line and screen output examples that require more than one row.

Explicit new lines (\\) need to be given inside {graybox} environment to separate different rows. LaTeX special characters (_$#%{}^~{}) need to be handled in text with special marking unless they are used inside \verb command.

For example:

<empty line is required before graybox>
 \begin{graybox}
  \$ First command line
  \textraw{\$ Second line in TextRaw}
  Third line has underscore (character '\_') and dollar sign (character '\$')
 \end{graybox}

$ First command line
 $ Second line in TextRaw
Third line has underscore (character '_') and dollar sign (character '$')

Using notes

Use {notebox} environment for notes that require whole sentence or paragraph to be highlighted.

Explicit new lines (\\) need to be given inside {notebox} environment to separate different rows. LaTeX special characters (_$#%{}^~{}) need to be handled in text with special marking unless they are used inside \verb command.

For example:

\begin{notebox}
This is note text inside a yellow box
 \textraw{Second line in TextRaw}
 Third line has underscore (character '\_') and dollar sign (character '\$')
 \end{notebox}

Using code listings

Use \lstset and \lstinputlisting for listing source code for C/C++, CSS, HTML, Java, JavaScript, Latex, Pascal, Perl, PHP, Postscript, Python, Ruby, SQL, Tcl, Properties files, Makefile, XML, Log files, Ini files and Shell scripts.

For example:

\lstset{language=C}
 \lstinputlisting{chapters/DocumentationGuidelines/snippets/example_source.c}

/*
* example_source.c, an example source code for kernel module
*
* Copyright (C) 2010 Nokia Corporation. All rights reserved.
*
* This maemo code example is licensed under a MIT-style license,
* that can be found in the file called "COPYING".
*
*/
 
#include <linux/module.h> /* needed by all kernel modules */
#include <linux/init.h>   /* needed for custom init/exit functions */
#include <linux/kernel.h> /* needed for KERN_ALERT macro */
 
/* Special macro to indicate license (to avoid tainting the kernel) */
MODULE_LICENSE("Dual MIT/GPL");
 
static int hello_init(void) {
printk(KERN_ALERT "Hello, world\n"); /* top priority message */
return 0;
}
 
static void hello_exit(void)
{
printk(KERN_INFO "Goodbye, world\n");
}
 
/* macros to mark modules init/exit funcs (run on insmod/rmmod) */
module_init(hello_init);
module_exit(hello_exit);

Using figures

Use \includegraphics for figures without a file name extension. For example, use image_file_name instead of image_file_name.png.

Use option [H] for figure environment if the position of the figure related to base text cannot be changed by LaTeX . For example \begin{figure}[H].

All figures must be centered and have both a caption and a label.

For example:

\begin{figure}[H]
  \caption{Example picture}
  \label{fig:example-chapter-title-example-picture}
  \centering
  \includegraphics[width=\textwidth]{folder/images/LaTeX_logo}
 \end{figure}

Combining small tables and figures

You can arrange small tables and figures side-by-side within the page width limitation.

The following figure environment arranges two small figures side-by-side and creates individual captions for each figure and one common caption for the whole figure environment.

\begin{figure}[H]
\caption{Example logos}
\label{fig:example-chapter-title-example-logos}
\centering
\subfloat[ESbox]{
\includegraphics{chapters/DocumentationGuidelines/images/esbox_logo}
}
\subfloat[PluThon]{
\includegraphics{chapters/DocumentationGuidelines/images/pluthon_logo}
}
\end{figure}

Referring to a section

Use a standard reference \ref to refer to a section in base text. Use a unique label in a reference and refer only to sections inside the same level 1 section (a.b).

For example:

• For more information on example topic, see chapter \ref{sec:example-chapter-title-example-section-title}.
• For more information on example topic, see chapter #Using LaTeX formatting commands.

Referring to a figure

Use standard reference \ref to refer to a figure in base text. Use a unique label in a reference and refer only to sections inside the same level 1 section (a.b).

For example:

• For more information on example topic, see figure \ref{fig:example-chapter-title-example-picture}.
• For more information on example topic, see figure 4.1.

Referring to a table

Use standard reference \ref to refer to a table in base text. Use a unique label in a reference and refer only to sections inside same level 1 section (a.b).

For example:

• For more information on example topic, see table \ref{tab:example-chapter-title-example-table}.
• For more information on example topic, see table 4.1.

Using HTML links

Use \htmladdnormallink for external references that are not included in the Maemo bibliography database. Notice that link text is normal LaTeX text and characters _$#%{}^~ need to be handled with special marking but URL can be any normal HTTP link.

For example:

• For more information on example topic, see \htmladdnormallink{maemo.org}{http://www.maemo.org}.
• For more information on example topic, see maemo.org.

Using Maemo bibliography database

Use \cite for external references from Bibliography database. All references to external documents that are other than product version specific documents (documents that are not expected to change regularly) must use Maemo bibliography database. Use LaTeX tag \htmladdnormallink for references to product version specific documents.

Give document name in Italics before citation from bibliography database and join document name and citation together with tilde (~). Tilde prevents LaTeX to break row between document name end and citation link.

For example:

• For more information on example topic, see document \textit{Maemo Documentation Guidelines}~\cite{bibliography-key}.
• For more information on example topic, see document Maemo Documentation Guidelines ^[1].
• For more information on example topic, see document \textit{Maemo Documentation Guidelines}~\cite[Formatting in LaTex]{bibliography-key}.
• For more information on example topic, see document Maemo Documentation Guidelines [[/node7.html#maemo-documentation-guidelines 4], Formatting in LaTex].

Using normal tables

Use \tabular and \table to create tables. For example to create a table with two half-page-wide columns that can expand to new lines, use the following definition:

\begin{tabular}{|p\{0.5\textwidth}|p{0.5\textwidth}|}

To set the width for the whole table, use {tabular*} with option \textwidth:

\begin{tabular*}{\textwidth}{|c|p{0.5\textwidth}|}

To reduce column width use @{}: \begin{tabular} {|@{}c@{}|c|}.

To add horizontal lines between cells, use \hline. To separate cells, use &. To change row, use \\.

Use option [H] for table environment if LaTeX cannot change the position of the table related to base text: \begin{table}[H].

All tables must be centered and have both a caption and a label.

For example:

\begin{table}[H]
 \caption{Example normal table}
 \label{tab:example-chapter-title-example-table}
 \centering
 \begin{tabular}{|p{0.45\textwidth}|p{0.45\textwidth}|}
 \hline\hline
 \textbf{Column 1} & \textbf{Column 2} \\
 \hline
 % Table data starts from here
 %
 1 & 2 \\ \hline
 3 & 4 \\ \hline
 5 & 6 \\ \hline
 \hline
 \end{tabular}
\end{table}

Using multi-column table rows

Use \multicolumn to widen a table row to cover multiple columns. Avoid using multi-column cells for other purposes than creating subheadings for the table. If complex tables are needed create them outside LaTeX as images.

For example:

<code>\multicolumn{2}{|l|}{\textbf{\textit{Table SubHeader}}} \\ \hline

Using long tables

Use {center} and {longtable} environments to create tables that require multiple pages. For example, to create a table with two half-page-wide columns that can expand to new lines, use the following definition:

\begin{longtable}{|p{0.45\textwidth}|p{0.45\textwidth}|}

To reduce column width use @{}:

\begin{longtable}{|@{}c@{}|c|}

To add horizontal lines between cells, use \hline. To separate cells, use &. To change row, use \\.

All tables must be centered and have both a caption and a label.

For example:

\begin{center}
 \begin{longtable}
{|p{0.45\textwidth}|p{0.45\textwidth}|}
 \caption{Example long table}
 \label{tab:example-chapter-title-example-long-table}
 % FirstHead
 \hline\hline
 \textbf{Column 1} & \textbf{Column 2} \\ \hline
 \endfirsthead
 % Head
 \hline\hline
 \multicolumn{2}{|l|}{\small\tablename \thetable{}
 Continued from previous page} \\
 \hline\hline
 \textbf{Column } & \textbf{Column 2} \\ \hline
 \endhead
 % Foot
 \multicolumn{2}{|r|}{\small\tablename \thetable{}
 Continued to next page} \\
 \hline
 \endfoot
 % LastFoot
 \hline\hline
 \endlastfoot
 % Table data starts from here
 %
 1 & 2 \\ \hline
 3 & 4 \\ \hline
 5 & 6 \\ \hline
 ... & ... \\ \hline
 \end{longtable}
\end{center}

Reducing the size of tables and figures

You can reduce the size of tables and figures that do not fit on the page without scaling them down.

If the object is too long or wide, you can:

• reduce the size of the table font
• rotate the figure
• scale down the figure

Reduce the size of the table

To reduce the size of the table use the font size command inside the table environment to reduce the size of the table font. Font size commands in order from biggest to smallest are:

Huge, huge, LARGE, Large, large, normalsize, small, footnotesize, scriptsize and tiny.

Rotate and scale down a figure

To fit on the page, figures in Maemo documents are recommended to have maximum size of 600 x 1200 (width x height) pixels. If a figure is bigger than this, it needs to be rotated, scaled down, or both rotated and scaled down before it can be used. Maemo documentation infrastructure provides a command line tool for automatic figure rotation and scaling.

For Maemo documents figures wider than 340 pixels must be scaled down in LaTeX to fit to the default page width used in PDF documents. Figures wider than 600 pixels or higher than 1200 pixels are recommended to be scaled down with maemodoc-scaleimage command line tool for them to be readable also in HTML documents.

Figures which are smaller than 340 x 1200 (width x height) pixels do not need to be scaled down either in LaTeX or with maemodoc-scaleimage tool.

For example, the following command scales a figure down to the recommended maximum width and height.

$ ./maemodoc-scaleimage <image_file> -outpath <output directory>

The following command rotates the figure 90 degrees anticlockwise if doing so reduces the amount of scaling needed. The command scales down the figure to the recommended maximum width and height only if the figure after rotation still does not fit on the page.

$ ./maemodoc-scaleimage <image_file> -outpath <output directory> -rotate

References

1. ↑ Maemo Documentation Guidelines. http://library.maemodocs.nokia.com