|
|
Index page for the LateX documentation of rockbox.LaTeX and RockboxThe 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 isLaTeX 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 GuidelinesThe 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 environmentDownload the Rockbox sourceIn 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/rockboxThis 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 LaTeXSee LatexInstallationWindows editorWhen 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 manualCreate 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-manNow, 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/configureThis will generate a Makefile, and to finally build the manual do: make manualWith the introduction of the HTML version of the manual there are now some new targets to make :
SPLITHTML=1 make manual-zipBe aware that building the HTML version relies on TeX4ht which does the complete processing. Dealing with multiple targetsHow 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 filesSeveral 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?
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.GuidelinesSee LatexGuidelines.Creating a patchSee 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 DiscussionSee LatexGuidelinesTalkHelpful linksA 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.r93 - 02 Apr 2021 - 20:46:07 - UnknownUser
Copyright © by the contributing authors.
|