Rockbox

This is the bug/patch tracker for Rockbox. Click here for more information.

Quick links: Bugs · Patches · Rockbox frontpage

Tasklist

FS#9880 - many minor changes in the manual

Attached to Project: Rockbox
Opened by Johannes Linke (Jaykay) - Saturday, 07 February 2009, 23:18 GMT+2
Last edited by Alex Parker (BigBambi) - Sunday, 17 May 2009, 12:40 GMT+2
Task Type Patches
Category Manual
Status Closed
Assigned To No-one
Player Type All players
Severity Low
Priority Normal
Reported Version Daily build (which?)
Due in Version Undecided
Due Date Undecided
Percent Complete 100%
Private No

Details

the title says it, many minor changes. i didnt go through the whole manual yet, so ill extend it, maybe tomorrow. i also cant check whether its still possible to build the manual, but it should be possible.

i think i have to explain some changes, just ask or say "this change is crap", maybe also why its crap.
   manual.diff (11 KiB) 
 manual/platform/recorder.tex             |    1 -
 manual/getting_started/installation.tex  |   23 +++++++++--------------
 manual/getting_started/ipod_install.tex  |   17 ++++++++---------
 manual/getting_started/main.tex          |    2 +-
 manual/getting_started/sansa_install.tex |   25 +++++++++++++------------
 5 files changed, 31 insertions(+), 37 deletions(-)

This task depends upon

Closed by  Alex Parker (BigBambi)
Sunday, 17 May 2009, 12:40 GMT+2
Reason for closing:  Accepted
Additional comments about closing:  Parts accepted as part of r20900. Thanks!
Comment by Paul Louden (Llorean) - Sunday, 08 February 2009, 01:33 GMT+2
There's a reason we called them "archived builds" instead of "daily builds." Many people seem to think "current" isn't as up to date as "daily" because the phrase daily means it happens every day, and most people assume current can't be more current than "today." "Archived" was selected to make it especially clear that these are _old_ builds.

As well, I'm not sure changing the "fixme" to a warning is a good idea. Fixmes help us keep track of where things need to be fixed, and that certainly does.

I'm also not sure why you removed the reference to the download page in the "updating Rockbox" section.
Comment by Johannes Linke (Jaykay) - Sunday, 08 February 2009, 14:42 GMT+2
"There are three di erent types of rmware binaries available from the Rockbox website: Release version, current build and daily build." - form the manual. i just wanted to bring it in line with this. also the current build is described as "representing the current status", it should be clear that this is the newest version. also the "an archive of daily builds" remains.

i thought the manual is for users, so imo its not the right place for reminders for the developers. its not more important to notice this warning than other ones, e.g. the firmware version, so imo it shouldnt be that highlighted.

the link is only to the releases of rockbox, so useless for those who want to update their current build. anyway it would be an iteration of "manual installation". maybe something like "Download a Rockbox build. as described in 2.3.2 manual installation" would be useful.
Comment by Paul Louden (Llorean) - Sunday, 08 February 2009, 17:10 GMT+2
So add the word "archived" to any instance of "daily build" where there's not already an "archived" before it to bring things more into line, then.

The manual is for users. But the fixme is for developers *of* the manual. Rather than removing the fixme, why not FIX the problem that results in the fixme being there? That's the whole point of it, it says "this section of the manual needs fixed." You chose, rather than fixing it, to just remove the notice that it needs fixed, the exact opposite of its purpose.
Comment by Johannes Linke (Jaykay) - Sunday, 08 February 2009, 18:10 GMT+2
"You can download the archived daily builds from http://www.rockbox.org/daily.shtml"; is that ok?

this "fixme" was added with the commit message "Add a note in the E200 install section referring E200R users to the SansaE200RInstallation wiki page." so it should only be a note. although i think a warning is better here :)
Comment by Paul Louden (Llorean) - Sunday, 08 February 2009, 20:31 GMT+2
A proper fix would be to put the e200r installation instructions in the manual, written as we do our other instructions.
Comment by Johannes Linke (Jaykay) - Sunday, 08 February 2009, 22:16 GMT+2
removed the removal of the fixme, and wrote "the archived daily builds"
   manual2.diff (10.4 KiB) 
 manual/platform/recorder.tex             |    1 -
 manual/getting_started/installation.tex  |   23 +++++++++--------------
 manual/getting_started/ipod_install.tex  |   17 ++++++++---------
 manual/getting_started/main.tex          |    2 +-
 manual/getting_started/sansa_install.tex |   20 ++++++++++----------
 5 files changed, 28 insertions(+), 35 deletions(-)

