Downloads

release

dev builds

extras

themes

Documentation

manual

wiki

device status

Support

forums

mailing lists

IRC

Development

bugs

patches

dev guide

Wiki > Main > DocBoxObsolete (r45)

Rockbox documentation work area

This page is for work in progress on the Rockbox documentation.

Todo: Ondio docs

The Ondio docs are as yet unfinished. This is what needs doing.

Please feel free to help out. These tasks are independent and can be done by multiple people and submitted seperately. Let us know here if you've taken on one of these tasks (put your WikiName? in brackets after the text so we don't duplicate effort).

Patches to the documentation should be submitted in OpenOffice format starting from the current RockboxManual via Sourceforge. It's probably best to start a new version of the file (Version from the OO File menu) before you start. Please follow the style guidelines as given below.

Chapters 2-3 need updating to include Ondio keys and any other Ondio specifics.

Chapter 5 needs Ondio keymaps added to all the Ondio compatible plugins, and reference to key mappings in the text removing.

Whole document: No actual key information should be contained within the body of the text. It should, in general be in tables. ideally one for each platform. (ChristiScarborough)

The entire text needs checking for references to to Recorders. Where appropriate, these should be updated to indicate that they also apply to the Ondio.

Chapter 2 - document how to use flash cards with the Ondio.

Other stuff that needs to happen before the next release.

Add section on restoring original firmware

Document flashing the player

Document recording beeps

Document changes to stereo separation settings

Document recording by signal level option

Create infrastructure for multiple platform releases. (ChristiScarborough)

Changes to sleep timer

New plugin: logo

New plugin: rockboy

New plugin: iriverify

Player graphics library - new plugins

OpenOffice settings

OpenOffice has an object oriented styles model. On one hand, this is cool. On the other hand, it you don't use it properly, it sucks.

Try to avoid doing any manual formatting in Rockbox. There are three main circumstances where manual formatting is appropriate.

A genuine one off case - there's some specific formatting that simply doesn't have a general case.

Putting the odd word in bold. There's no point creating a custom style for that. But see "Minor titles" below.

Sometimes there is a single line on its own before a table. In this case manually format the paragraph not the style with "Keep with next paragraph"

NEVER do spacing with carriage returns (the title pages are an exception to this). Use space before, space after in styles / graphics / whatever. Trust me - it's much easier than having to rejig the spacing by hand every time you add something to the document.

Otherwise, the only formatting done should be by selecting the text to format and picking an appropriate style from the Style list. There are a couple of custom styles in the manual:

Minor title - use this for anything that's a title but doesn't want to go in the contents. Why? It binds itself to the following paragraph, so you won't get your titles appearing on their own at the end of a page.

Non-indexed heading - Same as Heading 2, but doesn't appear in the TOC. Used in Chapter 1 to make the intro more 'friendly'.

Table left - Most of our tables have row headings as well as column headings - Use this para style for the left hand column of a table where appropriate

Standard styles we use

Heading 1,2,3 - Section heirarchy - H1 is a section, H2 subsection, H3 subsubsection

Table Heading - Table column headings

Table Body - "Ordinary" table cells

Hyperlink, Footer - guess

Caption - used to format graphics captions.

Default - ordinary text

Changes from the OpenOffice defaults ("Rockbox house style")

Use OpenOffice 1.1.4

The manual is aimed at end users. Technical information of interest to hackers is therefore left or the wiki for now. If someone wants to write more technical documentation, that's great. The manual, however, should remain focused on a more general audience.

Hyperlinks aren't underlined (Acrobat puts a square around them later anyway)

Default Style is changed to URWGothicL, 12pt. The OO default is ugly, because I say so. "Do not split paragraphs" is also turned on in the Default style. It's confusing to have paragraphs cross pages in a manual, let's not. 0.3cm space after paragraph.

We use a postscript font because this allows extendedPDF to create a searchable PDF file. (There's a Ghostscript bug that mates this not work with TT fonts.) It is also nicer than the default font.

URWGothicL.zip: URW gothic font from Aladdin Ghostscript

Caption style is a 0.5cm gap before and after. This relates to the way we show images. Images are anchored as characters and tied to captions by putting them on the same logical line: ie image {hard line break (Shift + Enter)} caption. This "paragraph" is formatted in the "Caption" style, which is centred italic 10pt. It seems to be the only way to get the page end behaviour we'd expect out of images, otherwise the caption and image someitmes swap places at the end of a page leaving the caption on one page and the image at the top of the next. Yuck.

The background colour of table headings is "blue 8" - remember to strip formatting from tables imported from the wiki, unless you want to visually assault the reader.

Tables must be formatted by hand every time. There's no way to set defaults for tables (which sucks) 0.5cm gap before and after, do not split.

Ditto for images. Not sure if you still need to set borders on images with the new formatting method, but if you do it's 0.5 top and bottom

Also 0.5 top and bottom for any frames we might use. (Frames are generic "holders")

Remember - don't change the formatting, change the style. Then OO manages consistency for you, which is nice of it.

When removing erroneous styles, the "Default" item on the Format menu is your friend. This resets the selected area to the formatting selected by the Style. Styles are overridden by local formatting. Most of the time we don't want this.

For the same reason (consistency) any styles we use should be set to "auto-update".

We use the extendedPDF macro (freely available on the Net) to generate PDF output using Ghostscript - why? Because we get nifty bookmarks and hyperlinks, which OO's stardard PDF export doesn't support.

Menu options, configuration option names and filennames and paths (with trailing /) are given in bold Submenus use -> eg Backlight on when plugged, /.rockbox/, /.rockbox/lang/english.lang, Main Menu -> Playlist -> Show Playlist

Configuration options are quoted for text. Times, numbers etc. do not have surrounding quotes. eg "Always on", 1:00, 4

We do not do formatting using carriage returns. Objects such as tables, frames that need formatting should have a 0.5cm space in their before and after "Text Flow" spacing fields. Carriage returns only appear at the end of a paragraph.

Lists in general use the unnumbered list style with a grey button - see the manual. Don't use line breaks in lists unless there's a good reason (Extra paragraphs under a buller point are normally formatted as unbulleted items in the list. This makes the spacing uniform.) Avoid numbered lists if you can, as they can't be treated in this way and end up having to be formatted using line breaks.

If in doubt, find something similar in the manual. The Jukebox comparison table and the explanatory numbered list for the Split Editor are one off exceptions, and should not therefore be taken as examples of general good style. If still in doubt, ask.

Draft Manual

The current documentation master copy is available from RockboxManual.

Not currently active

The files below are copies of of the current draft of the Rockbox 2.3 manual.

rockbox-manual-2.3-draft-3.pdf: Hopefully our final draft of this cycle (PDF)

rockbox-manual-2.3-draft-3.sxw: Much cleaner source this time

CategoryFrontpage: Documentation work area

ChristiScarborough - 24 Jan 2005

buttons.zip: GIMP 2 source images for the button illustrations

r45 - 29 Jan 2006 - 14:22:47 - AliRose?