Discussion of the LaTeX Style Guidelines

Note: please add the actual time to your name to make it easier following the discussion "thread".

Discussion

We need to establish a naming convention of the images used in the manual, and also agree on a sensible directory structure. Please discuss and give feedback on this topic. Proposal: The images are separated by chapters, i.e.

chapter/images/platform/

E.g.

chapter1/images/h1xx/ss_main_menu.png

A naming convention could be ss_what_screen.png, where ss implies a screenshot. Could be useful to have the naming convention separate screenshots from other images, such as images of the devices etc. The screenshots can be used across platforms using the \platform macro:

 \includegraphics{chapter5/\platform/ss_sudoku_main.png}

or similar. LaTeX will make sure that the screenshot from the correct subdirectory is chosen.

DaveChapman - This approach doesn't take advantage of the fact that for targets with the same LCD size and depth (such as the H300 and iPod Photo, the H1x0 and iPod 3G or 4G, or most of the Archos devices), 95% of the screenshots will be identical. One solution would be to have two macros - something like \genericimgdir and \platformimgdir and two corresponding directories, such as images/220x176x16, images/h300 and images/ipodcolor. Images which are the same for all targets with a certain size/depth LCD will be in the genericimgdir, and images which are different will be in the platformimgdir. Also, storing images inside the chapter directory means that we need one big set of directories for every chapter - would it be unmanageable to just have all the images (for all chapters) inside one top-level images/ directory hierarchy?

MartinArver - I think we should have separate image directories for all the chapters. This will have the benefit of chapters being atomic units, with all the files needed contained within those units. I had a look at the device chart, and we would need the following different screenshots. I think it sounds like a splendid idea to split by feature instead of by target in this case.

char11x2x1
112x64x1
138x110x2
160x128x2
160x128x16
176x132x16
220x176x16
320x240x16

And of course the remotes:

128x64x1
128x96x2

Which will be the same for both h300 and h1xx.

HenricoWitvliet - And for simplicity for the writers I would choose 1 subdirectory for each platform. If the H300 and the iPod are nearly identical, then the screenshots can be taken once and copied.

HenricoWitvliet - Another possibility would be to give each main file in every chapter the same name, and to give special files such as the plugins descriptive names:

getting_started/main.tex
...
plugins/main.tex
plugins/bounce.tex
...

MartinArver - I agree, I think this looks like a good way of arranging the chapters.

MartinArver - Another issue is what the standard Rockbox interface should look like. Should the default font and WPS change? This might not apply to all targets, but those with a higher resolution than that of the archoses do look prettier with a larger font and newer WPS's (boxes perhaps?)

MichaelDiFebbo - this is a minor point, but iriver spells its own name these days using all lowercase letters, rather than "iRiver." I've tried to use that convention in the WikiManual, so the extent that text is copied from there, it will use the lowercase version in most instances. Whatever we use (and lowercase would be my preference), we should be consistent.

ThomJohansen - I wish to raise the point of whether we really want to start caring about how all these people want their names lettered and spelled. Can't we just try conforming to english language standards of using a front capital letter in all names instead of degenerating into what is starting to look more and more like hieroglyphic tendencies with graphic icons instead of combinations of letters? Should we also soon start caring what font they're using?

MartinArver - I agree with Thom here.

MartinArver - I think it's easier to work with the docs if long sections are separated to their own files. If you want to split a section this way. This will also lower the probability of clashes if two people want to work on the same chapter. Have a look at the appendix, or the plugins chapter for examples of this. I would like to encourage people to split up the files they are working on.

MartinArver - I write it here so that I don't forget. We have to make sure to add a backslash after the macros if we want a space after it. For instance ...the \dap\ is ...

NilsWallmenius - Any thoughts on removing grayscale and helloworld plugins from the manual, they aren't in the builds anymore and the guidelines above state that the manual should be for users, not hackers.

ThomJohansen - I don't think this is anything to think about, just remove them. Users are not supposed to see those plugins anyway, unless they're coders. At any rate I don't think they need documentation.

MartinArver - How do you think we should treat tables and images? It looks like it is too unpredictable where floats end up. Another thing is the size of tables. Should we define the tables within a minipage or a scalebox so that we always get the same size? If we do this, I think we can choke a number of the 'overfull hbox" warnings we get now.

MichaelDiFebbo--Chapter 4 of the manual, "Configuring Rockbox," is very long, and has quite a few subsections,itemizations, etc. I propose that this chapter be broken into two separate chapters: "Configuring Rockbox: the Sound Settings Menu," and "Configuring Rockbox: the General Settings Menu." This will reduce the amount of indenting needed, particularly in the General Settings/Playback Options section.

