Cleanup WPS tags appendix a bit and add macro for wps tag tables.

git-svn-id: svn://svn.rockbox.org/rockbox/trunk@9587 a1c6a512-1295-4272-9138-f99709370657

3 files changed, 160 insertions, 146 deletions

diff --git a/manual/appendix/appendix.tex b/manual/appendix/appendix.tex
index f26e03eebf..06eeda0595 100644
--- a/manual/appendix/appendix.tex
+++ b/manual/appendix/appendix.tex
@@ -1,3 +1,4 @@
+% $Id$ %
 \appendix
 \chapter{File formats}
 \section{\label{ref:Supportedfileformats}Supported file formats}
@@ -35,7 +36,6 @@
 \end{tabularx}
 \end{center}
 
-\chapter{\label{ref:wps_tags}WPS Tags}
 \input{appendix/wps_tags.tex}
 
 \chapter{\label{ref:config_file_options}Config file options}
diff --git a/manual/appendix/wps_tags.tex b/manual/appendix/wps_tags.tex
index c3f183da86..ae349ccec8 100644
--- a/manual/appendix/wps_tags.tex
+++ b/manual/appendix/wps_tags.tex
@@ -1,17 +1,15 @@
-\subsubsection{Status Bar}
-\begin{tabularx}{\textwidth}{lX}\toprule
-\textbf{Tag} & \textbf{Description}\\\midrule
+% $Id$ %
+\chapter{\label{ref:wps_tags}WPS Tags}
+\section{Status Bar}
+\begin{tagmap}{}{}
 \%we & Status Bar Enabled\\
-\%wd & Status Bar Disabled\\\bottomrule
-\end{tabularx}
-\newline
-\newline
-These tags override the player setting for the display of the status bar, they must be on their own line.
+\%wd & Status Bar Disabled\\
+\end{tagmap}
+These tags override the player setting for the display of the status bar.
+They must be noted on their own line.
 
-\subsubsection{ID3 Info}
-
-  \begin{tabularx}{\textwidth}{lX}\toprule
-    \textbf{Tag} & \textbf{Description}\\\midrule
+\section{ID3 Info}
+  \begin{tagmap}{}{}
     \%ia & ID3 Artist\\
     \%ic & ID3 Composer\\
     \%id & ID3 Album Name\\
@@ -19,65 +17,63 @@ These tags override the player setting for the display of the status bar, they m
     \%in & ID3 Track Number\\
     \%it & ID3 Track Title\\
     \%iv & ID3 Version (1.0, 1.1, 2.2, 2.3, 2.4 or empty if no id3 tag)\\
-    \%iy & ID3 Year\\\bottomrule
-  \end{tabularx}
-\newline
-\newline
-Remember that this information is not always available, so use the conditionals to show alternate information in preference to assuming.
-
-\subsubsection{Power Related Information}
+    \%iy & ID3 Year\\
+  \end{tagmap}
+Remember that this information is not always available, so use the 
+conditionals to show alternate information in preference to assuming.
 
-  \begin{tabularx}{\textwidth}{lX}\toprule
-    \textbf{Tag} & \textbf{Description}\\\midrule
+\section{Power Related Information}
+  \begin{tagmap}{}{}
     \%bl & Show numeric battery level in percent.\\
-         & Can also be used in a conditional: \%?bl{\textless}0{\textbar}1{\textbar}2{\textbar}3{\textbar}4{\textgreater}\\
+         & Can also be used in a conditional: 
+           \%?bl{\textless}0{\textbar}1{\textbar}2{\textbar}3{\textbar}4{\textgreater}\\
     \%bv & Show the battery level in volts\\
     \%bt & Show estimated battery time left\\
-    \%bp & "p" if the charger is connected \\
+    \%bp & ``p'' if the charger is connected \\
          & (only on targets that can charge batteries)\\
-    \%bc & "c" if the unit is currently charging the battery\\
+    \%bc & ``c'' if the unit is currently charging the battery\\
          & (only on targets that have software charge control or monitoring)\\
     \%bs & Sleep timer. Shows the remaining time if the sleeptimer is set\\
