blob: 5b6e11094ae5f697713c5eeccefe3c2ca3d00404 [file] [log] [blame]
Dominik Riebeling40afbd22007-01-02 20:50:03 +00001%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2% __________ __ ___.
3% Open \______ \ ____ ____ | | _\_ |__ _______ ___
4% Source | _// _ \_/ ___\| |/ /| __ \ / _ \ \/ /
5% Jukebox | | ( <_> ) \___| < | \_\ ( <_> > < <
6% Firmware |____|_ /\____/ \___ >__|_ \|___ /\____/__/\_ \
7% \/ \/ \/ \/ \/
8% - M A N U A L -
9%
10% $Id$
11%
12% Copyright (C) 2006 The Rockbox Manual Team
13%
14% All files in this archive are subject to the GNU Free Documentation License
15% See the file COPYING-MANUAL in the source tree docs/ folder for full license
16% agreement.
17%
18% Contributors are listed in the file docs/CREDITS-MANUAL
19%
20%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
21
Martin Arver3622c932006-03-29 18:48:52 +000022\documentclass[a4paper,11pt]{scrreprt}
Dominik Riebeling73ee2372007-02-01 00:00:49 +000023\usepackage[utf8x]{inputenc}
Martin Arver8bedb5c2006-03-22 23:26:30 +000024\usepackage{palatino}
Christi Scarboroughd68d7c02006-02-06 07:25:25 +000025
Martin Arverec60a052006-03-29 18:40:42 +000026\usepackage{tabularx}
Nils Wallméniusc687b302006-04-02 13:50:01 +000027\usepackage{multirow}
Dominik Riebelingb074b222006-06-05 10:08:54 +000028\usepackage{multicol}
Martin Arver0da41d82006-03-24 11:53:07 +000029
Christi Scarboroughd68d7c02006-02-06 07:25:25 +000030\usepackage{float}
31\floatstyle{ruled}
32
Dominik Riebelingc0068bb2006-04-08 21:00:22 +000033\usepackage{hyperref}
34
Christi Scarboroughd68d7c02006-02-06 07:25:25 +000035\usepackage{optional}
36
37\input{platform/\platform.tex}
38
Martin Arver4c981062006-06-07 18:48:56 +000039\newcommand{\playername}{\playerman\ \playerlongtype}
Christi Scarboroughd68d7c02006-02-06 07:25:25 +000040
Dominik Riebelingc0068bb2006-04-08 21:00:22 +000041\hypersetup{% add some values to the pdf properties
42 colorlinks = true,
43 pdfstartview = FitV,
44 linkcolor = blue,
45 citecolor = blue,
46 urlcolor = blue,
47 pdftitle = {Rockbox user manual},
48 pdfauthor = {The Rockbox Team},
49 pdfsubject = {Rockbox user manual for \playername}
50}
51
Martin Arver47ea9062006-06-07 12:15:46 +000052\newcommand{\fname}[1]{\texttt{#1}}
Christi Scarboroughd68d7c02006-02-06 07:25:25 +000053\newcommand{\tabeltc}[1]{{\centering #1 \par}}
54\newcommand{\tabelth}[1]{{\centering \textbf{\textit{#1}} \par}}
55
Martin Arvera0cdee02006-03-31 12:25:22 +000056\newcommand{\fixme}[1]{\textbf{\textcolor{red}{#1}}}
57
Christi Scarboroughd68d7c02006-02-06 07:25:25 +000058\usepackage{fancyhdr}
59\usepackage{graphicx}
60\usepackage{verbatim}
Christi Scarboroughd68d7c02006-02-06 07:25:25 +000061\usepackage{makeidx}
Christi Scarboroughd68d7c02006-02-06 07:25:25 +000062\usepackage{fancyvrb}
63\usepackage{enumerate}
Christi Scarboroughd68d7c02006-02-06 07:25:25 +000064\usepackage{color}
Dominik Riebeling1d16d4a2006-09-17 20:34:10 +000065\ifpdfoutput{\usepackage{booktabs}}%
66 {\newcommand{%
67 \toprule}{}\newcommand{\midrule}{\hline}\newcommand{\bottomrule}{}%
68 }
Martin Arverd3d3e342006-03-15 10:56:14 +000069\usepackage{longtable}
Martin Arver7d6810c2006-03-31 11:50:33 +000070\usepackage{url}
71\urlstyle{sf}
Martin Arver9be37f32006-03-31 13:29:27 +000072\usepackage{marvosym}
Martin Arver1dbb2d22006-06-07 20:01:27 +000073\usepackage{ifthen}
Dominik Riebeling6ea22822007-01-07 17:10:44 +000074\usepackage{rotating}
Christi Scarboroughd68d7c02006-02-06 07:25:25 +000075
Dominik Riebeling009aeab2006-04-03 21:29:47 +000076% mark this ad draft version (only for pdflatex) -- comment this out at release
Dominik Riebeling6424c502006-07-17 19:10:31 +000077\ifpdfoutput{
Dominik Riebeling009aeab2006-04-03 21:29:47 +000078 \usepackage{pdfdraftcopy}
79 \draftstring{DRAFT VERSION}
80% \draftangle{45}
Dominik Riebeling6424c502006-07-17 19:10:31 +000081 }
Dominik Riebeling009aeab2006-04-03 21:29:47 +000082
Dominik Riebeling1d16d4a2006-09-17 20:34:10 +000083% pdf output: try pdf first, then png and jpg as file format
84% html output: try png first, then jpg. Ignore pdf files
85% this only applies if no file extension is given!
86\ifpdfoutput{\DeclareGraphicsExtensions{.pdf,.png,.jpg}}%
87 {\DeclareGraphicsExtensions{.png,.jpg}}
88
Martin Arver6d5d7342006-03-30 22:03:46 +000089% fancy header style adjustments
Christi Scarboroughd68d7c02006-02-06 07:25:25 +000090\fancyhead{}
91\fancyfoot{}
Dominik Riebelingc9bb1522006-08-13 18:55:59 +000092\fancyhead[L]{{\nouppercase{\textsc{\leftmark}}}}
Martin Arver6d5d7342006-03-30 22:03:46 +000093\fancyhead[R]{\iffloatpage{}{\thepage}}
Martin Arver6c9f3152006-06-05 16:31:34 +000094\fancyfoot[L]{\textsc{The Rockbox manual}}
Dominik Riebelingc7bb9492006-06-13 16:39:07 +000095\fancyfoot[R]{\textsc{\playerman{} \playertype}}
Dominik Riebelingc9bb1522006-08-13 18:55:59 +000096\fancypagestyle{plain}{}
Christi Scarboroughd68d7c02006-02-06 07:25:25 +000097
Christi Scarboroughd68d7c02006-02-06 07:25:25 +000098\renewcommand{\headrulewidth}{\iffloatpage{0pt}{0.4pt}}
99\renewcommand{\footrulewidth}{\iffloatpage{0pt}{0.4pt}}
100\setlength{\headheight}{18.5pt}
101\newcounter{example}[chapter]
Martin Arver0da41d82006-03-24 11:53:07 +0000102
Martin Arver47ea9062006-06-07 12:15:46 +0000103%% \newenvironment{example}
104%% {\stepcounter{example}\paragraph{Example \theexample:}}
105%% {\hfill$\Box$
Christi Scarboroughd68d7c02006-02-06 07:25:25 +0000106
Martin Arver47ea9062006-06-07 12:15:46 +0000107%% \bigskip
108%% \noindent}
Martin Arver0da41d82006-03-24 11:53:07 +0000109
Martin Arvercbc55992006-03-30 15:54:47 +0000110% found on the internet, posting by Donald Arseneau
111% I may as well include my robust expandable definions, which can be
112% used in \edef or \write where the \def would not be executed:
113%
114% \if\blank --- checks if parameter is blank (Spaces count as blank)
115% \if\given --- checks if parameter is not blank: like \if\blank{#1}\else
116% \if\nil --- checks if parameter is null (spaces are NOT null)
117% use \if\given{ } ... \else ... \fi etc.
118%
119{\catcode`\!=8 % funny catcode so ! will be a delimiter
120\catcode`\Q=3 % funny catcode so Q will be a delimiter
121\long\gdef\given#1{88\fi\Ifbl@nk#1QQQ\empty!}
122\long\gdef\blank#1{88\fi\Ifbl@nk#1QQ..!}% if null or spaces
123\long\gdef\nil#1{\IfN@Ught#1* {#1}!}% if null
124\long\gdef\IfN@Ught#1 #2!{\blank{#2}}
125\long\gdef\Ifbl@nk#1#2Q#3!{\ifx#3}% same as above
126}
127
128% add screenshot image.
129% Usage: \screenshot{filename}{caption}{label}
Martin Arverf6db3682006-04-26 11:06:45 +0000130% By using the 'H' (HERE) placement, the screenshots are placed where
131% we want them.
Martin Arvercbc55992006-03-30 15:54:47 +0000132% Note: use this only for screenshots!
133% Note: leave caption empty to supress it.
134\newcommand{\screenshot}[3]{
Martin Arverf6db3682006-04-26 11:06:45 +0000135 \begin{figure}[H]
Martin Arvercbc55992006-03-30 15:54:47 +0000136 \begin{center}
Dominik Riebeling5be45092006-06-04 11:20:06 +0000137 \IfFileExists{#1-\genericimg-\specimg.png}
Dominik Riebelingf83f9202006-08-18 14:32:15 +0000138 {\includegraphics[width=\screenshotsize]{#1-\genericimg-\specimg.png}
Dominik Riebeling5be45092006-06-04 11:20:06 +0000139 \typeout{Note: device specific image used}}
140 {\IfFileExists{#1-\genericimg.png}
Dominik Riebelingf83f9202006-08-18 14:32:15 +0000141 {\includegraphics[width=\screenshotsize]{#1-\genericimg.png}}
Dominik Riebeling5be45092006-06-04 11:20:06 +0000142 {\IfFileExists{#1}
Dominik Riebelingf83f9202006-08-18 14:32:15 +0000143 {\includegraphics[width=\screenshotsize]{#1}
Dominik Riebeling5be45092006-06-04 11:20:06 +0000144 \typeout{Warning: deprecated plain image name used}}%
145 {\typeout{Missing image: #1 (\genericimg) (\specimg)}%
146 \color{red}{\textbf{WARNING!} Image not found}%
147 }
Dominik Riebeling2cf5abb2006-04-02 17:29:44 +0000148 }
149 }
Dominik Riebelinge5a2b692006-04-01 19:16:12 +0000150 \if\blank{#3}\else{\label{#3}}\fi\if\blank{#2}\else{%
Martin Arvercbc55992006-03-30 15:54:47 +0000151 \caption{#2}}\fi
152 \end{center}
153 \end{figure}
154}
Martin Arver0da41d82006-03-24 11:53:07 +0000155
Martin Arver9be37f32006-03-31 13:29:27 +0000156% command to display a note.
157% Usage: \note{text of your note}
158% Note: do NOT use \textbf or similar to emphasize text, use \emph!
Dominik Riebeling6424c502006-07-17 19:10:31 +0000159\ifpdfoutput{
Martin Arver9be37f32006-03-31 13:29:27 +0000160\newcommand{\note}[1]{
Dominik Riebelingdf91a9b2006-04-01 15:35:30 +0000161 \ifinner\else\par\noindent\fi
162 \textbf{Note:}\ %
163 \ifinner#1\else\marginpar{\raisebox{-6pt}{\Huge\Writinghand}}#1\par\fi%
Dominik Riebeling6424c502006-07-17 19:10:31 +0000164}}
165{\newcommand{\note}[1]{\ifinner\else\par\noindent\fi\textbf{Note:{} }#1\par}}
Martin Arver9be37f32006-03-31 13:29:27 +0000166
167% command to display a warning.
168% Usage: \warn{text of your warning}
169% Note: do NOT use \textbf or similar to emphasize text!
Dominik Riebeling6424c502006-07-17 19:10:31 +0000170\ifpdfoutput{
Martin Arver9be37f32006-03-31 13:29:27 +0000171\newcommand{\warn}[1]{
Dominik Riebelingdf91a9b2006-04-01 15:35:30 +0000172 \ifinner\else\par\noindent\fi
173 \textbf{Warning:\ }%
174 \ifinner#1\else\marginpar{\raisebox{-6pt}{\Huge\Stopsign}}#1\par\fi%
Dominik Riebeling6424c502006-07-17 19:10:31 +0000175}}
176{\newcommand{\warn}[1]{\ifinner\else\par\noindent\fi\textbf{Warning:{} }#1}}
Dominik Riebelingdf91a9b2006-04-01 15:35:30 +0000177
Dominik Riebeling4ccc2ce2006-07-19 16:06:37 +0000178% command to mark a text block as intended especially for blind people
179% Usage: \blind{text}
180\ifpdfoutput{
181\newcommand{\blind}[1]{
182 \ifinner\else\par\noindent\fi
183 \ifinner#1\else\marginpar{\raisebox{-6pt}{\Huge\ForwardToEnd}}#1\par\fi%
184}}
185{\newcommand{\blind}[1]{\ifinner\else\par\noindent\fi#1}}
186
Martin Arverf6db3682006-04-26 11:06:45 +0000187% make table floats use "H" (as for screenshots) as default positioning
188\makeatletter\renewcommand{\fps@table}{H}\makeatother
Dominik Riebeling38385a52006-04-03 18:14:25 +0000189% change defaults for floats on a page as we have a lot of small images
190\setcounter{topnumber}{3} % default: 2
191\setcounter{bottomnumber}{2} % default: 1
192\setcounter{totalnumber}{5} % default: 3
193
Dominik Riebeling8c177222006-04-03 22:45:01 +0000194% command to set the default table heading for button lists
195\newcommand{\btnhead}{\textbf{Key} & \textbf{Action} \\\midrule}
196
197% environment intended to be used with button maps
198% usage: \begin{btnmap}{caption}{label} Button & ButtonAction \\ \end{btnmap}
199% Note: this automatically sets the table lines.
200% Note: you *need* to terminate the last line with a linebreak \\
201% Note: you still need to enclose this with \begin{table} / \end{table}
202% Cheers for the usenet helping me building this up :)
203\newenvironment{btnmap}[2]{%
204 \expandafter\let\expandafter\SavedEndTab\csname endtabular*\endcsname
205 \expandafter\renewcommand\expandafter*\csname endtabular*\endcsname{%
206 \bottomrule
207 \SavedEndTab%
208 \if\given{#1}\caption{#1}\fi%
209 \if\given{#2}\label{#2}\fi%
210 \endcenter%
211 }
212 \center
213\tabularx{.75\textwidth}{lX}\toprule % here is the table width defined
214 \btnhead
215}{%
216 \endtabularx
217}
218
Dominik Riebeling36a31332006-04-09 21:22:42 +0000219% command to set the default table heading for button lists
220\newcommand{\taghead}{\textbf{Tag} & \textbf{Description} \\\midrule}
221
222% environment intended to be used with tag maps (for wps)
223% usage: \begin{tagmap}{caption}{label} Tag & Description \\ \end{btnmap}
224% Note: this automatically sets the table lines.
225% Note: you *need* to terminate the last line with a linebreak \\
226% Note: you still need to enclose this with \begin{table} / \end{table}
227% Cheers for the usenet helping me building this up :)
228\newenvironment{tagmap}[2]{%
229 \expandafter\let\expandafter\SavedEndTab\csname endtabular*\endcsname
230 \expandafter\renewcommand\expandafter*\csname endtabular*\endcsname{%
231 \bottomrule
232 \SavedEndTab%
233 \if\given{#1}\caption{#1}\fi%
234 \if\given{#2}\label{#2}\fi%
235 \endcenter%
236 }
237 \center
238\tabularx{\textwidth}{lX}\toprule % here is the table width defined
239 \taghead
240}{%
241 \endtabularx
242}
243
Dominik Riebeling9c426e92006-04-27 18:52:16 +0000244\newcommand{\setting}[1]{\textsc{#1}}
Dominik Riebeling36a31332006-04-09 21:22:42 +0000245
Dominik Riebeling0f661ab2006-05-28 15:49:17 +0000246\newcommand{\config}[1]{\texttt{#1}}
247
Dominik Riebeling40afbd22007-01-02 20:50:03 +0000248% set link to download server
249% Usage: \download{bootloader/bootloader-ipodnano.ipod}
250% gets expanded to
251% "http://download.rockbox.org/bootloader/bootloader-ipodnano.ipod"
252\newcommand{\download}[1]{\url{http://download.rockbox.org/#1}}
253
Dominik Riebeling0f661ab2006-05-28 15:49:17 +0000254% set link to the wiki.
255% Usage: \wikilink{WebHome}
256% with "WebHome" being the wiki page name
Dominik Riebeling7255bdb2007-09-24 22:39:24 +0000257\newcommand{\wikibaseurl}{http://www.rockbox.org/wiki/}
258\ifpdfoutput{\newcommand{\wikiicon}{\Pointinghand}}
259 {\newcommand{\wikiicon}{}}
260\newcommand{\wikilink}[1]{\wikiicon{}\href{\wikibaseurl#1}{#1}}
261%\newcommand{\wikilink}[1]{\url{http://www.rockbox.org/wiki/#1}}
Dominik Riebeling0f661ab2006-05-28 15:49:17 +0000262
Dominik Riebeling89a2a282006-06-06 17:42:27 +0000263% define environment "code" based on fancyvrb.
264% use it to set code the user should type / see on his screen.
265% Note: the first 4 characters of each line will be stripped,
266% requiring everything to be indendet by exactly _4_ spaces!
267% This is intended to make the LaTeX sources more readable.
268% Note: when using the code environment you need to use optv instead of opt!
269\DefineVerbatimEnvironment{code}{Verbatim}%
Dominik Riebeling6ea22822007-01-07 17:10:44 +0000270 {framerule=0.4pt, framesep=1ex,frame=lines,%numbers=left,stepnumber=5,%
271 gobble=4,fontsize=\footnotesize,xleftmargin=10pt,xrightmargin=10pt,%
Dominik Riebeling89a2a282006-06-06 17:42:27 +0000272 label=\textnormal{\textsc{Code}},%
273 commandchars=\\\{\}%
274 }
275
Martin Arver47ea9062006-06-07 12:15:46 +0000276% define environment "example" based on fancyvrb.
277% use it to set example code the user should type / see on his screen.
278% Note: the first 4 characters of each line will be stripped,
279% requiring everything to be indendet by exactly _4_ spaces!
280% This is intended to make the LaTeX sources more readable.
281% Note: when using the example environment you need to use optv instead of opt!
282\DefineVerbatimEnvironment{example}{Verbatim}%
283 {commentchar=!,framerule=0.4pt, framesep=1ex,frame=lines,%
Dominik Riebeling6ea22822007-01-07 17:10:44 +0000284 gobble=4,fontsize=\footnotesize,xleftmargin=10pt,xrightmargin=10pt,%
Martin Arver47ea9062006-06-07 12:15:46 +0000285 label=\textnormal{\textsc{Example}},%
286 commandchars=\\\{\}%
287 }
288
Martin Arver1dbb2d22006-06-07 20:01:27 +0000289% Use the nopt command to exclude a certain defined feature from a sectio
290% Example:
291% \nopt{ondio}{This text will be excluded for ondios}
292\newcommand{\optnvalue}{0}
293 \newcommand{\nopt}[2]{%
294 \renewcommand{\optnvalue}{0}\opt{#1}{\renewcommand{\optnvalue}{1}}%
Dominik Riebelingeef96942007-04-07 22:48:11 +0000295 \ifthenelse{\optnvalue > 0}{}{#2}%
Martin Arver1dbb2d22006-06-07 20:01:27 +0000296 }
Martin Arver7a473132006-07-31 12:21:57 +0000297
Martin Arver26c6e7b2006-08-01 11:57:38 +0000298% Use the reference to handle get a flexible reference command
299% usage \reference{ref_section}
Dominik Riebelingc9bb1522006-08-13 18:55:59 +0000300\ifpdfoutput{%
Martin Arver26c6e7b2006-08-01 11:57:38 +0000301 \newcommand{\reference}[1]{%
Dominik Riebelingd0a12a72006-08-22 16:34:41 +0000302 section~\ref{#1} (page~\pageref{#1})%
Martin Arver7a473132006-07-31 12:21:57 +0000303}}
Dominik Riebelingd0a12a72006-08-22 16:34:41 +0000304{\newcommand{\reference}[1]{section~\ref{#1}}}
Dominik Riebeling5eb1e152006-08-07 20:46:26 +0000305
306% special HTML output adjustments
307\ifpdfoutput{}{\setlength{\parindent}{0mm}}
308\ifpdfoutput{}{\renewcommand{\Forward}[1]{$\triangleright${}#1}}
Dominik Riebelingf83f9202006-08-18 14:32:15 +0000309
Dominik Riebelingf6b4b912006-08-24 15:09:34 +0000310\newcommand{\btnfnt}[1]{\textbf{#1}}
Dominik Riebelinga9a5c352006-10-05 16:47:17 +0000311%\hfuzz=2pt
312
313% generate index
314\usepackage{makeidx}
315\makeindex