Guidelines for coding style of LaTeX files for the manual

This are preliminary guidelines. This is currently work in progress. There is a discussion on LatexGuidelinesTalk

Also this includes some guidelines on how to write the text itself.

Language

General

• Use British English. Since most of the manual is currently in British English, changing it back would be a considerable effort. 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 or 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 hypen to break words over lines. This one is written as single hyphen - in LaTeX
• The longer hypen indicating changes in the sentence, for example something thats entered as a sidenote. This is written as two hypens --
• The longest hypen. 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 avaiable 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

tbd.

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

Tables are formatted using the tabularx package. Usually a table takes the whole width of the page, resulting in

\begin{tabularx}{\textwidth}{lX}
% your table goes here
\end{tabularx}

We also use the booktabs package for the tables. To get a uniform look, we use the \toprule, \midrule and \bottomrule to define the lines in a table. E.g.

\begin{tabularx}{\textwidth}{lX}\toprule
tableheader \\ \midrule
% your table goes here
\bottomrule
\end{tabularx}

Table headers

fixme: define a macro for this, \thead or similar.

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.

\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 \nopt command is used.

\nopt{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.

Markup

Emphasizing

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

Notes

Use the \note 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!

\note{Your note text goes here}

Warnings

If you want to write a warning, use the \warn macro. This behaves similar to \note 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 empasize 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 consistant 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!

\fname{/.rockbox}

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 URI, 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

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.

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