-  \bottomrule
-  \end{tabularx}
+  \end{tagmap}
 
-\subsubsection{File Info}
-
-  \begin{tabularx}{\textwidth}{lX}\toprule
-    \textbf{Tag} & \textbf{Description}\\\midrule
+\section{File Info}
+  \begin{tagmap}{}{}
     \%fb & File Bitrate (in kbps)\\
-    \%fc & File Codec (e.g. "MP3" or "FLAC")\\
+    \%fc & File Codec (e.g. ``MP3'' or ``FLAC'')\\
          & This tag can also be used in a conditional tag,\\
-         & \%?fc{\textless}mp1{\textbar}mp2{\textbar}mp3{\textbar}wav{\textbar}vorbis{\textbar}flac{\textbar}mpc{\textbar}a52{\textbar}wavpack{\textbar}unknown{\textgreater} %
-           The codec order is as follows: MP1, MP2, MP3, WAV, Ogg Vorbis (OGG),%
+         & \%?fc{\textless}mp1{\textbar}mp2{\textbar}mp3{\textbar}wav%
+           {\textbar}vorbis{\textbar}flac{\textbar}mpc{\textbar}a52%
+           {\textbar}wavpack{\textbar}unknown{\textgreater}\\ %
+         & The codec order is as follows: MP1, MP2, MP3, WAV, Ogg Vorbis (OGG),%
            FLAC, MPC, AC3, WavPack (WV), ALAC, AAC, Shorten (SHN), AIFF\\
     \%ff & File Frequency (in Hz)\\
     \%fm & File Name\\
     \%fn & File Name (without extension)\\
     \%fp & File Path\\
     \%fs & File Size (In Kilobytes)\\
-    \%fv & "(avg)" if variable bit rate or "" if constant bit rate\\
+    \%fv & ``(avg)'' if variable bit rate or ``'' if constant bit rate\\
     \%d1 & First directory from end of file path.\\
     \%d2 & Second directory from end of file path.\\
-    \%d3 & Third directory from end of file path.\\\bottomrule
-  \end{tabularx}
-\newline
-\newline
-Example for the the \%dN commands: If the path is "/Rock/Kent/Isola/11 - 747.mp3", \%d1 is "Isola", \%d2 is "Kent"... You get the picture.
-
-\subsubsection{Playlist/Song Info}
-
-  \begin{tabularx}{\textwidth}{lX}\toprule
-    \textbf{Tag} & \textbf{Description}\\\midrule
+    \%d3 & Third directory from end of file path.\\
+  \end{tagmap}
+Example for the the \%dN commands: If the path is 
+``/Rock/Kent/Isola/11 - 747.mp3'', \%d1 is ``Isola'', \%d2 is ``Kent'' \dots
+You get the picture.
+
+\section{Playlist/Song Info}
+  \begin{tagmap}{}{}
     \%pb & Progress Bar\\
     \opt{player}{
-          & This will display a 1 character "cup" %
+          & This will display a 1 character ``cup'' %
             that empties as the time progresses.}
     \opt{recorder,recorderv2fm,h1xx,h300,ipodcolor,ipodnano}{
          & This will replace the entire line with a progress bar. \\
          & You can set the height, position and width of the progressbar %
-           (in pixels): \%pb{\textbar}height{\textbar}leftpos{\textbar}rightpos{\textbar}} \\
-    \%pf & Player: Full-line progress bar + time display\\
+           (in pixels): \%pb{\textbar}height{\textbar}leftpos%
+           {\textbar}rightpos{\textbar}} \\
+    \opt{player}{
+    \%pf & Full-line progress bar \& time display\\
+    }
     \%pc & Current Time In Song\\
     \%pe & Total Number of Playlist Entries\\
     \%pm & Peak Meter (Recorder only) The entire line is used as volume peak meter.\\
