FS#12090 - Manual: add metadata section

Attached to Project: Rockbox
Opened by Andree Buschmann (Buschel) - Sunday, 01 May 2011, 20:53 GMT
Last edited by Alexander Levin (fml2) - Monday, 09 May 2011, 20:35 GMT
Task Type Patches
Category Manual
Status Closed
Assigned To No-one
Operating System All players
Severity Low
Priority Normal
Reported Version Release 3.8.1
Due in Version Undecided
Due Date Undecided
Percent Complete 100%
Votes 0
Private No


I have the impression that a reasonable amount of questions in the forums comes from rockbox' metadata implementation. This is why I want to add a metadata section to the manual. This first patch adds such section and provides a table with information about what metadata tag type is used for which file extensions.

Next steps:
- feature overview (e.g. which tags support replaygain, embedded album art, ... in rockbox)
- limitations (e.g. max string lengths)
This task depends upon

Closed by  Alexander Levin (fml2)
Monday, 09 May 2011, 20:35 GMT
Reason for closing:  Accepted
Additional comments about closing:  Committed as r29847
Comment by Dominik Riebeling (bluebrother) - Monday, 02 May 2011, 20:15 GMT
I've had a short look on this (didn't try to build it though). Two (somewhat general) comments:
1. For creating a new section the usual way is to put two consecutive newlines in the code, not \\ which starts a new line. The LaTeX sources should always start new paragraphs, starting a new line is almost never needed. The output is slightly different for new lines and new paragraphs; if the indentation of new paragraphs isn't wanted that should be adjusted in the preamble instead of breaking the document structure with \\ (this is done wrong in the manual in several places unfortunately). The macro \note shouldn't need a separate paragraph before it since it does that itself.
2. using \textbf for the table headings is ugly. I think we had a macro for headers in the past, but I can't find that anymore -- the table macros were changed since.
Comment by Andree Buschmann (Buschel) - Tuesday, 03 May 2011, 20:57 GMT
1. I do not get the point... Can you change my patch in the way you mentioned?
2. This is exactly how the tables which are defined right before this new table are configured. At least this is consistent...
Comment by Alexander Levin (fml2) - Sunday, 08 May 2011, 19:31 GMT
I think the table is typeset correctly. We only have "rbtabular" for the general table layout (heading lines, alternating row colors) but IIRC we don't have a special style for column headers.

As for the sections: Dominik, I think you mean paragraphs? Andree: instead of

audio file extension.\\
\note{There is always only \textbf{one} tag type supported for each file


audio file extension.

\note{There is always only \textbf{one} tag type supported for each file

I.e. no "\\" at the end of line and an empty line before "\note".

Also, if there is always only \textbf{one} tag type supported for each file extension (BTW: here I would use "emph" instead of "textbf"), wouldn't it be better to have just one column and write there which tags are supported instead of many columns with X's?
Comment by Andree Buschmann (Buschel) - Sunday, 08 May 2011, 21:59 GMT
Alexander, thanks for the feedback. I changed the "//" and tried to set up a table with only two columns. Looks much better now.