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



Wiki > Main > ManualHowto (compare)

Difference: ManualHowto (r91 vs. r90)

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 SVN repository :

svn co svn://svn.rockbox.org/rockbox/trunk/ 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 SVN, check the UsingSVN page.

Install LaTeX

LaTeX should be available as packages on all common Linux distributions. Recent distributions have support for unicode. If you use an older distribution you might need to install unicode support manually. You need to have unicode support for LaTeX to build the manual.

manually installing unicode support

If your LaTeX distribution doesn't support unicode you can install http://www.unruh.de/DniQ/latex/unicode/ and just follow the install instructions. Note that this will use the name "utf8x" instead of "utf8" for the inputenc package. To use it you need to change the inputenc line in the preamble.

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

# apt-get install texlive-latex-base texlive-binaries texlive-latex-extra tex4ht

Note: "texlive-latex-extra" now also contains the previous "latex-ucs" package.

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

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

You may need latex-xcolor as well.

On Gentoo:

# emerge tetex latex-unicode

On Fedora:

# yum install tetex tetex-latex tetex-unicode

On Arch:

# pacman -S texlive-core texlive-latexextra texlive-htmlxml

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

Mac OS X

For a native TeX distribution, try MacTeX. There's more information about TeX and LaTeX on OS X here.

Windows / MiKTeX?

For a native TeX distribution try MiKTeX. Building the manual requires a couple of tools (make, perl, etc) which you need to have running on your machine. An alternative is to simply use Cygwin which includes all the required tools. You can also use MiKTeX? in conjunction with Cygwin:

  • Install MiKTeX (the basic version is sufficient)
  • Install Cygwin but without any LaTeX packages (teTeX packages)
  • Open the Cygwin shell and extend the PATH variable by the path to the MiKTeX bin folder. In my case this looks like the following:
    export PATH=/cygdrive/c/Program\ Files/MiKTeX\ 2.9/miktex/bin/:$PATH
  • Continue to configure for a manual build and run make as stated below.

Windows / Cygwin with teTeX

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 / Cygwin with TeXLive?

  • Install Cygwin with at least the following packages: make, gcc (or gcc4), subversion, perl, wget
  • Make sure you don't have teTeX installed. If you previously installed it with Cygwin uninstall it first.
  • install TeXLive? (medium scheme) using the non-Windows installer install-tl-unx.tar.gz according to the TeXLive? website (from Cygwin prompt).
  • make sure TeXLive? is in PATH: export PATH=/usr/local/texlive/2010/bin/i386-cygwin:$PATH
  • install additional LaTeX? packages with tlmgr from Cygwin prompt: tlmgr install soul tex4ht enumitem multirow tex4ht.i386-cygwin

Windows / VMWare

The VMWare image is missing only the Unicode support package. Log in as root and run "apt-get install latex-ucs" to install it

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

Revision r91 - 20 Apr 2011 - 19:19 - DominikRiebeling
Revision r90 - 20 Apr 2011 - 06:33 - DominikRiebeling
Copyright by the contributing authors.