@@ -87,80 +83,76 @@ Example for the the \%dN commands: If the path is "/Rock/Kent/Isola/11 - 747.mp3
     \%ps & Shuffle. Shows 's' if shuffle mode is enabled.\\
     \%pt & Total Track Time\\
     \%pv & Current volume. Can also be used in a conditional: \\
-         & \%?pv{\textless}0{\textbar}1{\textbar}2{\textbar}3{\textbar}4{\textbar}5{\textbar}6{\textbar}7{\textbar}8{\textbar}9{\textbar}10{\textgreater}\\\bottomrule
-  \end{tabularx}
+         & \%?pv{\textless}0{\textbar}1{\textbar}2{\textbar}3%
+           {\textbar}4{\textbar}5{\textbar}6{\textbar}7{\textbar}8%
+           {\textbar}9{\textbar}10{\textgreater}\\
+  \end{tagmap}
 
-\subsubsection{Runtime Database}
-
-  \begin{tabularx}{\textwidth}{lX}\toprule
-    \textbf{Tag} & \textbf{Description}\\\midrule
+\section{Runtime Database}
+  \begin{tagmap}{}{}
     \%rp & Song playcount\\
     \%rr & Song rating (0-10). This tag can also be used in a conditional tag, %
-           \%?rr{\textless}0{\textbar}1{\textbar}2{\textbar}3{\textbar}4{\textbar}5{\textbar}6{\textbar}7{\textbar}8{\textbar}9{\textbar}10{\textgreater}\\\bottomrule
-  \end{tabularx}
+           \%?rr{\textless}0{\textbar}1{\textbar}2{\textbar}3{\textbar}%
+           4{\textbar}5{\textbar}6{\textbar}7{\textbar}8{\textbar}9{\textbar}%
+           10{\textgreater}\\
+  \end{tagmap}
 
 \opt{h1xx,h300}{
-\subsubsection{Hold Switches}
-
-  \begin{tabularx}{\textwidth}{lX}\toprule
-    \textbf{Tag} & \textbf{Description}\\\midrule
-    \%mh & "h" if the main unit hold switch is on\\
-    \%mr & "r" if the remote hold switch is on\\\bottomrule
-  \end{tabularx}
+\section{Hold Switches}
+  \begin{tagmap}{}{}
+    \%mh & ``h'' if the main unit hold switch is on\\
+    \%mr & ``r'' if the remote hold switch is on\\
+  \end{tagmap}
 }
 
