Enhanced documentation for Doxygen

git-svn-id: https://vdr-muggle.svn.sourceforge.net/svnroot/vdr-muggle/trunk/muggle-plugin@150 e10066b5-e1e2-0310-b819-94efdf66514b

5 files changed, 173 insertions, 22 deletions

diff --git a/HISTORY b/HISTORY
index 7350748..e0960d4 100644
--- a/HISTORY
+++ b/HISTORY
@@ -2,7 +2,7 @@ VDR Plugin 'muggle' Revision History
 ------------------------------------
 
 2004-08-31: Version 0.0.1-ALPHA
-
 - An initial revision given to a few people.
 
-
+2004-09-05: Version 0.0.2-ALPHA
+- Added an Ogg Vorbis decoder
diff --git a/README b/README
index 209dd46..254e344 100644
--- a/README
+++ b/README
@@ -1,3 +1,5 @@
+/*! \mainpage Muggle: Media Juggler for VDR
+
 This is a "plugin" for the Video Disk Recorder (VDR).
 
 Written by:                  Andi Kellner
@@ -11,7 +13,7 @@ Latest version available at: URL
 See the file COPYING for license information.
 
 
-PLEASE!
+\section foreword PLEASE!
 
 This is a difficult plugin. It's nice but difficult.
 With difficult I mean, that due to the underlying
@@ -23,73 +25,87 @@ Please provide feedback to the authors whenever you
 think, these instructions are not appropriate, wrong,
 or useless in any other sense.
 
-1 DESCRIPTION
+\section desc DESCRIPTION
 
 The muggle plugin provides a database link for VDR so that selection of media becomes more flexible.
 Prerequisites are describedin Section 2, Notes on Compilation are in Section 3. Before using the plugin, 
 you need to import your media into the database (cf. Section 4). The configuration of VDR and startup
 parameters are descibed in Section 5.
 
-2 PREREQUISITES
+\section prereq PREREQUISITES
 
 The plugin is written for VDR 1.2.6. In addition, the following pieces of 
 software are required:
 
-- mySQL server (tested with 4.0.18) (Debian packages mysql-server, mysql-client)
-- mySQL client libraries (Debian package libmysqlclient-dev)
-- libmad (for mp3 decoding) (Debian package libmad0-dev)
-- libtag (for ID3 tag reading/writing) (Debian package libtag1-dev)
+ - mySQL server (tested with 4.0.18) (Debian packages mysql-server, mysql-client)
+ - mySQL client libraries (Debian package libmysqlclient-dev)
+ - libmad (for mp3 decoding) (Debian package libmad0-dev)
+ - libtag (for ID3 tag reading/writing) (Debian package libtag1-dev)
+ - optionally libvorbis and libvorbisfile (Debian packages )
 
+The developer versions are needed because their headers are required for compilation.
 The server need not be on the same machine as the VDR. Also, music tracks can reside somewhere else,
 if they are available through a remote filesystem (NFS, Samba). However, in this case you should
 know what you are doing in terms of networking and security issues.
 
-
-3 INSTALLING 
+\section install INSTALLING 
 
 Unpack the sources in PLUGINS/src below your VDR directory (i.e. where all your other plugins are.
 For example (paths and version numbers may vary)
 
+\verbatim
    cd /usr/local/src/VDR/PLUGINS/src
    tar xvjf muggle-0.1.7.tar.bz2
+\endverbatim
 
 Establish a symlink as you would for other plugins:
 
+\verbatim
    ln -s muggle-0.1.7 muggle
+\endverbatim
 
 Within the VDR main directory (e.g. /usr/local/src/VDR) issue a 
 
+\verbatim
    make plugins
+\endverbatim
 
 This should build all relevant stuff. If you have difficulties, check that required libraries are 
 in the library directories stated in the muggle Makefile.
 
 
-4 IMPORT
+\section import IMPORT
 
 The import is done in two steps: First, a database is created and initialized with proper data structures (so-called schema).
 Then, these data structures are filled from the ID3 tags of your music tracks.
 
-4.1 Setup Database
+\subsection dbsetup Setup Database
 
 This step can be done on the database server or on some other client machine.
 Within the directory scripts there are a few helpful files to support setting
 up the database. Change into that directory:#
 
+\verbatim
    cd scripts
+\endverbatim
 
 The first step is to essentially create the database:
 
+\verbatim
    mysql -u root -p < createdb.mysql
+\endverbatim
 
 You will need to enter your root password that you choose during mySQL installation.
 Next, we generate the database tables (schema):
 
+\verbatim
    mysql -u root -p < createtables.mysql 
+\endverbatim
 
 Further, initial data about known languages, genres, sources and musictypes is fed into the database:
 Execute these commands on a single line, the \ for the linebreak ist just for presentation purposes here.
 
+\verbatim
    echo " use GiantDisc; load data local infile 'genres.txt' into table genre;" | \
       mysql -u root -p  --local-infile=1
 
@@ -101,6 +117,7 @@ Execute these commands on a single line, the \ for the linebreak ist just for pr
 
    echo "use GiantDisc; load data local infile '$SCRIPTDIR/sources.txt' into table language;" | \
       mysql -u root --local-infile=1
+\endverbatim
 
 You can find the sequence of commands in the file scripts/make-empty-db. Use it at your own luck.
 
@@ -114,7 +131,7 @@ If you want your database name to be different than 'GiantDisc' you will need to
 in the files createdb.mysql and createtables.mysql and in the commands above. Now your database
 is ready for import.
 
-4.2 Import Music
+\subsection importfile Import Music
 
 The next step is to feed all music information into the database. There is a small tool called 'mugglei'
 in the muggle main directory. It connects to the database, evaluates ID3 tags from a file, and writes
@@ -136,7 +153,9 @@ First, import the files in Assorted. This requires the flag -a to mugglei. Furth
 specify database host, name, user and password, respectively. The filename to import is given using the -f
 directive. Using 'find' you can import all files for assorted albums with a command like:
 
+\verbatim
    find Assorted -name '*' -type f -exec mugglei -a -f {} \;
+\endverbatim
 
 For reasons of simplicity, the arguments -h, -n, -u and -p are not shown. You will need them if the default
 values do not apply or modify the source code accordingly (beginning of function main). Also, make sure 
@@ -144,7 +163,9 @@ that either mugglei is on your path or specify an absolute or relative path in t
 
 For "regular" albums, the following command may be helpful:
 
+\verbatim
    find * -path 'Assorted' -prune -o -type f -exec mugglei -f {} \;
+\endverbatim
 
 It is important that you perform all these steps from the same location so the filenames are relative to
 exactly the same directory (e.g. /home/music in the example case).
@@ -153,12 +174,14 @@ Speed should not be an issue: on my machine, it takes about 10 secs to run the i
 albums with more than 600 tracks. Further 1200 tracks or so require 20 more secs. This depends on machine
 configuration, of course.
 
-5 MUGGLE CONFIGURATION
+\section config MUGGLE CONFIGURATION
 
 Muggle uses a small set of command line parameters in order to control the interaction with the mySQL server.
 Let's look at an example:
 
+\verbatim
   -P'muggle -h localhost -u vdr -n GiantDisc -t/home/music'
+\endverbatim
 
 The -h parameter specifies the database host, -u specifies the user, -n is the database name. The scripts mentioned
 above do not make use of passwords, but restrict database acccess on a server basis. 
@@ -166,10 +189,9 @@ above do not make use of passwords, but restrict database acccess on a server ba
 The -t argument specifies the top level directory of the music files. On a local installation, this is the
 directory in which you executed the import steps (Chapter 4.2).
 
-6 USING MUGGLE
+\section use USING MUGGLE
 
 Quick version: select Muggle on the OSD, browse titles (using up/down and Ok), add them using the red button.
 Then turn to the playlist view using yellow and start play using again the red function key.
 
-
-
+*/
\ No newline at end of file
diff --git a/TODO b/TODO
index cac1f2c..402aa85 100644
--- a/TODO
+++ b/TODO
@@ -8,13 +8,33 @@ Ogg/Vorbis decoder integration
 Deployment
 ----------
 - Script to publish a version
