Guidelines for coding style of LaTeX files for the manual

---

The guidelines can be discussed on the LatexGuidelinesTalk page.

---

Language

General

• Use British English. Consistency is more important than the fact that a particular variant of a language be supported, and British people are expected to use manuals in American English all the time. This is not an unreasonable burden. In general this means that most words ending in "or" should end "our" and most words ending "ize" should end "ise".

• Try to avoid writing in the second person. So "to do this the configuration file needs to be edited" is preferred to "you must edit your configuration file in order to do this".

• The manual is aimed at end users. Technical information of interest to hackers is therefore left for the wiki for now. If someone wants to write more technical documentation, that's great. The manual, however, should remain focused on a more general audience.

• Don't overwrite the styles! In general you should use the defined macros to emphasize words (\emph), filenames (\fname), hyperlinks (\url) and so on. The exact style is defined in those macros and shouldn't be overridden to get a consistent look of the manual!

• If in doubt, find something similar in the manual. The Jukebox comparison table and the explanatory numbered list for the Split Editor are one off exceptions, and should not therefore be taken as examples of general good style. If still in doubt, ask.

Quotes

British writing uses "smart quotes" quotation marks. They are coded in LaTeX as (two backticks) for the opening quotation mark and '' (two apostrophes) for the closing quotation mark

Ellipsis

An Ellipsis usually indicates an omitted part in the text. It's always three dots and coded as

\ldots

Hyphens

English typesetting has three different types of hyphens.

• The short hyphen to break words over lines. This one is written as single hyphen - in LaTeX
• The longer hyphen indicating changes in the sentence, for example something thats entered as a sidenote. This is written as two hypens --
• The longest hyphen. This one is written as three hyphens --- and is not separated to the previous and the following word with a space.

Names

Manufacturer and product names are formatted in accordance with the standard rules of English grammar e.g. "Ipod playback is currently unsupported", "This feature is not available for the Iriver H120". In general these should be defined in macros in the platform specific LaTeX files. Manufacturer and model names are proper nouns, and should thus begin with a capital letter.

---

Sectioning

To be discussed.

---

Tables

Button mapping tables ("button map")

There is now an environment helping to unify all button map tables. Use it as following:

\begin{table} % this is still needed! Don't put position modifiers here!
\begin{btnmap}{mapping table caption)}{mapping table label}
\ButtonStop & Stops playback \\
...
\ButtonPlay & Starts playback \\
\end{btnmap}
\end{table}

Note: you need to end the last line with \\. To suppress caption / label leave them empty.

Generic tables

To provide a consistent look, all tables should be created using the rbtabular environment. This environment correctly fills the headers with colors, sets the horizontal rules and provides alternating colors for table rows. Example:

\begin{rbtabular}{\textwidth}{lX}{Head 1 & Head 2}{Caption}{Label}
% your table goes here
\end{rbtabular}