MartinArver - When we commit our changes, or write a patch for inclusion. Please make sure that the manual builds for at least the player, recorder, ondio, h100, h300, x5 and an ipod. This will help in reducing the risk for hard to find errors. A typical error would for instance be to include a \end{itemize} in a section only valid for HAVE_LCD_BITMAP. Then, we will not notice this, unless we build a manual for the player.

NilsWallmenius - Plugins chapter is starting to shape up I've left out some plugins for now, (the experimental stuff like wavplay, wav2wv, midi2wav etc, Iriverify, the database related plugins databox and searchengine) Doom should be added but since it's still early it might change a lot. Anyway I'm going away on a long trip soon and will not be able to contribute much more until June probably...

DominikRiebeling - 05 Apr 2006 - I think we should introduce some generic button macros: \BtnStop, \BtnPlay, \BtnMenu, \BtnSelect -- this should be something on any player. Or did I miss something? Any more keys that could be calles "generic"? opt-ing every type gives me a PITA.

MartinArver - While I totally agree that the button opt-ing is a PITA, the reason for doing this is to mirror the way the code works. Problem is that the different players do have very few button in common. Like some players do not have stop (ipod). To be able to do it like you propose, we need to invent our own scheme for this. I am not sure what this would look like though.

MichaelDiFebbo - 02 May 2006 - We have inconsistencies regarding whether periods and commas are placed within a quotation, or after the quotation mark. In America, at least, it is proper to put the punctuation inside the quotation mark as a general rule. E.G., The Playlist Submenu allows you to put new songs into a "dynamic playlist." (Not, "dynamic playlist".) (There are exceptions for question marks and exclamation points in some circumstances but I don't think that those are relevant here.) What is the British convention for this?

ThomJohansen - 03 May 2006 - I believe punctuation within quotation marks is something you primarily do when you're actually quoting something. In the example you mention, I don't particularily see the need for quotation marks at all. Wouldn't \emph be better? In that case, the general typographical preference is including the punctuation in the \emph command for better letterfitting between punctuation and letters, but that's another thing entirely.

MichaelDiFebbo - 03 May 2006 - I probably could have used a better example, but as I skim through the manual, most of the quotation mark issues that I am noticing relate to settings (e.g., If "Auto Change Directory" is set to "No," playback will ...). As I read the LatexGuidelines, we should be using \setting for these anyway, so that will eliminate most of my punctuation concerns.

MarianneArnold - 11 Oct 2009 - Time to dig up this topic/page as I want to put up something for discussion where I'd like some input of others and where it is easier to show an example. When looking at the remote button columns in the button tables (especially those in the plugin chapter), I have a very hard time to read and understand those. Almost all button tables look differently code-wise and in some it's very hard to find the column and the line delimiters (some put the & for next column on the same line, or sometimes the \\ can be found at the same line too etc.) - a very "nice" example is the table in goban.tex. My suggestion is to go through all of them and clean it up if we can find and agree on a style. The following should visualise my suggestion:

\begin{btnmap}{}{}
    \opt{PLAYER_PAD}{\ButtonPlay}                       % first line, first column
    \opt{IRIVER_H10_PAD}{\ButtonRew}                    % main targets' button assignment
        &                                               %     & column delimiter
    \opt{HAVEREMOTEKEYMAP}{                             % first line, start of optional
        \opt{IRIVER_RC_H100_PAD}{\ButtonRCPlay}         % second column
        \opt{IAUDIO_RC_PAD}{\ButtonRCMenu}              % remotes' button assignment
        &}                                              %     & optional column delimiter
    Play                                                % first line, second/third column explains the action
    \\                                                  % \\ line delimiter
                                                        % blank line to mark the line break a bit stronger
    \opt{PLAYER_PAD}{\ButtonStop}                       % second line, first column
    \opt{IRIVER_H10_PAD}{\ButtonPower}                  %
        &                                               %
    \opt{HAVEREMOTEKEYMAP}{                             % second line, optional second column
        \opt{IRIVER_RC_H100_PAD,IAUDIO_RC_PAD}{}        %
        &}                                              % discuss whether the } belongs here but that's better readable IMO
    Exit the game                                       % second line, last column
    \\                                                  %
\end{btnmap}

There are still some questions left

• How to indent optional lines, I mean the complete block with the 2-3 columns.
• What to do with "directional keys" vs, "up", "down", "left", "right" vs. "up, down, left, right", especially as the last on can lead to a list broken into 2..3 lines and very weird breaks between e.g. "scroll" and "forward" etc.

Any ideas, suggestions, comments welcome.