release
dev builds
extras
themes manual
wiki
device status forums
mailing lists
IRC bugs
patches
dev guide



Search | Go
Wiki > Main > RockboxManual > ManualHowto

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

The style guidelines for formatting the LaTeX sources can be found on LatexGuidelines. To make the code consistent all LaTeX files should follow these guidelines. As the existing code suffers from the conversion from OpenOffice, old code should be adjusted to that guidelines as well.


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 Git repository :
git clone git://git.rockbox.org/rockbox
This will create a rockbox subdirectory in the current directory : it is the root directory of your working copy of the Rockbox source code.

For more information about how to use Git, check the UsingGit page.

Install LaTeX

See LatexInstallation

Windows editor

When running Windows, you might want to use TeXnicCenter as your editor. It is like an IDE for LaTeX with buttons for compiling, viewing and some text formatting. Of course this is completely optional, since LaTeX is just plain text.

Build the manual

Create a directory at the same level as the Rockbox root. That is, at the same level as tools, apps, manual etc are located.
mkdir h300-man
cd h300-man
Now, it's time to select target for the manual. Do the following, and follow the on-screen instructions. Note: you can select (M)anual or (N)ormal, which makes it possible building the manual with your normal build tree. The (M)anual option might get removed at one point. You always need to use one of the make targets mentioned below, running make without a target will build the main Rockbox binary!
../tools/configure
This will generate a Makefile, and to finally build the manual do:
make manual
With the introduction of the HTML version of the manual there are now some new targets to make:

  • manual-html for building the html manual. The output will be placed into a subfolder html. You need TeX4ht for this to work.
  • manual-zip for building a zipped version of the html manual.
  • manual-pdf is an alternative for building the pdf version. This is is equivalent to the manual target.
  • manual-txt for building the txt version of the manual. Note: the txt version first builds the html manual, then converts it using links. Most distributions use elinks instead, make sure there's an appropriate symlink (Ubuntu has been reported to not set that up).
Also, you can control the HTML generation a bit:
  • 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.
Thus, if you want to build the HTML manual zipped with a single file build it with
SPLITHTML=1 make manual-zip
Be aware that building the HTML version relies on TeX4ht which does the complete processing.


Dealing with multiple targets

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}}
(the \textbf keyword, makes the text within the {} bold.)

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). 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 as well as spelling and grammar mistakes.

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

Guidelines

See LatexGuidelines.

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

See LatexGuidelinesTalk


Helpful links

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

A newbie guide to LaTeX. This covers the basics and is presented in a nice way.

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

Tutorials on LaTeX.


r92 - 24 Jan 2012 - 12:27:58 - MarcinBukat

Parents: RockboxManual
Copyright by the contributing authors.