-   - Checkout
    - make dist
    - copy .tgz, README, CHANGES, HISTORY into web directory
    - generate documentation
    - copy into web directory
    - sync with web
 
+----------------- publish_muggle.sh -----------------
+# $1: version name (e.g. 0.0.5-BETA)
+
+# how to determine current path?
+svn copy ... http://.../svn/muggle/tags/$1
+
+make dist
+# obtain name from output? or copy commands and make correctly
+mv vdr-muggle-0.0.1.tgz ~/Web/current/htpc/muggle/vdr-muggle-$1.tgz
+
+cp README ...
+cp TODO ...
+cp CHANGES ...
+
+doxygen muggle.doxygen
+cp -R doc ~/Web/current/htpc/muggle/
+
+sitecopy --update htpctech
+
+-----------------------------------------------------
+
 - How to track bugs and feature requests?
 
 Testing/bugs
diff --git a/muggle.doxygen b/muggle.doxygen
index f973c51..c5796c6 100644
--- a/muggle.doxygen
+++ b/muggle.doxygen
@@ -23,7 +23,7 @@ PROJECT_NAME           = Muggle media plugin
 # This could be handy for archiving the generated documentation or 
 # if some version control system is used.
 
-PROJECT_NUMBER         = 0.1
+PROJECT_NUMBER         = 0.0.2
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) 
 # base path where the generated documentation will be put. 