Comment by Johannes Linke (Jaykay) - Sunday, 08 February 2009, 23:33 GMT+2
only further small changes.
   manual.diff (13.1 KiB) 
 manual/platform/recorder.tex             |    1 
 manual/getting_started/installation.tex  |   42 +++++++++++++------------------
 manual/getting_started/ipod_install.tex  |   17 +++++-------
 manual/getting_started/main.tex          |    2 -
 manual/getting_started/sansa_install.tex |   22 ++++++++--------
 manual/rockbox_interface/main.tex        |    5 +--
 6 files changed, 40 insertions(+), 49 deletions(-)

Comment by Johannes Linke (Jaykay) - Monday, 09 February 2009, 22:34 GMT+2
currently working on more useless changes in the button descriptions for unifying them, a start is in the attached patch. please write if it gets to useless.

   manual.diff (20.8 KiB) 
 manual/platform/recorder.tex             |    1 
 manual/getting_started/installation.tex  |   42 ++++++--------
 manual/getting_started/ipod_install.tex  |   17 ++---
 manual/getting_started/main.tex          |    2 
 manual/getting_started/sansa_install.tex |   22 +++----
 manual/rockbox_interface/main.tex        |   90 ++++++++++++++-----------------
 6 files changed, 80 insertions(+), 94 deletions(-)

Comment by Alex Parker (BigBambi) - Wednesday, 18 February 2009, 12:50 GMT+2
Hi,

It is likely that some of this doesn't apply any more after http://svn.rockbox.org/viewvc.cgi?view=rev;revision=20034 or at least needs resynching. If you do that and let me know when it is done, I'll have a look at it.
Comment by Johannes Linke (Jaykay) - Thursday, 19 February 2009, 18:37 GMT+2
this is the remaining part less the changes in the buttons. its not really much, i admit.

i have to do the part with the buttons again...
   manualreduced.diff (5.7 KiB) 
 manual/platform/recorder.tex            |    1 -
 manual/getting_started/installation.tex |   32 ++++++++++++--------------------
 manual/getting_started/main.tex         |    2 +-
 3 files changed, 13 insertions(+), 22 deletions(-)

Comment by Johannes Linke (Jaykay) - Thursday, 19 February 2009, 18:50 GMT+2
i missed some changes...
   manualreduced.diff (9.5 KiB) 
 manual/platform/recorder.tex             |    1 
 manual/getting_started/installation.tex  |   32 +++++++++++--------------------
 manual/getting_started/ipod_install.tex  |    6 ++---
 manual/getting_started/main.tex          |    2 -
 manual/getting_started/sansa_install.tex |    6 ++---
 manual/rockbox_interface/main.tex        |    2 -
 6 files changed, 20 insertions(+), 29 deletions(-)

Comment by Alex Parker (BigBambi) - Friday, 20 February 2009, 09:39 GMT+2
Have you checked this builds? Some of the changes I will add, others I'm less sure about.

For instance, why did you remove the \index{Firewire} ? I will admit here to not being sure what it does, but do you? Do you know it isn't there for a reason?

Anyway, I'll have a closer look when I get home tonight.

Comment by Johannes Linke (Jaykay) - Friday, 20 February 2009, 16:00 GMT+2
no, i havent, because i cant, latex is not working properly.

i only changed "index" to "note", as the index produced a note, so there should be no difference in the outcome.
Comment by Alex Parker (BigBambi) - Friday, 20 February 2009, 22:05 GMT+2
The user visible aspect is only one of them - this is like your changing of the fixme - just because you can't see anything in the output doesn't mean it isn't important.

You should try and get latex working - it would be nice to know you had done test builds, a single misplaced } can break manuals.
Comment by Johannes Linke (Jaykay) - Monday, 06 April 2009, 18:07 GMT+2
now with all changes in chapter one and two. i didn't change much of the content, the most changes are "code-police"

i tested it for some players and it builds fine.

