Documentation/Maemo Documentation Guidelines/Formatting in LaTeX

(categorize)
(wikify slightly)
 
(One intermediate revision not shown)
Line 1: Line 1:
-
= Formatting in LaTeX =
 
-
 
This chapter includes information about how to format Maemo documentation text in LaTeX environment.
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: [http://en.wikibooks.org/wiki/LaTeX/ WikiBooks LaTex].
+
Basic instructions on how to use LaTeX can be found here in the [[wikibooks:LaTeX|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 <code>\label</code> tag on the next row after the referenced element tag (like <code>\section</code>).
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 <code>\label</code> tag on the next row after the referenced element tag (like <code>\section</code>).
Line 9: Line 7:
For references, use <code>\ref</code> tag with a unique label.
For references, use <code>\ref</code> tag with a unique label.
-
= Using LaTeX formatting commands =
+
== Using LaTeX formatting commands ==
-
== Using list of tables ==
+
=== Using list of tables ===
-
Use <code>\listoftables</code> to create a list of tables automatically. Used for PDF documents to get a more book like result.
+
Use <code>\listoftables</code> to create a list of tables automatically. Used for PDF documents to get a more book-like result.
-
== Using list of figures ==
+
=== Using list of figures ===
Use <code>\listoffigures</code> to create a list of figures automatically. Used for PDF documents to get a more book like result.
Use <code>\listoffigures</code> to create a list of figures automatically. Used for PDF documents to get a more book like result.
-
== Using LaTeX special characters ==
+
=== Using LaTeX special characters ===
LaTeX has special characters <code>_$#%{}^~{}</code> that need to be handled in text with a special marking like <code>\_</code>, <code>\$</code>, <code>\#</code>, <code>\%</code>, <code>\{</code>, <code>\}</code>, <code>\^</code> and <code>\~{}</code>.
LaTeX has special characters <code>_$#%{}^~{}</code> that need to be handled in text with a special marking like <code>\_</code>, <code>\$</code>, <code>\#</code>, <code>\%</code>, <code>\{</code>, <code>\}</code>, <code>\^</code> and <code>\~{}</code>.
-
== Using highlight for example code ==
+
=== Using highlight for example code ===
Use <code>\textraw{Example text}</code> or <code>\verb|Example text|</code> to highlight command line examples, function names, and file names in base text. The difference between these two is that <code>\textraw</code> allows normal LaTeX commands inside text will be ignored and handled as plain text.
Use <code>\textraw{Example text}</code> or <code>\verb|Example text|</code> to highlight command line examples, function names, and file names in base text. The difference between these two is that <code>\textraw</code> allows normal LaTeX commands inside text will be ignored and handled as plain text.
Line 29: Line 27:
Both <code>\textraw</code> and <code>\verb</code> will display given text in an appropriate fixed-width font.
Both <code>\textraw</code> and <code>\verb</code> will display given text in an appropriate fixed-width font.
-
{|
+
{{ambox|text=<code>\textraw</code> is a Maemo-specific definition and is usable only in the Maemo environment.}}
-
|-
+
-
| [[Image:dialog-information.png]]
+
-
| '''Note:'''  <code>\textraw</code> is a Maemo-specific definition and is usable only in the Maemo environment.
+
-
|}
+
For example:
For example:
Line 46: Line 40:
* File <code>~/folder/example_file.txt</code>.
* File <code>~/folder/example_file.txt</code>.
-
== Using highlight for important words ==
+
=== Using highlight for important words ===
Use ''Italics'' for other than command line examples and function or file names.
Use ''Italics'' for other than command line examples and function or file names.
Line 55: Line 49:
* This is ''important example text''.
* This is ''important example text''.
-
== Using highlight for user interface component names ==
+
=== 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.
Use '''Bold''' for UI element names in text. UI element name in text is the same as UI element caption in UI.
Line 64: Line 58:
* This is '''UI Element Caption'''.
* This is '''UI Element Caption'''.
-
== Using normal headings ==
+
=== 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.
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.
Line 86: Line 80:
   <code> \label{sec:example-chapter-title-example-subsubsection-title}</code>
   <code> \label{sec:example-chapter-title-example-subsubsection-title}</code>
-
== Using level 4 headings ==
+
=== 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.
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.
Line 95: Line 89:
* '''Example level 4 title'''
* '''Example level 4 title'''
-
== Using command line and screen output examples ==
+
=== Using command line and screen output examples ===
Use <code>{graybox}</code> environment for command line and screen output examples that require more than one row.
Use <code>{graybox}</code> environment for command line and screen output examples that require more than one row.
-
{|
+
{{ambox|text=<code>{graybox}</code> is a Maemo-specific definition and is usable only in the Maemo environment.}}
-
|-
+
-
| [[Image:dialog-information.png]]
+
-
| '''Note:'''  <code>{graybox}</code> is a Maemo-specific definition and is usable only in the Maemo environment.
+
-
|}
+
Explicit new lines (<code>\\</code>) need to be given inside <code>{graybox}</code> environment to separate different rows. LaTeX special characters (<code>_$#%{}^~{}</code>) need to be handled in text with special marking unless they are used inside <code>\verb</code> command.
Explicit new lines (<code>\\</code>) need to be given inside <code>{graybox}</code> environment to separate different rows. LaTeX special characters (<code>_$#%{}^~{}</code>) need to be handled in text with special marking unless they are used inside <code>\verb</code> command.
Line 120: Line 110:
  Third line has underscore (character '_') and dollar sign (character '$')
  Third line has underscore (character '_') and dollar sign (character '$')
-
== Using notes ==
+
=== Using notes ===
Use <code>{notebox}</code> environment for notes that require whole sentence or paragraph to be highlighted.
Use <code>{notebox}</code> environment for notes that require whole sentence or paragraph to be highlighted.
-
{|
+
{{ambox|text=<code>{notebox}</code> is a Maemo-specific definition and is usable only in the Maemo environment.}}
-
|-
+
-
| [[Image:dialog-information.png]]
+
-
| '''Note:'''  <code>{notebox}</code> is a Maemo-specific definition and is usable only in the Maemo environment.
+
-
|}
+
Explicit new lines (<code>\\</code>) need to be given inside <code>{notebox}</code> environment to separate different rows. LaTeX special characters (<code>_$#%{}^~{}</code>) need to be handled in text with special marking unless they are used inside <code>\verb</code> command.
Explicit new lines (<code>\\</code>) need to be given inside <code>{notebox}</code> environment to separate different rows. LaTeX special characters (<code>_$#%{}^~{}</code>) need to be handled in text with special marking unless they are used inside <code>\verb</code> command.
Line 140: Line 126:
   <code>\end{notebox}</code>
   <code>\end{notebox}</code>
-
{|
+
{{ambox|text=This is note text inside a yellow box<br/><span><font face="monospace">Second line in TextRaw</font></span><br/>Third line has underscore (character '_') and dollar sign (character '$')
-
|-
+
-
| [[Image:dialog-information.png]]
+
-
| '''Note:'''  This is note text inside a yellow box <br> <span><font face="monospace">Second line in TextRaw</font></span> <br>Third line has underscore (character '_') and dollar sign (character '$')
+
-
|}
+
-
== Using code listings ==
+
=== Using code listings ===
Use <code>\lstset</code> and <code>\lstinputlisting</code> 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.
Use <code>\lstset</code> and <code>\lstinputlisting</code> 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.
Line 155: Line 137:
   <code>\lstinputlisting{chapters/DocumentationGuidelines/snippets/example_source.c}</code>
   <code>\lstinputlisting{chapters/DocumentationGuidelines/snippets/example_source.c}</code>
-
<code><nowiki>
+
<source lang="c">
-
/*
+
/*
-
* example_source.c, an example source code for kernel module
+
* example_source.c, an example source code for kernel module
-
*
+
*
-
* Copyright (C) 2010 Nokia Corporation. All rights reserved.
+
* Copyright (C) 2010 Nokia Corporation. All rights reserved.
-
*
+
*
-
* This maemo code example is licensed under a MIT-style license,
+
* This maemo code example is licensed under a MIT-style license,
-
* that can be found in the file called "COPYING".
+
* that can be found in the file called "COPYING".
-
*
+
*
-
*/
+
*/
-
#include &lt;linux/module.h&gt; /* needed by all kernel modules */
+
#include <linux/module.h> /* needed by all kernel modules */
-
#include &lt;linux/init.h&gt;   /* needed for custom init/exit functions */
+
#include <linux/init.h>   /* needed for custom init/exit functions */
-
#include &lt;linux/kernel.h&gt; /* needed for KERN_ALERT macro */
+
#include <linux/kernel.h> /* needed for KERN_ALERT macro */
-
/* Special macro to indicate license (to avoid tainting the kernel) */
+
/* Special macro to indicate license (to avoid tainting the kernel) */
-
MODULE_LICENSE("Dual MIT/GPL");
+
MODULE_LICENSE("Dual MIT/GPL");
-
static int hello_init(void) {
+
static int hello_init(void) {
-
printk(KERN_ALERT "Hello, world\n"); /* top priority message */
+
printk(KERN_ALERT "Hello, world\n"); /* top priority message */
-
return 0;
+
return 0;
-
}
+
}
-
static void hello_exit(void)
+
static void hello_exit(void)
-
{
+
{
-
printk(KERN_INFO "Goodbye, world\n");
+
printk(KERN_INFO "Goodbye, world\n");
-
}
+
}
-
/* macros to mark modules init/exit funcs (run on insmod/rmmod) */
+
/* macros to mark modules init/exit funcs (run on insmod/rmmod) */
-
module_init(hello_init);
+
module_init(hello_init);
-
module_exit(hello_exit);
+
module_exit(hello_exit);
-
</nowiki></code>
+
</source>
-
== Using figures ==
+
=== Using figures ===
-
Use <code>\includegraphics</code> for figures without a file name extension. For example, <span><font face="monospace">use image_file_name</font></span> instead of <span><font face="monospace">image_file_name.png</font></span>.
+
Use <code>\includegraphics</code> for figures without a file name extension. For example, use <code>image_file_name</code> instead of <code>image_file_name.png</code>.
Use option <code>[H]</code> for figure environment if the position of the figure related to base text cannot be changed by LaTeX . For example <code>\begin{figure}[H]</code>.
Use option <code>[H]</code> for figure environment if the position of the figure related to base text cannot be changed by LaTeX . For example <code>\begin{figure}[H]</code>.
-
{|
+
{{ambox|text=Use <code>maemodoc-scaleimage</code> command line tool to scale down figure files that are bigger than recommended maximum size of 600 × 1200 (width × height) pixels. Use option <code>[width=\textwidth]</code> when including figures in LaTeX that are wider than 340 pixels.
-
|-
+
-
| [[Image:dialog-information.png]]
+
-
| '''Note:'''  Use <span><font face="monospace">maemodoc-scaleimage</font></span> command line tool to scale down figure files that are bigger than recommended maximum size of 600 x 1200 (width x height) pixels. Use option <code>[width=\textwidth]</code> when including figures in LaTeX that are wider than 340 pixels.
+
|}
|}
Line 211: Line 190:
   <code>\end{figure}</code>
   <code>\end{figure}</code>
 +
<div id="figure-example_picture">
 +
[[Image:LaTeX_logo.png|frame|center|alt=LaTeX logo|'''Figure 4.1:''' Example picture]]
 +
</div>
-
 
+
=== Combining small tables and figures ===
-
{| summary="Example picture"
+
-
|+ align="BOTTOM" |'''Figure 4.1:''' Example picture
+
-
|-
+
-
|
+
-
[[Image:LaTeX_logo.png|Image LaTeX_logo]]
+
-
|}
+
-
 
+
-
 
+
-
 
+
-
== Combining small tables and figures ==
+
You can arrange small tables and figures side-by-side within the page width limitation.
You can arrange small tables and figures side-by-side within the page width limitation.
Line 228: Line 200:
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.
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.
-
<code>\begin{figure}[H]</code>
+
<source lang="latex">
-
<code> \caption{Example logos}</code>
+
\begin{figure}[H]
-
<code> \label{fig:example-chapter-title-example-logos}</code>
+
\caption{Example logos}
-
<code> \centering</code>
+
\label{fig:example-chapter-title-example-logos}
-
<code> \subfloat[ESbox]{</code>
+
\centering
-
<code> \includegraphics{chapters/DocumentationGuidelines/images/esbox_logo}</code>
+
\subfloat[ESbox]{
-
<code> }</code>
+
\includegraphics{chapters/DocumentationGuidelines/images/esbox_logo}
-
<code> \subfloat[PluThon]{</code>
+
}
-
<code> \includegraphics{chapters/DocumentationGuidelines/images/pluthon_logo}</code>
+
\subfloat[PluThon]{
-
<code> }</code>
+
\includegraphics{chapters/DocumentationGuidelines/images/pluthon_logo}
-
<code>\end{figure}</code>
+
}
-
 
+
\end{figure}
-
 
+
</source>
{| summary="Example logos"
{| summary="Example logos"
Line 249: Line 221:
|}
|}
-
 
+
=== Referring to a section ===
-
 
+
-
== Referring to a section ==
+
Use a standard reference <code>\ref</code> 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).
Use a standard reference <code>\ref</code> 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).
Line 266: Line 236:
* For more information on example topic, see chapter [[#Using LaTeX formatting commands]].
* For more information on example topic, see chapter [[#Using LaTeX formatting commands]].
-
== Referring to a figure ==
+
=== Referring to a figure ===
Use standard reference <code>\ref</code> 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).
Use standard reference <code>\ref</code> 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).
Line 273: Line 243:
* For more information on example topic, see figure <code>\ref{fig:example-chapter-title-example-picture}</code>.
* For more information on example topic, see figure <code>\ref{fig:example-chapter-title-example-picture}</code>.
-
* For more information on example topic, see figure [[#fig:formatting-in-latex-example-picture|4.1]].
+
* For more information on example topic, see figure [[#figure-formatting-in-latex-example-picture|4.1]].
-
== Referring to a table ==
+
=== Referring to a table ===
Use standard reference <code>\ref</code> 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).
Use standard reference <code>\ref</code> 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).
Line 284: Line 254:
* For more information on example topic, see table 4.1.
* For more information on example topic, see table 4.1.
-
== Using HTML links ==
+
=== Using HTML links ===
Use <code>\htmladdnormallink</code> for external references that are not included in the Maemo bibliography database. Notice that link text is normal LaTeX text and characters <code>_$#%{}^~</code> need to be handled with special marking but URL can be any normal HTTP link.
Use <code>\htmladdnormallink</code> for external references that are not included in the Maemo bibliography database. Notice that link text is normal LaTeX text and characters <code>_$#%{}^~</code> need to be handled with special marking but URL can be any normal HTTP link.
Line 293: Line 263:
* For more information on example topic, see [http://www.maemo.org maemo.org].
* For more information on example topic, see [http://www.maemo.org maemo.org].
-
== Using Maemo bibliography database ==
+
=== Using Maemo bibliography database ===
Use <code>\cite</code> 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 <code>\htmladdnormallink</code> for references to product version specific documents.
Use <code>\cite</code> 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 <code>\htmladdnormallink</code> 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.
+
Give document name in ''Italics'' before citation from bibliography database and join document name and citation together with tilde (~). Tilde prevents LaTeX from breaking the row between document name end and citation link.
For example:
For example:
Line 303: Line 273:
* For more information on example topic, see document <code>\textit{Maemo Documentation Guidelines}</code><code>~\cite{bibliography-key}</code>.
* For more information on example topic, see document <code>\textit{Maemo Documentation Guidelines}</code><code>~\cite{bibliography-key}</code>.
* For more information on example topic, see document ''Maemo Documentation Guidelines'' <ref name=r4>Maemo Documentation Guidelines. http://library.maemodocs.nokia.com</ref>.
* For more information on example topic, see document ''Maemo Documentation Guidelines'' <ref name=r4>Maemo Documentation Guidelines. http://library.maemodocs.nokia.com</ref>.
-
 
* For more information on example topic, see document <code>\textit{Maemo Documentation Guidelines}</code><code>~\cite[Formatting in LaTex]{bibliography-key}</code>.
* For more information on example topic, see document <code>\textit{Maemo Documentation Guidelines}</code><code>~\cite[Formatting in LaTex]{bibliography-key}</code>.
-
* For more information on example topic, see document ''Maemo Documentation Guidelines'' [[/node7.html#maemo-documentation-guidelines 4], Formatting in LaTex].
+
* For more information on example topic, see document ''Maemo Documentation Guidelines'' [[{{PAGENAME}}|Formatting in LaTex]].
-
== Using normal tables ==
+
=== Using normal tables ===
Use <code>\tabular</code> and <code>\table</code> 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:
Use <code>\tabular</code> and <code>\table</code> 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:
-
<code>\begin{tabular}<nowiki>
+
<source lang="latex">
-
{|p\</nowiki>{0.5\textwidth}<nowiki>|p</nowiki>{0.5\textwidth}<nowiki>|}</nowiki></code>.
+
\begin{tabular}{|p\{0.5\textwidth}|p{0.5\textwidth}|}
 +
</source>
-
To set the width for the whole table, use <code>{tabular*}</code> with option <code>\textwidth</code><nowiki>: </nowiki>
+
To set the width for the whole table, use <code>{tabular*}</code> with option <code>\textwidth</code>:
-
<code>\begin{tabular*}{\textwidth}<nowiki>
+
<source lang="latex">
-
{|c|p</nowiki>{0.5\textwidth}<nowiki>|}</nowiki></code>.
+
\begin{tabular*}{\textwidth}{|c|p{0.5\textwidth}|}
 +
</source>
-
To reduce column width use <code>@{}</code><nowiki>: </nowiki><code>\begin{tabular}<nowiki>
+
To reduce column width use <code>@{}</code>: <code>\begin{tabular}
-
{|@</nowiki>{}c@{}<nowiki>|c|}</nowiki></code>.
+
<nowiki>{|@{}c@{}|c|}</nowiki></code>.
-
To add horizontal lines between cells, use <code>\hline</code>. To separate cells, use <code>&amp;</code>. To change row, use <code>\\</code>.
+
To add horizontal lines between cells, use <code>\hline</code>. To separate cells, use <code>&</code>. To change row, use <code>\\</code>.
Use option <code>[H]</code> for table environment if LaTeX cannot change the position of the table related to base text: <code>\begin{table}[H]</code>.
Use option <code>[H]</code> for table environment if LaTeX cannot change the position of the table related to base text: <code>\begin{table}[H]</code>.
Line 330: Line 301:
For example:
For example:
-
<code>\begin{table}[H]</code>
+
<source lang="latex">
-
  <code> \caption{Example normal table}</code>
+
\begin{table}[H]
-
  <code> \label{tab:example-chapter-title-example-table}</code>
+
  \caption{Example normal table}
-
  <code> \centering</code>
+
  \label{tab:example-chapter-title-example-table}
-
  <code> \begin{tabular}<nowiki>
+
  \centering
-
{|p</nowiki>{0.45\textwidth}<nowiki>|p</nowiki>{0.45\textwidth}<nowiki>|}</nowiki></code>
+
  \begin{tabular}{|p{0.45\textwidth}|p{0.45\textwidth}|}
-
  <code> \hline\hline</code>
+
  \hline\hline
-
  <code> \textbf{Column 1} &amp; \textbf{Column 2} \\</code>
+
  \textbf{Column 1} & \textbf{Column 2} \\
-
  <code> \hline</code>
+
  \hline
-
  <code> % Table data starts from here</code>
+
  % Table data starts from here
-
  <code> %</code>
+
  %
-
  <code> 1 &amp; 2 \\ \hline</code>
+
  1 & 2 \\ \hline
-
  <code> 3 &amp; 4 \\ \hline</code>
+
  3 & 4 \\ \hline
-
  <code> 5 &amp; 6 \\ \hline</code>
+
  5 & 6 \\ \hline
-
  <code> \hline</code>
+
  \hline
-
  <code> \end{tabular}</code>
+
  \end{tabular}
-
<code>\end{table}</code>
+
\end{table}
 +
</source>
-
 
+
{| class="wikitable"
-
 
+
|+ Table 4.1: Example normal table
-
 
+
-
 
+
-
{| border="1" cellpadding="3"
+
-
|+ '''Table 4.1:''' Example normal table
+
|-
|-
-
! width="225" align="LEFT" valign="TOP" | '''Column 1'''
+
! Column 1
-
! width="225" align="LEFT" valign="TOP" | '''Column 2'''
+
! Column 2
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 1
+
| 1
-
| width="225" align="LEFT" valign="TOP" | 2
+
| 2
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 3
+
| 3
-
| width="225" align="LEFT" valign="TOP" | 4
+
| 4
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 5
+
| 5
-
| width="225" align="LEFT" valign="TOP" | 6
+
| 6
|}
|}
-
 
+
=== Using multi-column table rows ===
-
 
+
-
== Using multi-column table rows ==
+
Use <code>\multicolumn</code> 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.
Use <code>\multicolumn</code> 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.
Line 376: Line 342:
For example:
For example:
-
<code>\multicolumn{2}<nowiki>
+
<source lang="latex">
-
{|l|}</nowiki>{\textbf{\textit{Table SubHeader}}} \\ \hline</code>
+
<code>\multicolumn{2}{|l|}{\textbf{\textit{Table SubHeader}}} \\ \hline
 +
</source>
-
 
+
{| class="wikitable"
-
 
+
|+ Table 4.2: Example multicolumn table
-
 
+
-
 
+
-
{| border="1" cellpadding="3"
+
-
|+ '''Table 4.2:''' Example multicolumn table
+
|-
|-
-
! width="225" align="LEFT" valign="TOP" | '''Column 1'''
+
! Column 1
-
! width="225" align="LEFT" valign="TOP" | '''Column 2'''
+
! Column 2
|-
|-
-
| colspan="2" align="LEFT" | <span>'''''SubHeader Left'''''</span>
+
| colspan="2" align="left" | '''''SubHeader Left'''''
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 1
+
| 1
-
| width="225" align="LEFT" valign="TOP" | 2
+
| 2
|-
|-
-
| colspan="2" align="CENTER" | <span>'''''SubHeader Center'''''</span>
+
| colspan="2" align="center" | '''''SubHeader Center'''''
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 3
+
| 3
-
| width="225" align="LEFT" valign="TOP" | 4
+
| 4
|-
|-
-
| colspan="2" align="RIGHT" | <span>'''''SubHeader Right'''''</span>
+
| colspan="2" align="right" | '''''SubHeader Right'''''
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 5
+
| 5
-
| width="225" align="LEFT" valign="TOP" | 6
+
| 6
|}
|}
-
 
+
=== Using long tables ===
-
 
+
-
== Using long tables ==
+
Use <code>{center}</code> and <code>{longtable}</code> 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:
Use <code>{center}</code> and <code>{longtable}</code> 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:
-
<code>\begin{longtable}<nowiki>
+
<source lang="latex">
-
{|p</nowiki>{0.45\textwidth}<nowiki>|p</nowiki>{0.45\textwidth}<nowiki>|}</nowiki></code>.
+
\begin{longtable}{|p{0.45\textwidth}|p{0.45\textwidth}|}
 +
</source>
-
To reduce column width use <code>@{}</code><nowiki>: </nowiki><code>\begin{longtable}<nowiki>
+
To reduce column width use <code>@{}</code>:
-
{|@</nowiki>{}c@{}<nowiki>|c|}</nowiki></code>.
+
<source lang="latex">
 +
\begin{longtable}{|@{}c@{}|c|}
 +
</source>
-
To add horizontal lines between cells, use <code>\hline</code>. To separate cells, use <code>&amp;</code>. To change row, use <code>\\</code>.
+
To add horizontal lines between cells, use <code>\hline</code>. To separate cells, use <code>&</code>. To change row, use <code>\\</code>.
All tables must be centered and have both a caption and a label.
All tables must be centered and have both a caption and a label.
Line 423: Line 387:
For example:
For example:
-
<code>\begin{center}</code>
+
<source lang="latex">
-
  <code> \begin{longtable}<nowiki>
+
\begin{center}
-
{|p</nowiki>{0.45\textwidth}<nowiki>|p</nowiki>{0.45\textwidth}<nowiki>|}</nowiki></code>
+
  \begin{longtable}
-
  <code> \caption{Example long table}</code>
+
{|p{0.45\textwidth}|p{0.45\textwidth}|}
-
  <code> \label{tab:example-chapter-title-example-long-table}</code>
+
  \caption{Example long table}
-
  <code> % FirstHead</code>
+
  \label{tab:example-chapter-title-example-long-table}
-
  <code> \hline\hline</code>
+
  % FirstHead
-
  <code> \textbf{Column 1} &amp; \textbf{Column 2} \\ \hline</code>
+
  \hline\hline
-
  <code> \endfirsthead</code>
+
  \textbf{Column 1} &amp; \textbf{Column 2} \\ \hline
-
  <code> % Head</code>
+
  \endfirsthead
-
  <code> \hline\hline</code>
+
  % Head
-
  <code> \multicolumn{2}<nowiki>
+
  \hline\hline
-
{|l|}</nowiki>{\small\tablename \thetable{} </code>
+
  \multicolumn{2}{|l|}{\small\tablename \thetable{}
-
  <code> Continued from previous page} \\</code>
+
  Continued from previous page} \\
-
  <code> \hline\hline</code>
+
  \hline\hline
-
  <code> \textbf{Column } &amp; \textbf{Column 2} \\ \hline</code>
+
  \textbf{Column } &amp; \textbf{Column 2} \\ \hline
-
  <code> \endhead</code>
+
  \endhead
-
  <code> % Foot</code>
+
  % Foot
-
  <code> \multicolumn{2}<nowiki>
+
  \multicolumn{2}{|r|}{\small\tablename \thetable{}
-
{|r|}</nowiki>{\small\tablename \thetable{} </code>
+
  Continued to next page} \\
-
  <code> Continued to next page} \\</code>
+
  \hline
-
  <code> \hline</code>
+
  \endfoot
-
  <code> \endfoot</code>
+
  % LastFoot
-
  <code> % LastFoot</code>
+
  \hline\hline
-
  <code> \hline\hline</code>
+
  \endlastfoot
-
  <code> \endlastfoot</code>
+
  % Table data starts from here
-
  <code> % Table data starts from here</code>
+
  %
-
  <code> %</code>
+
  1 & 2 \\ \hline
-
  <code> 1 &amp; 2 \\ \hline</code>
+
  3 & 4 \\ \hline
-
  <code> 3 &amp; 4 \\ \hline</code>
+
  5 & 6 \\ \hline
-
  <code> 5 &amp; 6 \\ \hline</code>
+
  ... & ... \\ \hline
-
  <code> ... &amp; ... \\ \hline</code>
+
  \end{longtable}
-
  <code> \end{longtable}</code>
+
\end{center}
-
<code>\end{center}</code>
+
</source>
-
 
+
-
{| border="1" cellpadding="3"
+
{| class="wikitable"
-
|+ '''Table 4.3:''' Example long table
+
|+ Table 4.3: Example long table
|-
|-
-
| width="225" align="LEFT" valign="TOP" | '''Column 1'''
+
! Column 1
-
! width="225" align="LEFT" valign="TOP" | '''Column 2'''
+
! Column 2
|-
|-
-
| width="225" align="LEFT" valign="TOP" |
+
| 1
-
| width="225" align="LEFT" valign="TOP" |
+
| 2
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 1
+
| 3
-
| width="225" align="LEFT" valign="TOP" | 2
+
| 4
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 3
+
| 5
-
| width="225" align="LEFT" valign="TOP" | 4
+
| 6
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 5
+
| 7
-
| width="225" align="LEFT" valign="TOP" | 6
+
| 8
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 7
+
| 9
-
| width="225" align="LEFT" valign="TOP" | 8
+
| 0
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 9
+
| 1
-
| width="225" align="LEFT" valign="TOP" | 0
+
| 2
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 1
+
| 3
-
| width="225" align="LEFT" valign="TOP" | 2
+
| 4
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 3
+
| 5
-
| width="225" align="LEFT" valign="TOP" | 4
+
| 6
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 5
+
| 7
-
| width="225" align="LEFT" valign="TOP" | 6
+
| 8
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 7
+
| 9
-
| width="225" align="LEFT" valign="TOP" | 8
+
| 0
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 9
+
| 1
-
| width="225" align="LEFT" valign="TOP" | 0
+
| 2
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 1
+
| 3
-
| width="225" align="LEFT" valign="TOP" | 2
+
| 4
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 3
+
| 5
-
| width="225" align="LEFT" valign="TOP" | 4
+
| 6
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 5
+
| 7
-
| width="225" align="LEFT" valign="TOP" | 6
+
| 8
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 7
+
| 9
-
| width="225" align="LEFT" valign="TOP" | 8
+
| 0
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 9
+
| 1
-
| width="225" align="LEFT" valign="TOP" | 0
+
| 2
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 1
+
| 3
-
| width="225" align="LEFT" valign="TOP" | 2
+
| 4
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 3
+
| 5
-
| width="225" align="LEFT" valign="TOP" | 4
+
| 6
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 5
+
| 7
-
| width="225" align="LEFT" valign="TOP" | 6
+
| 8
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 7
+
| 9
-
| width="225" align="LEFT" valign="TOP" | 8
+
| 0
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 9
+
| 1
-
| width="225" align="LEFT" valign="TOP" | 0
+
| 2
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 1
+
| 3
-
| width="225" align="LEFT" valign="TOP" | 2
+
| 4
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 3
+
| 5
-
| width="225" align="LEFT" valign="TOP" | 4
+
| 6
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 5
+
| 7
-
| width="225" align="LEFT" valign="TOP" | 6
+
| 8
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 7
+
| 9
-
| width="225" align="LEFT" valign="TOP" | 8
+
| 0
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 9
+
| 1
-
| width="225" align="LEFT" valign="TOP" | 0
+
| 2
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 1
+
| 3
-
| width="225" align="LEFT" valign="TOP" | 2
+
| 4
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 3
+
| 5
-
| width="225" align="LEFT" valign="TOP" | 4
+
| 6
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 5
+
| 7
-
| width="225" align="LEFT" valign="TOP" | 6
+
| 8
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 7
+
| 9
-
| width="225" align="LEFT" valign="TOP" | 8
+
| 0
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 9
+
| 1
-
| width="225" align="LEFT" valign="TOP" | 0
+
| 2
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 1
+
| 3
-
| width="225" align="LEFT" valign="TOP" | 2
+
| 4
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 3
+
| 5
-
| width="225" align="LEFT" valign="TOP" | 4
+
| 6
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 5
+
| 7
-
| width="225" align="LEFT" valign="TOP" | 6
+
| 8
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 7
+
| 9
-
| width="225" align="LEFT" valign="TOP" | 8
+
| 0
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 9
+
| 1
-
| width="225" align="LEFT" valign="TOP" | 0
+
| 2
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 1
+
| 3
-
| width="225" align="LEFT" valign="TOP" | 2
+
| 4
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 3
+
| 5
-
| width="225" align="LEFT" valign="TOP" | 4
+
| 6
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 5
+
| 7
-
| width="225" align="LEFT" valign="TOP" | 6
+
| 8
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 7
+
| 9
-
| width="225" align="LEFT" valign="TOP" | 8
+
| 0
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 9
+
| 1
-
| width="225" align="LEFT" valign="TOP" | 0
+
| 2
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 1
+
| 3
-
| width="225" align="LEFT" valign="TOP" | 2
+
| 4
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 3
+
| 5
-
| width="225" align="LEFT" valign="TOP" | 4
+
| 6
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 5
+
| 7
-
| width="225" align="LEFT" valign="TOP" | 6
+
| 8
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 7
+
| 9
-
| width="225" align="LEFT" valign="TOP" | 8
+
| 0
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 9
+
| 1
-
| width="225" align="LEFT" valign="TOP" | 0
+
| 2
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 1
+
| 3
-
| width="225" align="LEFT" valign="TOP" | 2
+
| 4
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 3
+
| 5
-
| width="225" align="LEFT" valign="TOP" | 4
+
| 6
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 5
+
| 7
-
| width="225" align="LEFT" valign="TOP" | 6
+
| 8
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 7
+
| 9
-
| width="225" align="LEFT" valign="TOP" | 8
+
| 0
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 9
+
| 1
-
| width="225" align="LEFT" valign="TOP" | 0
+
| 2
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 1
+
| 3
-
| width="225" align="LEFT" valign="TOP" | 2
+
| 4
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 3
+
| 5
-
| width="225" align="LEFT" valign="TOP" | 4
+
| 6
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 5
+
| 7
-
| width="225" align="LEFT" valign="TOP" | 6
+
| 8
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 7
+
| 9
-
| width="225" align="LEFT" valign="TOP" | 8
+
| 0
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 9
+
| 1
-
| width="225" align="LEFT" valign="TOP" | 0
+
| 2
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 1
+
| 3
-
| width="225" align="LEFT" valign="TOP" | 2
+
| 4
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 3
+
| 5
-
| width="225" align="LEFT" valign="TOP" | 4
+
| 6
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 5
+
| 7
-
| width="225" align="LEFT" valign="TOP" | 6
+
| 8
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 7
+
| 9
-
| width="225" align="LEFT" valign="TOP" | 8
+
| 0
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 9
+
| 1
-
| width="225" align="LEFT" valign="TOP" | 0
+
| 2
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 1
+
| 3
-
| width="225" align="LEFT" valign="TOP" | 2
+
| 4
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 3
+
| 5
-
| width="225" align="LEFT" valign="TOP" | 4
+
| 6
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 5
+
| 7
-
| width="225" align="LEFT" valign="TOP" | 6
+
| 8
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 7
+
| 9
-
| width="225" align="LEFT" valign="TOP" | 8
+
| 0
|-
|-
-
| width="225" align="LEFT" valign="TOP" | 9
+
| ...
-
| width="225" align="LEFT" valign="TOP" | 0
+
| ...
-
|-
+
-
| width="225" align="LEFT" valign="TOP" | ...
+
-
| width="225" align="LEFT" valign="TOP" | ...
+
-
|-
+
-
| width="225" align="LEFT" valign="TOP" |
+
-
| width="225" align="LEFT" valign="TOP" |
+
|}
|}
-
 
+
=== Reducing the size of tables and figures ===
-
 
+
-
== 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.
You can reduce the size of tables and figures that do not fit on the page without scaling them down.
-
{|
+
{{ambox|text=Scaling and rotating does not work with tables, and reducing font size does not work with figures.}}
-
|-
+
-
| [[Image:dialog-information.png]]
+
-
| '''Note:'''  Scaling and rotating does not work with tables, and reducing font size does not work with figures.
+
-
|}
+
If the object is too long or wide, you can:
If the object is too long or wide, you can:
Line 689: Line 640:
* scale down the figure
* scale down the figure
-
=== Reduce the size of the table ===
+
==== 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:
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:
-
<span><font face="monospace">Huge</font></span>, <span><font face="monospace">huge</font></span>, <span><font face="monospace">LARGE</font></span>, <span><font face="monospace">Large</font></span>, <span><font face="monospace">large</font></span>, <span><font face="monospace">normalsize</font></span>, <span><font face="monospace">small</font></span>, <span><font face="monospace">footnotesize</font></span>, <span><font face="monospace">scriptsize</font></span> and <span><font face="monospace">tiny</font></span>.
+
<code>Huge</code>, <code>huge</code>, <code>LARGE</code>, <code>Large</code>, <code>large</code>, <code>normalsize</code>, <code>small</code>, <code>footnotesize</code>, <code>scriptsize</code> and <code>tiny</code>.
-
=== Rotate and scale down a figure ===
+
==== 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.
+
To fit on the page, figures in Maemo documents are recommended to have maximum size of 600 × 1200 (width × 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 <span><font face="monospace">maemodoc-scaleimage</font></span> command line tool for them to be readable also in HTML documents.
+
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 <code>maemodoc-scaleimage</code> command line tool for them to be readable also in HTML documents.
-
{|
+
{{ambox|text=Use <span><font face="monospace">maemodoc-scaleimage</font></span> command line tool to scale down figure files that are bigger than recommended maximum size of 600 × 1200 (width × height) pixels. Use option <code>[width=\textwidth]</code> when including figures in LaTeX that are wider than 340 pixels.}}
-
|-
+
-
| [[Image:dialog-information.png]]
+
-
| '''Note:'''  Use <span><font face="monospace">maemodoc-scaleimage</font></span> command line tool to scale down figure files that are bigger than recommended maximum size of 600 x 1200 (width x height) pixels. Use option <code>[width=\textwidth]</code> when including figures in LaTeX that are wider than 340 pixels.
+
-
|}
+
-
Figures which are smaller than 340 x 1200 (width x height) pixels do not need to be scaled down either in LaTeX or with <span><font face="monospace">maemodoc-scaleimage</font></span> tool.
+
Figures which are smaller than 340 × 1200 (width × height) pixels do not need to be scaled down either in LaTeX or with <code>maemodoc-scaleimage</code> tool.
For example, the following command scales a figure down to the recommended maximum width and height.
For example, the following command scales a figure down to the recommended maximum width and height.
-
  $ ./maemodoc-scaleimage &lt;image_file&gt; -outpath &lt;output directory&gt;
+
  $ ./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.
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 &lt;image_file&gt; -outpath &lt;output directory&gt; -rotate
+
  $ ./maemodoc-scaleimage <image_file> -outpath <output directory> -rotate
 +
== References ==
-
 
-
== References ==
 
<references />
<references />
[[Category:Documentation]]
[[Category:Documentation]]

Latest revision as of 15:48, 9 November 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 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.

Contents

[edit] Using LaTeX formatting commands

[edit] Using list of tables

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

[edit] Using list of figures

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

[edit] Using LaTeX special characters

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

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

Image:Ambox_notice.png
\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.

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

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

[edit] 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}

[edit] 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

[edit] Using command line and screen output examples

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

Image:Ambox_notice.png
{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 '$')

[edit] Using notes

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

Image:Ambox_notice.png
{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 '$')

[edit] 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);

[edit] 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

[edit] 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}
Figure 4.2: Example logos

[ESbox] File:Esbox logo.png [PluThon] File:Pluthon logo.png

[edit] 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 \ref{sec:example-chapter-title-example-section-title}.
  • For more information on example topic, see chapter #Using LaTeX formatting commands.

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

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

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

[edit] 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 from breaking the 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 Formatting in LaTex.

[edit] 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}
Table 4.1: Example normal table
Column 1 Column 2
1 2
3 4
5 6

[edit] 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
Table 4.2: Example multicolumn table
Column 1 Column 2
SubHeader Left
1 2
SubHeader Center
3 4
SubHeader Right
5 6

[edit] 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} &amp; \textbf{Column 2} \\ \hline
 \endfirsthead
 % Head
 \hline\hline
 \multicolumn{2}{|l|}{\small\tablename \thetable{}
 Continued from previous page} \\
 \hline\hline
 \textbf{Column } &amp; \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}


Table 4.3: Example long table
Column 1 Column 2
1 2
3 4
5 6
7 8
9 0
1 2
3 4
5 6
7 8
9 0
1 2
3 4
5 6
7 8
9 0
1 2
3 4
5 6
7 8
9 0
1 2
3 4
5 6
7 8
9 0
1 2
3 4
5 6
7 8
9 0
1 2
3 4
5 6
7 8
9 0
1 2
3 4
5 6
7 8
9 0
1 2
3 4
5 6
7 8
9 0
1 2
3 4
5 6
7 8
9 0
1 2
3 4
5 6
7 8
9 0
1 2
3 4
5 6
7 8
9 0
1 2
3 4
5 6
7 8
9 0
... ...

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

Image:Ambox_notice.png
Scaling and rotating does not work with tables, and reducing font size does not work with figures.

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

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

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

[edit] Rotate and scale down a figure

To fit on the page, figures in Maemo documents are recommended to have maximum size of 600 × 1200 (width × 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.

Image:Ambox_notice.png
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.

Figures which are smaller than 340 × 1200 (width × 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

[edit] References

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