The first parameter ( \textwidth in the example) specifies the width of the table, the second specifies the format of the columns (same syntax as in the latex package tabularx). Then follow the headers (must match the columns' formats), and then the caption and the label (for referencing to this table from other places in the manual). The last two parameters may be left blank, but the braces should still be present.

When you create the table this way you don't need any hline, toprule or the like. The environment does this all for you!

---

Lists

Lists in general use the unnumbered list style. Don't use line breaks in lists unless there's a good reason (Extra paragraphs under a buller point are normally formatted as unbulleted items in the list. This makes the spacing uniform.) Avoid numbered lists if you can.

---

Descriptions

Description lists have previously set as itemize. This shouldn't be used anymore, use description instead. The description itself goes as optional argument for \item. Also, we decided to write a full stop after the description, not a colon. Thus, we get something like "Bookmark. To create a bookmark ...", not "Bookmark: To create ...". For better readability of the source put the separating space out of the argument like in the example below (and not "\item[Bookmark. ]To create ...")

\begin{description}
\item[Bookmark.] To create a bookmark ...
\end{description}

These won't be bulleted anymore. It has still to be decided if we want to change the style to use bullet signs again, but you really should use description

---

Include/Exclude sections

To include a section of text for a specific target or feature, use the \opt command. Note: opt introduces unwanted spaces when followed by line breaks. If you break a line directly after an \opt command, you need to end that line with a comment mark % to avoid that unwanted spaces, especially if that opt is followed by more opt lines! Thus it is recommended to end all opt's with a trailing comment sign. If you want to break an overly long \opt "list" you also need to use the % at the end of the line to sort of escape the line feed. Otherwise the item before or after the line break will be ignored depending on the position of the comma.

\opt{HAVE_LCD_COLOR,ondio}{This text will only be included in the manual for targets with color lcd's and ondios}

Excluding a section is done in a similar way, but for this the opt command is used.

opt{iriver}{This is included for all targets except irivers}

All the current defined features are to be found within the platform files in the /manual/platform folder. Look at the keywords in the def and edef lines. There is also the possibility to use all the features defined to enable or disable strings in the language files in /apps/features.txt. This file will be parsed automatically to a features.tex in the manual build folder and contains the usable options for the specified target. It's very handy for excluding or including parts that apply to a certain hardware set, e.g. only colour screens.

---

Markup

Emphasizing

Emphasize a word / sentence with \emph{}. Do not use \textbf{}.

Font variants

Do not use \textsc{} to get small caps. This will produce heavy HTML code. Use \caps{} instead. Generally, you should avoid to use font formatting directly in the text itself but use style macros like \setting{} unless it's unavoidable.

Notes

Use the ote macro for setting notes. They will automatically get the "Note:" added and have an icon on the margin so the reader can catch them pretty quick. Within a note do not use \textbf to emphasize parts, use only \emph instead!

ote{Your note text goes here}

Warnings

If you want to write a warning, use the \warn macro. This behaves similar to ote indicating this text is a warning using an icon alongside the text.

\warn{Don't drop your player!}

Fixme Note

If you want to highlight a part of the text that needs attention, use the \fixme macro. This will highlight the text within the curly braces in red.

\fixme{This needs some serious attention}

Tags/Config

Use the \config macro to emphasize a wps tag or a config setting.

\config{\%xx}

Code block

When writing blocks of code meant to be written in a terminal or terminal output, use the code environment. This will format the code in a consistent way. You have to indent the code with 4 spaces, as the first 4 are stripped.

\begin{code}
    ipod_fw -g nano -o rockboot.bin -i apple_os.bin bootloader-nano.bin
\end{code}

Example block

When you want to give an example on e.g. wps files or config files, use the example environment. You have to indent the example with 4 spaces, as the first 4 are stripped.

\begin{example}
    # Example configuration file
    volume: 70
    bass: 11
    treble: 12
    balance: 0
\end{example}

Menu entries and options

Menu options and configuration option names should use the macro \setting. Deeper paths use an arrow, which is coded as $\rightarrow$. Write the same casing as the entries on the device, which is atm uppercase every first letter of menu entries. If we want to change the style we can do this later in the preamble.

\setting{General Settings $\rightarrow$ Playback}

File names

Filenames and paths (with trailing /) should use the \fname macro. Paths use the unix' style "slash" as directory delimiter, not Windows backslash! To escape special characters, put a backslash before them.

\fname{/.rockbox}

is rendered as /.rockbox

\fname{/.rockbox/folder\_advance\_list.txt}

is rendered as /.rockbox/folder_advance_list.txt

Hyperlinks

Hyperlinks aren't underlined. This is handled in the pre-amble so you generally don't need to worry about it.

• Simply use the \url macro for all links. Please note that all links should be written as a complete URL, i.e. usually having the prefix "http://".

\url{http://www.rockbox.org}

• use the \wikilink macro for linking to wiki pages. This makes it a bit easier to write and also removes a problem with \opt's in the \url macro. The only argument is the wiki name of the page to link to.

\wikilink{LatexGuidelines}

---

Images

• Use png as file format for bitmaps
• For non-screenshot images (few and far between), use \includegraphics[width=12cm]{path/to/graphic.png}

The specified width will be used in the pdf.

Screenshots

• Use the following scheme for screenshot files: The files are named "ss-<name>-<resolution>.png" where <name> is your filename and <resolution> the complete resolution in pixels with color depth. I.e. for H1xx (2 bit grayscale, 160x128 px display) the solitaire plugin screenshot it named "ss-solitaire-160x128x2.png"
• Deprecated: the use of \genericimg for the resolution, i.e. the solitaire plugin should be included with "ss-solitaire-\genericimg.png". This gets expanded for all targets to use the correct resolution, so you don't need to bother about picking the correct one (assuming you added the correct screenshots)
• New: the filename gets the generic extension "-\genericimg.png", which expands as described above added automatically. If no file with the expanded name is found the given argument is tried as filename. This means the old behaviour described above still works but you are strongly encouraged to move to the new type.
• Use the \screenshot macro when including screenshots. The syntax is \screenshot{filename (without \genericimg and filename extension)}{caption}{label}. It is encouraged to use captions. Example:

     \screenshot{rockbox_interface/images/ss-file-menu}{The file menu}{fig:filemenu}
     

  If the image is not found an error is printed out (look for "Missing image: ") and it gets replaced with a "Warning! Image not found" in the text. All path names are relative to the manual folder.

SVG images

To include svg images they need to be converted.

• convert to pdf for use with the pdf version of the manual:
  1. open svg file with inkscape
  2. select everything
  3. save as eps
  4. use epstopdf to convert the eps to pdf format
• convert to png for the html version of the manual
  1. open svg file and select all like above
  2. "export bitmap" as png

---

Labels

If you place a label somewhere, please stick to the following rules. Labels should be named by the context in which they are placed.

• Section: sec:my_section
• Figure: fig:my_figure
• Table: tab:my_table

Labels should be all lowercase using an underscore as a separator. It is recommended to use the section name as label in the first place. If this isn't distinguishing enough prepend it with the section name a level above. I.e. the Xobox plugin section would be labeled "sec:xobox" or, if we need to specify this more, "sec:plugins_xobox". The screenshot for xobox would be labeled "fig:xobox". If there are additional screenshots they would be called "fig:xobox2" or "fig:xobox_2".

Do not reference the labels with \pageref, use \reference instead. pagerefs won't work on the html version of the manual as there are no page numbers. \reference will format the reference according to the manual type selected.

\reference{sec:my_section}

---

File structure

"Coding" style

• Indent with spaces only.
• Files are Unix style. If your editor doesn't support this get a better one. gvim is a nice way of editing files (even on windows!)
• Don't write more than 80 characters per line unless you can't break the line in a readable way.

Directory structure

tbd.

---

Macros you should use

• Use the \dap or daps macro when referring to devices generically, e.g. "The \dap{} will now reboot", "The \daps{} hard disk..."
• \playername expands to the player name (e.g. "Iriver H100")
• \firmwarefilename is used for the targets firmwares filename
• generally: all style macros mentioned above.

---