Index page for the LateX documentation of rockbox.

LaTeX and Rockbox

The Rockbox manual is, as of February 2006, written in LaTeX. This is done to further benefit from the collaborative effort of the open source community. We now have the opportunity to make target specific manuals, maintained by the users as changes to the manual are preferably sent to the patch tracker. In simple terms, it is possible to keep the manual equally up-to-date as the rest of Rockbox.

What LaTeX is

LaTeX is a document preparation system. It is not WYSIWYG. Instead, text is entered in a normal text-editor and keywords are used to structure the document. For instance:

\section{This is a section}
Some text
\subsection{This is a subsection}
Some more text

LaTeX Style Guidelines

Setting up a working environment

Download the rockbox source

In order to be able to build the manual, you need most of the rockbox source code, so the best way of starting with the documentation effort would be to checkout the whole source from the SVN repository :

svn co svn://svn.rockbox.org/rockbox/trunk/ rockbox

For more information about how to use SVN, check the UsingSVN page.

Install LaTeX

LaTeX must be installed for the manual to be built - see the section "How do I install LaTeX?" below for more details

Build the manual

Create a directory at the same level as the Rockbox SVN root. That is, at the same level as tools, apps, manual etc are located.

mkdir h300-man
cd h300-man

../tools/configure

make manual

• for building the html manual, use the makefile target manual-html. The output will be placed into a subfolder html
• for building a zipped version of the html manual use manual-zip.
• building the pdf version now also has the target manual-pdf which is equivalent to a simple make call

• set SPLITHTML=1 to generate a single file html manual
• the default, SPLITHTML=2 splits up the manual into chapters so you won't have a single huge page.
• you can increase SPLITHTML even more, resulting in the manual even more split up if you feel a need for this.

SPLITHTML=1 make manual-zip

Targets

The current targets are:

player: Archos Player/Studio
recorder: Archos Recorder 6, 10, 20
recorderv2fm: Archos Recorder V2/FM
ondio: Archos Ondio SP/FM
h1xx: iRiver iHP-100,iHP-115, H120, H140
h300: iRiver H320, H340
ipod4g: iPod 4G (grayscale)
ipodcolor: iPod Color (4G)
ipodnano: iPod Nano
ipodvideo: iPod Video (5G)
x5: iAudio X5
e200: Sandisk Sansa e200 Series
gigabeatf: Toshiba Gigabeat F Series

How do I add a target/feature specific section of text to the manual?

To be able to add a section of text that is only valid for a certain target or feature, you use the \opt keyword. For instance, this will place the text I am a player if player was chosen as target. I am a recorder will be used if recorder or recorder2fm was selected. And finally I am an iriver will be used if h1xx or h300 was chosen.

\opt{player}{\textbf{I am a player}}
\opt{recorder,recorderv2fm}{\textbf{I am a recorder}}
\opt{h1xx,h300}{\textbf{I am an iriver}}

If you write a section that is only valid for targets with software decoding of audio files, you would then use the SWCODEC option. Example:

\opt{SWCODEC}{
\section{Equalizer}
The equalizer is a parametric....
}

Then, the Equalizer section will only be included in the manuals where the SWCODEC option is defined in the platform file.

Platform files

Several macros and options are defined in the platform files found in the manual/platform directory. E.g. if you need to write a targets firmware filename, you would use the \firmwarefilename macro. When compiling the manual, then this will be exchanged with rockbox.iriver if the target selected is one of the irivers. Have a look at the platform files for reference on what options and macros that are defined.

What are the rules for a separate manual?

1. If two builds have different keymappings, they get a separate manual
2. If two builds have different screenshots, they get a separate manual
3. If it has indentical keymaps and screenshots, but there is a significant difference in operation that could lead to confusion, they get a separate manual (thus recorder and recorder v2 get separate manuals because the charging systems work differently).
4. If two players are similar but differ in terms of features, they get a separate manual (ondio fm, ondio sp)

How may I help?

The current state of the manual is quite useful as a reference document for using Rockbox. But we always need help keeping the manual synced with the changes made to Rockbox (which happens at a pace faster than we can keep up with most of the time).

• With the introduction of the main menu as a starting point, a restructuring of the manual is in a planning phase. Take a look at the discussions in the dev ml and on the ManualStructureTalk page.
• Screenshots of Rockbox in action is needed, and these are preferred in the .PNG format, with Rockbox settings reset to their default values.
• If you find fixmes or sections missing, please write and upload your changes to the patch tracker. In case you do not know LaTeX, we are happy with plain text as well. The same applies for factual information that is wrong, or spelling errors.

Also take a look at the now outdated ManualTodo for hints on what could be done.

Guidelines

Creating a patch

See WorkingWithPatches for info on creating and applying patches. To include new screenshots, simply create a zip of the added screenshots. E.g.

zip images.zip manual/chapter5/images/h1xx/ss_solitaire.png

Discussion

Work in progress

As you might know, the current state of the manual is not really release material. The Work-in-progress list has been moved to the ManualTodo. Daily versions of the manual are avaliable at http://www.rockbox.org/manual.shtml

LaTeX help

A good starter is The not so short introduction to LaTeX.

How do I install LaTeX?

Linux

LaTeX should be available as packages on all common Linux distributions. You need to install unicode support for LaTeX. This is usually a separate package, if you can't find it you can get the required files here: http://www.unruh.de/DniQ/latex/unicode/ and just follow the helpful install instructions.

If you are running Debian, Ubuntu or another Debian-based Linux:

# apt-get install tetex-base tetex-bin tetex-extra latex-ucs

On Gentoo:

# emerge tetex latex-unicode

On Fedora:

# yum install tetex tetex-latex tetex-unicode

Note that tetex (the primary TeX distribution for Linux systems) is a large package that will take some time to download, build and install.

Windows / native

Windows / Cygwin

TeTeX and TeTeX-extras are available as Cygwin packages, and this is all you need to be able to compile the manual. There seems to be no pre-built package for unicode support so you have to install the files manually (see Linux).

Windows editor

Links

A nice resource of frequently asked questions from the UK TeX Users' Group.

Tutorials on LaTeX.