@@ -361,7 +361,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = 
+INPUT                  = README
 
 # If the value of the INPUT tag contains directories, you can use the 
 # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 
@@ -535,7 +535,7 @@ HTML_FOOTER            =
 # fine-tune the look of the HTML output. If the tag is left blank doxygen 
 # will generate a default style sheet
 
-HTML_STYLESHEET        = 
+HTML_STYLESHEET        = stylesheet.css
 
 # If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, 
 # files or namespaces will be aligned in HTML using tables. If set to 
diff --git a/stylesheet.css b/stylesheet.css
new file mode 100644
index 0000000..dde7de6
--- /dev/null
+++ b/stylesheet.css
@@ -0,0 +1,109 @@
+body { 		background-color:	white 

+		}

+		

+P {		font-family: 		arial, sans-serif; 

+		font-size: 		10pt; 

+		color:			black; 

+		text-align: 		justify; 

+		vertical-align:		top; 

+		margin-right: 		10pt

+		}

+		

+P.header { 	font-family: 		arial,sans-serif; 

+		font-size: 		10pt; 

+		color:			black; 

+		text-align: 		right; 

+		margin-right: 		10pt

+		}

+		

+P.klein { 	font-family: 		arial,sans-serif; 

+		font-size: 		8pt; 

+		color:			black; 

+		text-align: 		justify; 

+		margin-right: 		10pt

+		}

+		

+P.kleinmitte { 	font-family: 		arial,sans-serif; 

+		font-size: 		8pt; 

+		color:			black; 		

+		text-align:		center; 

+		margin-right: 10pt

+		}

+		

+P.kleinrechts {	font-family: 		arial,sans-serif; 

+		font-size: 		8pt; 

+		color:			black; 

+		text-align: 		right; 

+		margin-right: 		10pt

+		}

+		

+P.kleinlinks {	font-family: 		arial,sans-serif; 

+		font-size: 		8pt; 

+		color:			black; 

+		text-align: 		left; 

+		margin-right: 		10pt

+		}

+		

+P.bildtitel { 	font-family: 		arial,sans-serif; 

+		font-size: 		8pt; 

+		font-weight: 		900; 

+		color:			black; 

+		text-align: 		left; 

+		vertikal-align: 	top; 

+		margin-left: 		10pt

+		}

+		

+P.bild { 	font-family: 		arial,sans-serif; 

+		font-size: 		8pt; 

+		font-weight: 		900; 

+		color:			black; 		

+		text-align: 		left; 

+		vertikal-align: 	top; 

+		margin-right: 		10pt

+		}

+		

+H1 { 		font-family: 		arial,sans-serif; 

+		font-size: 		20pt; 

+		color:			black; 

+		text-align: 		left; 

+		text-transform: 	uppercase; 

+		letter-spacing: 	10pt; 

+		margin-right: 10pt

+		}

+		

+H2 { 		font-family: 		arial,sans-serif; 

+		font-size: 12pt; 

+		color:black; 

+		text-align: left; 

+		margin-right: 10pt

+		}

+

+H3 {		font-family:		arial,sans-serif;

+		font-size: 10pt;

+		color:black;

+		text-align:left;

+		margin-right: 10pt;

+		}

+		

+UL { 		font-family: arial,sans-serif; 

+		font-size: 10pt; 

+		color:black; 

+		text-align: justify; 

+		margin-right: 10pt

+		}

+DT {		font-family: arial,sans-serif;

+		font-size: 10pt;

+		font-weight: bold;

+		color:black;

+		text-align: left;

+		}

+

+DD {		font-family: arial,sans-serif;

+		font-size: 10pt;

+		color:black;

+		text-align: justify;

+		margin-right: 10pt;

+		}

+TD { 		vertical-align: top

+		}

+