Documentation/Maemo Documentation Guidelines/Formatting in LaTeX

= 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: 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  tag on the next row after the referenced element tag (like  ).

For references, use  tag with a unique label.

= Using LaTeX formatting commands =

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

Using list of figures
Use  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  or   to highlight command line examples, function names, and file names in base text. The difference between these two is that  allows normal LaTeX commands inside text will be ignored and handled as plain text.

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

For example:


 * Function.
 * Function example_function_name.


 * Command.
 * Command $ mkdir ~/folder.


 * File.
 * File.

Using highlight for important words
Use Italics for other than command line examples and function or file names.

For example:


 * This is.
 * 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.
 * 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:

Section:

Subsection:

Subsubsection:

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:


 * Example level 4 title
 * Example level 4 title

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

Explicit new lines need to be given inside   environment to separate different rows. LaTeX special characters need to be handled in text with special marking unless they are used inside   command.

For example:

&lt;empty line is required before graybox&gt;

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

Using notes
Use  environment for notes that require whole sentence or paragraph to be highlighted.

Explicit new lines need to be given inside   environment to separate different rows. LaTeX special characters need to be handled in text with special marking unless they are used inside   command.

For example:

This is note text inside a yellow box

Using code listings
Use  and   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:

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

Use option  for figure environment if the position of the figure related to base text cannot be changed by LaTeX. For example.

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

For example:

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.

Referring to a section
Use a standard reference  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.
 * For more information on example topic, see chapter.

Referring to a figure
Use standard reference  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.
 * For more information on example topic, see figure 4.1.

Referring to a table
Use standard reference  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.
 * For more information on example topic, see table 4.1.

Using HTML links
Use  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.
 * For more information on example topic, see maemo.org.

Using Maemo bibliography database
Use  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  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.
 * For more information on example topic, see document Maemo Documentation Guidelines .


 * For more information on example topic, see document.
 * For more information on example topic, see document Maemo Documentation Guidelines [[/node7.html#maemo-documentation-guidelines 4], Formatting in LaTex].

Using normal tables
Use  and   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:

.

To set the width for the whole table, use  with option  :

.

To reduce column width use :.

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

Use option  for table environment if LaTeX cannot change the position of the table related to base text:.

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

For example:

Using multi-column table rows
Use  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:

Using long tables
Use  and   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:

.

To reduce column width use :.

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

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

For example:

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 &lt;image_file&gt; -outpath &lt;output directory&gt;

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