-\subsubsection{Virtual LED}
-
-  \begin{tabularx}{\textwidth}{lX}\toprule
-    \textbf{Tag} & \textbf{Description}\\\midrule
-    \%lh & "h" if there is hard disk activity\\\bottomrule
-  \end{tabularx}
-
-\subsubsection{Repeat Mode}
-
-  \begin{tabularx}{\textwidth}{lX}\toprule
-    \textbf{Tag} & \textbf{Description}\\\midrule
-    \%mm & Repeat mode, 0-4, in the order: Off, All, One, Shuffle\opt{player,recorder,recorderv2fm}{, A-B}\\\bottomrule
-  \end{tabularx}
-\newline
-\newline
-Example: \%?mm{\textless}Off{\textbar}All{\textbar}One{\textbar}Shuffle{\textbar}A-B{\textgreater}
-
-\subsubsection{Playback Mode Tags}
-
-  \begin{tabularx}{\textwidth}{lX}\toprule
-    \textbf{Tag} & \textbf{Description}\\\midrule
-    \%mp & Play status, 0-4, in the order: Stop, Play, Pause, Fast forward, Rewind\\\bottomrule
-  \end{tabularx}
-\newline
-\newline
-Example: \%?mp{\textless}Stop{\textbar}Play{\textbar}Pause{\textbar}Ffwd{\textbar}Rew{\textgreater}
-
-\subsubsection{Images}
-
-  \begin{tabularx}{\textwidth}{lX}\toprule
-    \textbf{Tag} & \textbf{Description}\\\midrule
-    \%X{\textbar}filename.bmp{\textbar} & Load and set a backdrop image for the WPS. %
-                        This image must be exactly the same size as your LCD.\\
-    \%P{\textbar}filename.bmp{\textbar} & Load a Progress bar image for the WPS. %
-                        Use \%pb tag to show the progress bar\\
-    \%x{\textbar}n{\textbar}filename{\textbar}x{\textbar}y{\textbar} & Load and display an image\\
-                        & n = image ID (a-z and A-Z)\\
-                        & filename = filename (relative to /.rockbox/ and including .bmp)\\
-                        & x = x coordinate\\
-                        & y = y coordinate.\\
-    \%xl{\textbar}n{\textbar}filename{\textbar}x{\textbar}y{\textbar} & Preload an image for later display\\
-                         & n = image ID (a-z and A-Z)\\
-                         & filename = filename (relative to /.rockbox/ and including .bmp)\\
-                         & x = x coordinate\\
-                         & y = y coordinate.\\
+\section{Virtual LED}
+  \begin{tagmap}{}{}
+    \%lh & ``h'' if there is hard disk activity\\
+  \end{tagmap}
+
+\section{Repeat Mode}
+  \begin{tagmap}{}{}
+    \%mm & Repeat mode, 0-4, in the order: Off, All, One, Shuffle
+           \opt{player,recorder,recorderv2fm}{, A-B}\\
+  \end{tagmap}
+Example: \%?mm{\textless}Off{\textbar}All{\textbar}One{\textbar}Shuffle%
+{\textbar}A-B{\textgreater}
+
+\section{Playback Mode Tags}
+  \begin{tagmap}{}{}
+    \%mp & Play status, 0-4, in the order: Stop, Play, Pause, 
+           Fast forward, Rewind\\
+  \end{tagmap}
+Example: \%?mp{\textless}Stop{\textbar}Play{\textbar}Pause{\textbar}%
+Ffwd{\textbar}Rew{\textgreater}
+
+\section{Images}
+  \begin{tagmap}{}{}
+    \opt{h300,x5,ipodcolor,ipodvideo}{
+    \%X{\textbar}filename.bmp{\textbar} 
+        & Load and set a backdrop image for the WPS. %
+          This image must be exactly the same size as your LCD.\\
+    }
+    \%P{\textbar}filename.bmp{\textbar} 
+        & Load a Progress bar image for the WPS. Use \%pb tag to show the 
+          progress bar\\
+    \%x{\textbar}n{\textbar}filename{\textbar}x{\textbar}y{\textbar} 
+        & Load and display an image\\
+        & n: image ID (a-z and A-Z)\\
+        & filename: filename relative to \fname{/.rockbox/} and including .bmp\\
+        & x: x coordinate\\
+        & y: y coordinate.\\
+    \%xl{\textbar}n{\textbar}filename{\textbar}x{\textbar}y{\textbar} 
+        & Preload an image for later display\\
+        & n: image ID (a-z and A-Z)\\
+        & filename: filename relative to \fname{/.rockbox/} and including .bmp\\
+        & x: x coordinate\\
+        & y: y coordinate.\\
     \%xdn & Display a preloaded image\\
+        & n: image ID (a-z and A-Z)\\
+  \end{tagmap}
 
-          & n = image ID (a-z and A-Z)\\\bottomrule
-  \end{tabularx}
-\newline
-\newline
-Example: image /.rockbox/bg.bmp with ID "a" at 37, 109 would be:\\
+Example: image \fname{/.rockbox/bg.bmp} with ID ``a'' at 37, 109 would be:\\
 \%x{\textbar}a{\textbar}bg.bmp{\textbar}37{\textbar}109{\textbar}
 
 \note{
@@ -174,39 +166,35 @@ Example: image /.rockbox/bg.bmp with ID "a" at 37, 109 would be:\\
   \end{itemize}
 }
 
-\subsubsection{Alignment}
-
-  \begin{tabularx}{\textwidth}{lX}\toprule
-    \textbf{Tag} & \textbf{Description}\\\midrule
+\section{Alignment}
+  \begin{tagmap}{}{}
     \%al & Text is left aligned\\
     \%ac & Text is center aligned\\
