Guidelines for coding style of LaTeX files for the manual

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

Ellipsis

\ldots

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

Sectioning

To be discussed.

Tables

Button mapping tables ("button map")

\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}

Generic tables

\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

Lists

Descriptions

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

Include/Exclude sections

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

\nopt{iriver}{This is included for all targets except irivers}

Markup

Emphasizing

Notes

\note{Your note text goes here}

Warnings

\warn{Don't drop your player!}

Fixme Note

\fixme{This needs some serious attention}

Tags/Config

\config{\%xx}

Code block

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

Example block

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

Menu entries and options

\setting{General Settings $\rightarrow$ Playback}

File names

\fname{/.rockbox}

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

Hyperlinks

• 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
• For non-screenshot images (few and far between), use \includegraphics[width=12cm]{path/to/graphic.png}

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

• 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. save as png

Labels

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

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

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.