Prepare new maemo release
[maemo-rb.git] / manual / preamble.tex
blob08d1f0dc0a5b86a0381beb7e7957b71433ece59f
1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2 % __________ __ ___.
3 % Open \______ \ ____ ____ | | _\_ |__ _______ ___
4 % Source | _// _ \_/ ___\| |/ /| __ \ / _ \ \/ /
5 % Jukebox | | ( <_> ) \___| < | \_\ ( <_> > < <
6 % Firmware |____|_ /\____/ \___ >__|_ \|___ /\____/__/\_ \
7 % \/ \/ \/ \/ \/
8 % - M A N U A L -
10 % $Id$
12 % Copyright (C) 2006 The Rockbox Manual Team
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/ directory for full license
16 % agreement.
18 % Contributors are listed in the file docs/CREDITS-MANUAL
20 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
22 \documentclass[a4paper,11pt,hyphens]{scrreprt}
23 \usepackage[utf8]{inputenx}
24 \usepackage[T1]{fontenc}
25 % load ix-utf8enc.dfu to get additional characters from the inputenx package.
26 \makeatletter\input{ix-utf8enc.dfu}\makeatother
27 % This manual used to use Palatino as font. This caused issues with small caps
28 % (textsc), so do not use that font as default one anymore.
29 % Use Latin Modern instead which improves searchability of the PDF output.
30 \usepackage{lmodern}
32 \usepackage{tabularx}
33 \usepackage{multirow}
34 \usepackage{multicol}
36 \usepackage{float}
37 \floatstyle{ruled}
39 \usepackage{hyperref}
40 \usepackage{enumitem}
42 \usepackage{optional}
44 \usepackage[table]{xcolor}
46 \input{platform/\platform.tex}
47 \input{features.tex}
49 \newcommand{\playername}{\playerman\ \playerlongtype}
51 \hypersetup{% add some values to the pdf properties
52 colorlinks = true,
53 pdfstartview = FitV,
54 linkcolor = blue,
55 citecolor = blue,
56 urlcolor = blue,
57 pdftitle = {Rockbox user manual},
58 pdfauthor = {The Rockbox Team},
59 pdfsubject = {Rockbox user manual for \playername}
62 \newcommand{\fname}[1]{\texttt{#1}}
63 \newcommand{\tabeltc}[1]{{\centering #1 \par}}
64 \newcommand{\tabelth}[1]{{\centering \textbf{\textit{#1}} \par}}
66 \newcommand{\fixme}[1]{\textbf{\textcolor{red}{#1}}}
68 % Colors used to typeset table headers and alternating table rows
69 \colorlet{tblhdrbgcolor}{blue!30} % Background color for headers
70 \colorlet{tbloddrowbgcolor}{blue!10} % Background color for odd rows (headers not included)
71 \colorlet{tblevenrowbgcolor}{white} % Background color for even rows (headers not included)
73 \usepackage{fancyhdr}
74 \usepackage{graphicx}
75 \usepackage{verbatim}
76 \usepackage{makeidx}
77 \usepackage{fancyvrb}
78 \usepackage{color}
79 \ifpdfoutput{\usepackage{booktabs}}%
80 {\newcommand{%
81 \toprule}{}\newcommand{\midrule}{\hline}\newcommand{\bottomrule}{}%
83 \usepackage{longtable}
84 \usepackage{url}
85 \urlstyle{sf}
86 \Urlmuskip = 0mu plus 1mu
87 \usepackage{marvosym}
88 \usepackage{rotating}
90 % pdf output: try pdf first, then png and jpg as file format
91 % html output: try png first, then jpg. Ignore pdf files
92 % this only applies if no file extension is given!
93 \ifpdfoutput{\DeclareGraphicsExtensions{.pdf,.png,.jpg}}%
94 {\DeclareGraphicsExtensions{.png,.jpg}}
96 % fancy header style adjustments
97 \fancyhead{}
98 \fancyfoot{}
99 \fancyhead[L]{{\nouppercase{\textsc{\leftmark}}}}
100 \fancyhead[R]{\iffloatpage{}{\thepage}}
101 \fancyfoot[L]{\textsc{The Rockbox manual} {\scriptsize(version \buildversion)}}
102 \fancyfoot[R]{\textsc{\playerman{} \playertype}}
103 \fancypagestyle{plain}{}
105 \renewcommand{\headrulewidth}{\iffloatpage{0pt}{0.4pt}}
106 \renewcommand{\footrulewidth}{\iffloatpage{0pt}{0.4pt}}
107 \setlength{\headheight}{18.5pt}
108 \newcounter{example}[chapter]
110 \ifpdfoutput{%
111 \renewcommand{\toprule}{\specialrule{\heavyrulewidth}{\abovetopsep}{0pt}}
112 \renewcommand{\midrule}{\specialrule{\lightrulewidth}{0pt}{\belowrulesep}}
114 \newcommand{\tblhdrstrut}{\rule[-1.3ex]{0mm}{4.0ex}}
117 %% \newenvironment{example}
118 %% {\stepcounter{example}\paragraph{Example \theexample:}}
119 %% {\hfill$\Box$
121 %% \bigskip
122 %% \noindent}
124 % found on the internet, posting by Donald Arseneau
125 % I may as well include my robust expandable definions, which can be
126 % used in \edef or \write where the \def would not be executed:
128 % \if\blank --- checks if parameter is blank (Spaces count as blank)
129 % \if\given --- checks if parameter is not blank: like \if\blank{#1}\else
130 % \if\nil --- checks if parameter is null (spaces are NOT null)
131 % use \if\given{ } ... \else ... \fi etc.
133 {\catcode`\!=8 % funny catcode so ! will be a delimiter
134 \catcode`\Q=3 % funny catcode so Q will be a delimiter
135 \long\gdef\given#1{88\fi\Ifbl@nk#1QQQ\empty!}
136 \long\gdef\blank#1{88\fi\Ifbl@nk#1QQ..!}% if null or spaces
137 \long\gdef\nil#1{\IfN@Ught#1* {#1}!}% if null
138 \long\gdef\IfN@Ught#1 #2!{\blank{#2}}
139 \long\gdef\Ifbl@nk#1#2Q#3!{\ifx#3}% same as above
142 % environment for setting the changelog.
143 \newenvironment{changelog}%
144 {\renewcommand{\labelitemi}{$\star$}\setitemize{noitemsep,topsep=0pt}%
145 \begin{itemize}}%
146 {\end{itemize}}
149 \newcommand{\dapdisplaysize}{\dapdisplaywidth$\times$\dapdisplayheight$\times$\dapdisplaydepth}
150 \newcommand{\genericimg}{\dapdisplaywidth x\dapdisplayheight x\dapdisplaydepth}
152 % add screenshot image.
153 % Usage: \screenshot{filename}{caption}{label}
154 % By using the 'H' (HERE) placement, the screenshots are placed where
155 % we want them.
156 % Note: use this only for screenshots!
157 % Note: leave caption empty to supress it.
158 % Resulting file names in the source should consist of up to 3 parts
159 % "filename-\genericimg-[\specimg|\seriesimg]" (the third is optional)
160 % filename is specified by the use of this macro in the tex file
161 % \genericimg will be generated using the display's resolution (see above)
162 % \specimg or \seriesimg are possible options set in the platform files
163 % Files will be used in the following order: 1.filename contains \specimg part
164 % 2. filename contains \seriesimg part, 3. filename without the third part
166 % set seriesimg if it isn't defined in the platform file to not break manuals
167 \ifdefined\seriesimg
168 \else
169 \newcommand{\seriesimg}{\specimg}
172 \newcommand{\screenshot}[3]{
173 \begin{figure}[H]
174 \begin{center}
175 \IfFileExists{#1-\genericimg-\specimg.png}
176 {\includegraphics[width=\screenshotsize]{#1-\genericimg-\specimg.png}
177 \typeout{Note: device specific image used}}
178 {\IfFileExists{#1-\genericimg-\seriesimg.png}
179 {\includegraphics[width=\screenshotsize]{#1-\genericimg-\seriesimg.png}
180 \typeout{Note: series specific image used}}
181 {\IfFileExists{#1-\genericimg.png}
182 {\includegraphics[width=\screenshotsize]{#1-\genericimg.png}}
183 {\IfFileExists{#1}
184 {\includegraphics[width=\screenshotsize]{#1}
185 \typeout{Warning: deprecated plain image name used}}%
186 {\typeout{Missing image: #1 (\genericimg) (\specimg)}%
187 \color{red}{\textbf{WARNING!} Image not found}%
192 \if\blank{#3}\else{\label{#3}}\fi\if\blank{#2}\else{%
193 \caption{#2}}\fi
194 \end{center}
195 \end{figure}
198 % command to display a note.
199 % Usage: \note{text of your note}
200 % Note: do NOT use \textbf or similar to emphasize text, use \emph!
201 \ifpdfoutput{
202 \newcommand{\note}[1]{
203 \ifinner\else\vspace{1ex}\par\noindent\fi
204 \textbf{Note:}\ %
205 \ifinner#1\else\marginpar{\raisebox{-6pt}{\Huge\Writinghand}}#1\par\vspace{1ex}\fi%
207 {\newcommand{\note}[1]{\ifinner\else\par\noindent\fi\textbf{Note:{} }#1\par}}
209 % command to display a warning.
210 % Usage: \warn{text of your warning}
211 % Note: do NOT use \textbf or similar to emphasize text!
212 \ifpdfoutput{
213 \newcommand{\warn}[1]{
214 \ifinner\else\par\noindent\fi
215 \textbf{Warning:\ }%
216 \ifinner#1\else\marginpar{\raisebox{-6pt}{\Huge\Stopsign}}#1\par\fi%
218 {\newcommand{\warn}[1]{\ifinner\else\par\noindent\fi\textbf{Warning:{} }#1}}
220 % command to mark a text block as intended especially for blind people
221 % Usage: \blind{text}
222 \ifpdfoutput{
223 \newcommand{\blind}[1]{\mbox{}\marginpar{\raisebox{-1ex}{\Huge{\ForwardToEnd}}}#1}
225 {\newcommand{\blind}[1]{\ifinner\else\par\noindent\fi#1}}
227 % make table floats use "H" (as for screenshots) as default positioning
228 \makeatletter\renewcommand{\fps@table}{H}\makeatother
229 % change defaults for floats on a page as we have a lot of small images
230 \setcounter{topnumber}{3} % default: 2
231 \setcounter{bottomnumber}{2} % default: 1
232 \setcounter{totalnumber}{5} % default: 3
235 % Environment for typesetting tables in a consistent way. The header has
236 % a darker background; rows are white and light gray (alternating). Top,
237 % middle and bottom rules are automatically set.
239 % Params:
240 % #1 -- table width
241 % #2 -- column specification (as used in the package tabularx)
242 % #3 -- contents of the header row. The number of items must
243 % match the number of specs in #2
244 % #4 -- caption (optional). If used then this must be inside a floating
245 % environment, e.g. table
246 % #5 -- label (optional)
248 % Example:
249 % \begin{rbtabular}{0.9\textwidth}{lX}{Col1 & Col2}{}{}
250 % A1 & A2\\
251 % B1 & B2\\
252 % C1 & C2\\
253 % \end{rbtabular}
255 \newenvironment{rbtabular}[5]{%
256 \rowcolors{2}{tbloddrowbgcolor}{tblevenrowbgcolor}
257 \expandafter\let\expandafter\SavedEndTab\csname endtabular*\endcsname
258 \expandafter\renewcommand\expandafter*\csname endtabular*\endcsname{%
259 \bottomrule
260 \SavedEndTab%
261 \if\given{#4}\caption{#4}\fi%
262 \if\given{#5}\label{#5}\fi%
263 \endcenter%
265 \center
266 \tabularx{#1}{#2}\toprule\rowcolor{tblhdrbgcolor}
267 \tblhdrstrut#3\\\midrule
269 \endtabularx
272 \newcommand{\tabnlindent}{\newline\mbox{ }\mbox{ }}
276 % command to set the default table heading for button lists
277 \newcommand{\taghead}{\tblhdrstrut\textbf{Tag} & \textbf{Description} \\\midrule}
279 % environment intended to be used with tag maps (for wps)
280 % usage: \begin{tagmap}{caption}{label} Tag & Description \\ \end{tagmap}
281 % Note: this automatically sets the table lines.
282 % Note: you *need* to terminate the last line with a linebreak \\
283 % Cheers for the usenet helping me building this up :)
284 \newenvironment{tagmap}{%
285 \rowcolors{2}{tbloddrowbgcolor}{tblevenrowbgcolor}
286 \expandafter\let\expandafter\SavedEndTab\csname endtabular*\endcsname
287 \expandafter\renewcommand\expandafter*\csname endtabular*\endcsname{%
288 \bottomrule
289 \SavedEndTab%
290 \endcenter%
292 \center
293 \tabularx{\textwidth}{Xp{.7\textwidth}}\toprule\rowcolor{tblhdrbgcolor} % here is the table width defined
294 \taghead
296 \endtabularx
299 % When creating HTML, use the soul package.
300 % This produces much nicer HTML code (textsc results in each character being
301 % put in a separate <span>).
302 \ifpdfoutput{\newcommand{\caps}[1]{\textsc{#1}}}{\usepackage{soul}}
303 \newcommand{\setting}[1]{\caps{#1}}
305 \newcommand{\config}[1]{\texttt{#1}}
307 % set link to download server
308 % Usage: \download{bootloader/bootloader-ipodnano.ipod}
309 % gets expanded to
310 % "http://download.rockbox.org/bootloader/bootloader-ipodnano.ipod"
311 \newcommand{\download}[1]{\url{http://download.rockbox.org/#1}}
313 % set link to the wiki.
314 % Usage: \wikilink{WebHome}
315 % with "WebHome" being the wiki page name
316 \newcommand{\wikibaseurl}{http://www.rockbox.org/wiki/}
317 \ifpdfoutput{\newcommand{\wikiicon}{\Pointinghand}}
318 {\newcommand{\wikiicon}{}}
319 \newcommand{\wikilink}[1]{\wikiicon{}\href{\wikibaseurl#1}{#1}}
320 %\newcommand{\wikilink}[1]{\url{http://www.rockbox.org/wiki/#1}}
322 % define environment "code" based on fancyvrb.
323 % use it to set code the user should type / see on his screen.
324 % Note: the first 4 characters of each line will be stripped,
325 % requiring everything to be indendet by exactly _4_ spaces!
326 % This is intended to make the LaTeX sources more readable.
327 % Note: when using the code environment you need to use optv instead of opt!
328 \DefineVerbatimEnvironment{code}{Verbatim}%
329 {framerule=0.4pt, framesep=1ex,frame=lines,%numbers=left,stepnumber=5,%
330 gobble=4,fontsize=\footnotesize,xleftmargin=10pt,xrightmargin=10pt,%
331 label=\textnormal{\textsc{Code}},%
332 commandchars=\\\{\}%
335 % define environment "example" based on fancyvrb.
336 % use it to set example code the user should type / see on his screen.
337 % Note: the first 4 characters of each line will be stripped,
338 % requiring everything to be indendet by exactly _4_ spaces!
339 % This is intended to make the LaTeX sources more readable.
340 % Note: when using the example environment you need to use optv instead of opt!
341 \DefineVerbatimEnvironment{example}{Verbatim}%
342 {commentchar=!,framerule=0.4pt, framesep=1ex,frame=lines,%
343 gobble=4,fontsize=\footnotesize,xleftmargin=10pt,xrightmargin=10pt,%
344 label=\textnormal{\textsc{Example}},%
345 commandchars=\\\{\}%
348 % Use the nopt command to exclude a certain defined feature from a section
349 % Example:
350 % \nopt{ondio}{This text will be excluded for ondios}
351 \makeatletter
352 \newcommand*\nopt[1]{\if\Opl@notlisted{#1}\expandafter\@firstofone
353 \else \expandafter\@gobble \fi}
354 \makeatother
356 % Use the reference to handle get a flexible reference command
357 % usage \reference{ref_section}
358 \ifpdfoutput{%
359 \newcommand{\reference}[1]{%
360 section~\ref{#1} (page~\pageref{#1})%
362 {\newcommand{\reference}[1]{section~\ref{#1}}}
364 % special HTML output adjustments
365 \ifpdfoutput{}{\setlength{\parindent}{0mm}}
366 \ifpdfoutput{}{\renewcommand{\Forward}[1]{$\triangleright${}#1}}
368 \newcommand{\btnfnt}[1]{\textbf{#1}}
369 %\hfuzz=2pt
371 % generate index
372 \usepackage{makeidx}
373 \makeindex
376 % command to set the default table heading for button lists
377 \newcommand{\btnhead}{\textbf{Key} \opt{HAVEREMOTEKEYMAP}{%
378 & \textbf{Remote Key}} & \textbf{Action} \\\midrule}
379 % environment intended to be used with button maps
380 % usage: \begin{btnmap} Button & ButtonAction \\ \end{btnmap}
381 % Note: this automatically sets the table lines.
382 % Note: you *need* to terminate the last line with a linebreak \\
383 % Cheers for the usenet helping me building this up :)
385 % tabularx is set to be either two or three columns wide depending on whether
386 % HAVEREMOTEKEYMAP is defined in the platform file for the target in question.
387 % If it is, then every button table has three columns of the form
388 % Main Unit Key & Remote Key & Description \\
390 \newenvironment{btnmap}{%
391 \rowcolors{2}{tbloddrowbgcolor}{tblevenrowbgcolor}
392 \expandafter\let\expandafter\SavedEndTab\csname endtabular*\endcsname
393 \expandafter\renewcommand\expandafter*\csname endtabular*\endcsname{%
394 \bottomrule
395 \SavedEndTab%
396 \endcenter\vspace{2ex}%
398 \vspace{2ex}\center
399 \opt{HAVEREMOTEKEYMAP}{
400 % here is the table width defined for 3 columns
401 \tabularx{.95\textwidth}{>{\raggedright\arraybackslash}p{.2\textwidth}>{\raggedright\arraybackslash}p{.2\textwidth}X}\toprule\rowcolor{tblhdrbgcolor}
403 \nopt{HAVEREMOTEKEYMAP}{
404 % here is the table width defined for 2 columns
405 \tabularx{.75\textwidth}{>{\raggedright\arraybackslash}p{.22\textwidth}X}\toprule\rowcolor{tblhdrbgcolor}
407 \tblhdrstrut\btnhead
409 \endtabularx