-    \%ar & Text is right aligned\\\bottomrule
-  \end{tabularx}
-\newline
-\newline
-All alignment tags may be present in one line, but they need to be in the order left - center - right. If the aligned texts overlap, they are merged.
-
-\subsubsection{Conditional Tags}
-
-\textbf{If/else}\\
-
-Syntax: \%?xx{\textless}true{\textbar}false{\textgreater}\\
-
-\textbf{Enumerations}\\
-
-Syntax: \%?xx{\textless}alt1{\textbar}alt2{\textbar}alt3{\textbar}...{\textbar}else{\textgreater}\\
-
-\subsection{Other Tags}
-\begin{tabularx}{\textwidth}{lX}\toprule
-\textbf{Tag} & \textbf{Description}\\\midrule
-  \%\%          & Display a '\%'\\
-  \%{\textless} & Display a '{\textless}'\\
-  \%{\textbar}  & Display a '{\textbar}'\\
-  \%{\textgreater} & Display a '{\textgreater}'\\
-  \%;           & Display a ';'\\
-  \%s           & Indicate that the line should scroll. Can occur anywhere in a line\\
-                & (given that the text is displayed; see conditionals above). \\
-                & You can specify up to 10 scrolling lines. Scrolling lines can not \\
-                & contain dynamic content such as timers, peak meters or progress bars.\\\bottomrule
+    \%ar & Text is right aligned\\
+  \end{tagmap}
+All alignment tags may be present in one line, but they need to be in the 
+order left -- center -- right. If the aligned texts overlap, they are merged.
+
+\section{Conditional Tags}
+
+\begin{tagmap}{}{}
+\%?xx{\textless}true{\textbar}false{\textgreater}
+    & If / Else: Evaluate for true or false case \\
+\%?xx{\textless}alt1{\textbar}alt2{\textbar}alt3{\textbar}\dots{\textbar}else{\textgreater}
+    & Enumerations: Evaluate for first / second / third / \dots / last condition \\
+\end{tagmap}
+
+\section{Other Tags}
+\begin{tagmap}{}{}
+  \%\%          & Display a `\%'\\
+  \%{\textless} & Display a `{\textless}'\\
+  \%{\textbar}  & Display a `{\textbar}'\\
+  \%{\textgreater} & Display a `{\textgreater}'\\
+  \%;           & Display a `;'\\
+  \%s           & Indicate that the line should scroll. Can occur anywhere in 
+                  a line (given that the text is displayed; see conditionals 
+                  above). You can specify up to 10 scrolling lines. Scrolling
+                  lines can not contain dynamic content such as timers, 
+                  peak meters or progress bars.\\
+\end{tagmap}
 
-\end{tabularx}
diff --git a/manual/preamble.tex b/manual/preamble.tex
index 7598e02eae..81013eab65 100644
--- a/manual/preamble.tex
+++ b/manual/preamble.tex
@@ -175,3 +175,29 @@
   \endtabularx
 }
 
+% command to set the default table heading for button lists
+\newcommand{\taghead}{\textbf{Tag} & \textbf{Description} \\\midrule}
+
+% environment intended to be used with tag maps (for wps)
+% usage: \begin{tagmap}{caption}{label} Tag & Description \\ \end{btnmap}
+% Note: this automatically sets the table lines.
+% Note: you *need* to terminate the last line with a linebreak \\
+% Note: you still need to enclose this with \begin{table} / \end{table}
+% Cheers for the usenet helping me building this up :)
+\newenvironment{tagmap}[2]{%
+  \expandafter\let\expandafter\SavedEndTab\csname endtabular*\endcsname
+  \expandafter\renewcommand\expandafter*\csname endtabular*\endcsname{%
+    \bottomrule
+    \SavedEndTab%
+    \if\given{#1}\caption{#1}\fi%
+    \if\given{#2}\label{#2}\fi%
+    \endcenter%
+  }
+  \center
+\tabularx{\textwidth}{lX}\toprule % here is the table width defined
+  \taghead
+}{%
+  \endtabularx
+}
+
+