# Documentation/Maemo Documentation Guidelines/Formatting in LaTeX

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 in the LaTeX Wikibook

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.

 \textraw is a Maemo-specific definition and is usable only in the Maemo environment.

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.

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.

 {graybox} is a Maemo-specific definition and is usable only in the Maemo environment.

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.  {notebox} is a Maemo-specific definition and is usable only in the Maemo environment. 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} {{ambox|text=This is note text inside a yellow box Second line in TextRaw Third line has underscore (character '_') and dollar sign (character '$')

###  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
*
*
* 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) */

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].

{{ambox|text=Use maemodoc-scaleimage command line tool to scale down figure files that are bigger than recommended maximum size of 600 × 1200 (width × height) pixels. Use option [width=\textwidth] when including figures in LaTeX that are wider than 340 pixels. |}

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}
File:LaTeX logo.png
Figure 4.1: Example picture

###  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}
 [ESbox] File:Esbox logo.png [PluThon] File:Pluthon logo.png

###  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).

 File:Dialog-information.png Note: Referring to the level 0 chapters (a) is not allowed because references can be used only inside same level 1 section (a.b).

For example:

• 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:

###  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: