Timestretch feature doc is not adequate

[LenW]

I tried to turn on the timestretch feature on my Sansa e280 (v1).
According to the manual all I needed to do to activate that setting was to reboot.
The actual procedure is a little more elaborate and is nicely explained at
http://www.rockbox.org/mail/archive/rockbox-archive-2010-10/0033.shtml.
Would have saved me quite a bit of time had that been in the manual.

Something like:

on p36 (in 4.3.3  The WPS Context Menu  ->  Pitch):

Code: [Select]

If you've enabled the Timestretch option in Sound Settings and have since re-
booted, you can also use timestretch mode. This allows you to change the playback
speed without affecting the pitch, and vice versa.
   In timestretch mode there are separate displays for pitch and speed, and each can be
altered independently. ...

change to:

Code: [Select]

If you've enabled the Timestretch option in Sound Settings and have 
activated it (see section 6.10 (page 57)),
you can also use timestretch mode. This allows you to change the playback 
speed without affecting the pitch, and vice versa.
   In timestretch mode the Pitch screen has separate displays for pitch and speed, and each can be 
altered independently. ...

------------------------------------------------------------
on p57

Code: [Select]

6.10 Timestretch
Enabling Timestretch allows you to change the playback speed without it affecting
the pitch of the recording. After enabling this feature and rebooting, you can access
this via the Pitch Screen. This function is intended for speech playback and may
significantly dilute your listening experience with more complex audio. See section 4.3.3
(page 36) for more details about how to use the feature.

change to:

Code: [Select]

6.10 Timestretch
Enabling Timestretch allows you to change the playback speed without it affecting
the pitch of the recording. After enabling this feature in the Sound Settings, 
you must reboot and then activate Timestretch by going into the Pitch screen and
pressing the REC button until you see both of the words "Pitch" and "Speed" in the 
middle of the screen.  After that you can control pitch and speed separately 
via the Pitch Screen.  (If you see "Rate" in the middle then the pitch and the
speed are changed together.) 
This function is intended for speech playback and may
significantly dilute your listening experience with more complex audio. See section 4.3.3
(page 36) for more details about how to use the feature.

[[Saint]]

I half understand this, and the docs could definitely stand some improvement in some areas.

However, the reason why I only half understand this is the issue of what you expected to happen. Enabling timestretch and activating it (as you have found out), are two completely separate things.

What exactly did you expect to happen?

This is a serious question, did you expect that enabling timestretch would automatically start to shorten/lengthen the current track immediately after reboot without any further user configuration? And if so, which...shorten or lengthen playback, and by how much? That to me sounds as though it would be very undesirable, and non-obvious behaviour.

As it is currently, the manual does explicitly state that enabling timestretch will have essentially no effect, other than allowing you to configure playback speed via the pitch screen, in addition to pitch.

The only thing I think might need some further clarification is the player specific button to change modes in the pitch screen, other than that, I think the function is accurately described.


[Saint]

[LenW]

Good grief!  I see what happened.  I never saw the Keystroke table
in the "Pitch" discussion of section "4.3.3. The WPS Context Menu" !
The table doesn't quite fit on the page with the desscription, so
there is a lot of white space at the bottom of the page, which I guess
meant to me that the section had ended, and I stopped reading.
Now it all makes sense.

I have no idea how many people make that mistake, but it might be
something to think about when laying out the manual.

Thanks for your very patient reply and sorry for the confusion.
And thanks for Rockbox!
-Len

[bluebrother]

I have no idea how many people make that mistake, but it might be
something to think about when laying out the manual.

The manual is done using LaTeX, which is responsible for the layout. For LaTeX, tables are not breakable (which usually makes sense, you can create tables that are breakable, but that is usually a bad idea), and for that specific manual the table simply doesn't fit on that page anymore -- it's not because someone decided to put the table on the next page. However, depending on the manual contents (which means if someone changes the text before that, or if the contents change  because the manual is built for a different player) the break might happen in some other location.

So while it would make sense to check (and possibly tweak) all manuals at least for releases this is unlikely to happen simply because it's a lot of work -- and the manuals are created automatically.

[LenW]

Thanks for the info.  Again, just a thought for the future, but it would
have helped me if there had just been a casual mention of "the following
keystroke table" in the text part of that session.  This probebaly makes
sense only when the table is on a separate page, which I understand is
hard to predict.  Or perhaps if each table had a little "table follows"
header it would be easy to ignore when it wasn't separated from its table.
(Just a thought, for what it's worth.)

Well, maybe it's time for me to take a little trip straight through the
manual, now that I've been using Rockbox for a few days and have my
bearings.  That just seemed daunting without any context.
(Again, sorry for the confusion.)

-Len
I don't know if this actually works, but I have tried to
change the title of this thread to:
"Spacing of tables in manual sometimes slightly confusing"

[saratoga]

Thanks for the info.  Again, just a thought for the future, but it would
have helped me if there had just been a casual mention of "the following
keystroke table" in the text part of that session.  This probebaly makes
sense only when the table is on a separate page, which I understand is
hard to predict.  Or perhaps if each table had a little "table follows"
header it would be easy to ignore when it wasn't separated from its table.
(Just a thought, for what it's worth.)

Well, maybe it's time for me to take a little trip straight through the
manual, now that I've been using Rockbox for a few days and have my
bearings.  That just seemed daunting without any context.
(Again, sorry for the confusion.)

-Len
I don't know if this actually works, but I have tried to
change the title of this thread to:
"Spacing of tables in manual sometimes slightly confusing"

To best honest, a lot of parts of the manual could use revision.  If you're interested in working on them, you can submit revisions directly using gerrit (or less directly but still fairly easy for me to review on flyspray).