if i should explain something, please ask...
   manual.diff (33.8 KiB) 
 manual/platform/recorder.tex               |    1 
 manual/advanced_topics/archos-flashing.tex |    4 
 manual/rockbox_interface/main.tex          |    2 
 manual/getting_started/installation.tex    |  306 +++++++++++++----------------
 manual/getting_started/ipod_install.tex    |    6 
 manual/getting_started/main.tex            |   34 +--
 manual/getting_started/sansa_install.tex   |    6 
 7 files changed, 164 insertions(+), 195 deletions(-)

Comment by Alex Parker (BigBambi) - Tuesday, 07 April 2009, 11:04 GMT+2
Could you do two different patches, one for "code-police" and one for content changes? It is very difficult to see actual changes in amongst all the whitespace changes. Thanks.
Comment by Frank Gevaerts (fg) - Tuesday, 07 April 2009, 13:38 GMT+2
Please don't remove the warning about recovery mode for sansa
Comment by Johannes Linke (Jaykay) - Tuesday, 07 April 2009, 19:48 GMT+2
linuxstb and BigBambi complained about the removal of "if all has gone well...", i left it in the patch for now.

and gevaerts complained about the removal of this warning, i remvoed it (the removal), but i really don't like the warning there. the manual NEVER says anything about the recovery mode, it also says nothing about how to get there. and it really doesn't fit in this place.

any opinions about these two "problems"?
   manualreal.diff (8.8 KiB) 
 manual/advanced_topics/archos-flashing.tex |    4 ++--
 manual/rockbox_interface/main.tex          |    2 +-
 manual/getting_started/installation.tex    |   10 +++-------
 manual/getting_started/ipod_install.tex    |    6 +++---
 manual/getting_started/main.tex            |   17 ++++++++---------
 manual/getting_started/sansa_install.tex   |    6 +++---
 6 files changed, 20 insertions(+), 25 deletions(-)

   manualwhite.diff (26.3 KiB) 
 manual/platform/recorder.tex            |    1 
 manual/getting_started/installation.tex |  294 ++++++++++++++------------------
 manual/getting_started/main.tex         |   17 -
 3 files changed, 144 insertions(+), 168 deletions(-)

Comment by Paul Louden (Llorean) - Tuesday, 07 April 2009, 20:06 GMT+2
Recovery mode is a feature of the original firmware. It's not our responsibility to document even the existence of OF features.

We shouldn't remove a warning that's valid and important just because it mentions a feature in the Original Firmware. If they don't know about the feature, the warning won't matter to them. if they DO know about the feature, the warning can prevent them from making a mistake that causes it to be significantly more difficult to get their player working again.

If you think it doesn't fit there, find someplace better to put it. And if you think the existence of recovery mode needs to be documented further (it shouldn't - no user should ever need to enter it) do so. But don't remove valid and important warnings.
Comment by Johannes Linke (Jaykay) - Tuesday, 07 April 2009, 20:21 GMT+2
as i said, the last patch doesn't remove this warning.

and i never said that we should document it. i said, if its not documented, why should we warn about it? its like "the OF has [a bug] which causes it to crash on playing [a file]". you don't write that in the manual too.

but i'll leave it as it is if you mean this warning is necessary.
Comment by Paul Louden (Llorean) - Tuesday, 07 April 2009, 20:41 GMT+2
Are you very familiar with the c200/e200?

"Recovery Mode" is a mode the original manufacturer included that may be used for firmware updates. People aware of this mode may think they're supposed to use it for firmware updates if they don't understand the real situations it should be used in. It's not a bug in the mode that's the problem. It's the fact that people may misunderstand and use it if not warned about it. It's similar to saying "please make sure you run the firmware patcher as root." We don't describe what root access means, or other OS features of the host system or anything, but it's still an important point.

A playback crash in the OF is very different from "this process which may have been recommended to you in the past by the official manufacturer for a firmware update should absolutely not be used."
Comment by Johannes Linke (Jaykay) - Tuesday, 07 April 2009, 21:27 GMT+2
the user is not instructed to enter the recovery mode, if he follows the instructions he doesn't enter it. i think the manual should describe what the user *should* do, not what he should *not* do."make sure you run the patcher as root" is the first case, "don't enter the recovery mode" the second one.

but we are discussing about nothing here since it doesn't have any effect, i'll leave the patch as it is.
Comment by Alex Parker (BigBambi) - Sunday, 10 May 2009, 20:54 GMT+2
I' ve committed those parts of the real changes that I think should go in as part of r20900. I'm not really sure about the whitespace changes - they seem more like changes for changes sake.

Loading...