Version 1.0release-1.0

* NEWS, configure.ac, README, README-hacking: Update.
* doc/idest.texi: Finish documentation.
* doc/Makefile.am (idest_TEXINFOS): Add macros.texi.

2 files changed, 244 insertions, 20 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 43b4e32..f2be55d 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -15,7 +15,7 @@
 # along with Idest.  If not, see <http://www.gnu.org/licenses/>.
 
 info_TEXINFOS=idest.texi
-idest_TEXINFOS = fdl.texi
+idest_TEXINFOS = fdl.texi macros.texi
 
 EXTRA_DIST = \
  gendocs_template
diff --git a/doc/idest.texi b/doc/idest.texi
index 338d6c7..d677d05 100644
--- a/doc/idest.texi
+++ b/doc/idest.texi
@@ -71,6 +71,7 @@ documents IdEst @value{VERSION}.
 
 @menu
 * Intro::                Introduction to ID3 Tags and @samp{IdEst}
+* Tag Versions::         ID3 Tag Versions
 * View::                 Viewing Existing Tags
 * Modify::               Modifying Existing Tags
 * Delete::               Deleting Tags
@@ -82,6 +83,7 @@ documents IdEst @value{VERSION}.
 
 Appendices
 
+* Genre Codes::          ID3 Genre Codes
 * Copying This Manual::  The GNU Free Documentation License
 * Concept Index::        Index of Concepts
 
@@ -91,17 +93,21 @@ Appendices
 @chapter Introduction
 
 @cindex ID3
+@cindex tag
+@cindex frame
+@cindex mp3
   Many @samp{mp3} files carry additional blocks of information, called
 ID3 tags.  These tags supply additional information about the file,
 such as the artists name, the name of the song, etc.  There are
 currently two major versions of these tags.  The version 1 is able to
 keep a predefined number of textual fields of limited length, and is
 written at the end of the file.  The version 2 is much more flexible.
-It allows to keep arbitrary number of fields, which may be textual or
-binary data.  The field length is not limited.  ID3 tags of this
-version are written at the beginning of the file, which makes them
-suitable for streaming.
+It allows to keep arbitrary number of fields, called @dfn{frames},
+which may be textual or binary data.  The frame length is not limited.
+ID3 tags of this version are written at the beginning of the file,
+which makes them suitable for streaming.
 
+@cindex Guile
   Idest is a command line tool for manipulating ID3 tags.  It allows
 to create new tags, and to view, modify or delete the existing ones.
 When compiled with Guile@footnote{Guile is the @dfn{GNU's Ubiquitous
@@ -112,10 +118,68 @@ to apply them to any number of files.
 
   The program name is an abbreviation for @samp{ID3 Edit and Scripting
 Tool}.  When speaking about the whole package, we spell its name as
-@samp{IdEst}.  When speaking about the binary file, we spell it
+@samp{IdEst}.  When speaking about the program file name, we spell it
 @command{idest}.  This latter spelling may be capitalized, if it
 occurs at the beginning of a sentence.
 
+@node Tag Versions
+@chapter ID3 Tag Versions
+@cindex ID3v1
+@cindex ID3v1.1
+@cindex ID3 version 1
+@cindex ID3 version 1.1
+  The version 1 of ID3 tags offers a very limited set of
+possibilities, compared to its successor, version 2.  You should know
+these limitations in order to understand their implications when
+creating version 1 tags or converting version 2 to version 1.
+
+  Properly speaking, the pure version 1 tag is seldom used.  It is its
+modified version, called 1.1 which is used most often.
+
+  The version 1.1 tag contains the following fields:
+
+@float Table, ID3v1
+@caption{ID3v1.1 tag}
+@multitable @columnfractions 0.2 0.2 0.8
+@headitem   Field   @tab Width @tab Description
+@item       title   @tab 30    @tab The title
+@item       artist  @tab 30    @tab The artist name
+@item       album   @tab 30    @tab The album name
+@item       year    @tab 4     @tab A four-digit year
+@item       comment @tab 28    @tab The comment.
+@item       track   @tab 1     @tab The number of the track on the album.
+@item       genre   @tab 1     @tab Index in a list of genres, see below.
+@end multitable
+@end float
+
+  The last field, @samp{genre}, merits special notice.  It is an ordinal
+number of the genre in a predefined table of genres (@pxref{Genre
+Codes}).  When modifying or setting this tag, you should supply one
+of the values listed in that table (case-insensitive).  If the value
+you supply is not found in that table, the value @samp{Other} will be
+set.
+
+@cindex ID3v2
+@cindex ID3 version 2
+  The version 2 is much more advanced and flexible.  It is described
+in detail in @uref{http://www.id3.org/id3v2-00}.  Its frames are named
+using four-character abbreviations.  The 7 mostly used frames,
+corresponding to the ID3v1 fields, are:
+
+@float Table, ID3v2
+@caption{Some ID3v2 frames}
+@multitable @columnfractions 0.3 0.7
+@headitem Frame   @tab V1 field
+@item     TIT2    @tab title
+@item     TPE1    @tab artist
+@item     TALB    @tab album
+@item     TDRC    @tab year
+@item     COMM    @tab comment
+@item     TRCK    @tab track
+@item     TCON    @tab genre
+@end multitable
+@end float
+
 @node View
 @chapter Viewing Existing Tags
 
@@ -138,8 +202,8 @@ genre: Folk
 This operation mode is called @dfn{query mode}.  By default,
 @command{idest} shows all these fields in this order.  If you wish to
 display only a subset of them, use the @option{--query} option 
-(or @option{-q}, for short).  It takes a comma-separated list of the field
-names to query.  For example:
+(or @option{-q}, for short).  It takes a comma-separated list of the
+frame names to query.  For example:
 
 @smallexample
 $ idest --query=artist,title,year file.mp3
@@ -149,7 +213,7 @@ year: 1975
 @end smallexample
 
 If the long option form is used, as in the example above, then the
-field list must be separated from it by an equal sign, with no
+frame list must be separated from it by an equal sign, with no
 surrounding white space.  If the short option form is used, the list
 must follow the option letter, with no white space in between, e.g.:
 
@@ -157,6 +221,9 @@ must follow the option letter, with no white space in between, e.g.:
 $ idest -qartist,title,year file.mp3
 @end smallexample
 
+The frame list may contain either field names (@pxref{ID3v1}) or
+the corresponding standard frame names (@pxref{ID3v2}).
+
 @xopindex{latin1, introduced}
 @cindex UTF-8
 @cindex ISO-8859-1
@@ -185,14 +252,14 @@ artist: Llu@'is Llach
 album: Torna aviat
 @end smallexample
 
-Future versions of @command{idest} will provide more sofisticated
+Future versions of @command{idest} will provide more sophisticated
 recoding facilities.
 
 @node Modify
 @chapter Modifying Existing Tags
 
 @xopindex{set, introduced}
-  To modify a particular field, use the @option{--set} (@option{-s})
+  To modify a particular field or frame, use the @option{--set} (@option{-s})
 option.  For example:
 
 @smallexample
@@ -237,7 +304,7 @@ with caution.
 in both formats at once.  By default, the @option{--set} option will
 store data in the same format as found initially in the file.  If the
 file did not contain any tags before running @command{idest --set},
-new tags wll be created in the version 2.
+new tags will be created in the version 2.
 
 @xopindex{convert, described}
 The @option{--convert} (@option{-C}) command line option takes the
@@ -282,6 +349,8 @@ in ID3v1 format.
 @chapter Scripting
 @cindex scripting
 @xopindex{script,described}
+@cindex Guile
+@cindex Scheme
   @command{Idest} offers a scripting facility, which allows to extend
 its functionality beyond the basic operations, described in previous
 chapters.  Scripts must be written in Scheme, using @samp{Guile}, the
@@ -342,30 +411,42 @@ The two following sections illustrate the concept of the script files.
 
   This section illustrates how to use the scripting facility for
 listing the contents of ID3 tags.  We will create a Scheme script
-which, for each imput file, will print its name, followed by the
+which, for each input file, will print its name, followed by the
 title, artist name and year, as shown in this sample output:
 
 @smallexample
 $ idest -S list.scm *.mp3
 dnr.mp3: Diamonds & Rust by Joan Baez, 1975
 ams.mp3: Amsterdam, by Jacques Brel, 1968
-...
+@dots{}
 @end smallexample
 
-Here is the contents of @file{list.scm}:
+To implement this, we would need a function that returns the value of
+a given frame from the frame list.  Remember, that the latter is a
+list of pairs, so the task is achieved easily by using the
+@code{assoc} function:
 
 @smalllisp
 (define (get-frame code frames)
   (let ((x (assoc code frames)))
     (if x (cdr x) "")))
-	
+@end smalllisp
+
+Now, we define the main function:
+
+@smalllisp	
 (define (lister name frames)
   (format #t "~A: ~A by ~A, ~A~%"
 	  name
 	  (get-frame "TIT2" frames)   ; Title
 	  (get-frame "TPE1" frames)   ; Artist
 	  (get-frame "TDRC" frames))) ; Year
+@end smalllisp
 
+Finally, we notify @command{idest} about the main function it should
+use, and inform it that the function does not modify the tags:
+
+@smalllisp	
 (set! idest-main lister)
 (set! idest-readonly #t)
 @end smalllisp
@@ -373,7 +454,17 @@ Here is the contents of @file{list.scm}:
 @node title.scm
 @section Using Scripts to Modify ID3 Frames
 
-FIXME
+  This section illustrates how to write scripts that modify ID3 tags.
+We will write a script which creates a new value for the @samp{title}
+(@code{TIT2}) frame from the name of the input file.  The title is
+created using the following algorithm:
+
+@enumerate 1
+@item Strip off leading directories and the @samp{.mp3} suffix.
+@item Replace underscores with spaces.
+@end enumerate
+
+  Here is the implementation:
 
 @smalllisp
 (use-modules (ice-9 regex)
@@ -396,8 +487,6 @@ FIXME
 (set! idest-readonly #f)
 @end smalllisp
 
-
-
 @node Backups
 @chapter Keeping Backup Copies
 
@@ -510,7 +599,7 @@ Guile function to call.  @xref{Scripting}.
 
 @item -h
 @itemx --help
-Prnt a short help list.
+Print a short help list.
 
 @item --latin1
 Force latin1 output, when used in query mode (@pxref{View,latin1}).
@@ -550,6 +639,141 @@ Print a short usage message.
 detailed description of the bug and information about the conditions
 under which it occurs, so we can reproduce it. 
 
+@node Genre Codes
+@appendix ID3 Genre Codes
+@cindex genre, code
+
+The following genres are defined in ID3v1:
+
+@multitable @columnfractions 0.1 0.8
+@item   0 @tab Blues
+@item   1 @tab Classic Rock
+@item   2 @tab Country
+@item   3 @tab Dance
+@item   4 @tab Disco
+@item   5 @tab Funk
+@item   6 @tab Grunge
+@item   7 @tab Hip-Hop
+@item   8 @tab Jazz
+@item   9 @tab Metal
+@item  10 @tab New Age
+@item  11 @tab Oldies
+@item  12 @tab Other
+@item  13 @tab Pop
+@item  14 @tab R&B
+@item  15 @tab Rap
+@item  16 @tab Reggae
+@item  17 @tab Rock
+@item  18 @tab Techno
+@item  19 @tab Industrial
+@item  20 @tab Alternative
+@item  21 @tab Ska
+@item  22 @tab Death Metal
+@item  23 @tab Pranks
+@item  24 @tab Soundtrack
+@item  25 @tab Euro-Techno
+@item  26 @tab Ambient
+@item  27 @tab Trip-Hop
+@item  28 @tab Vocal
+@item  29 @tab Jazz+Funk
+@item  30 @tab Fusion
+@item  31 @tab Trance
+@item  32 @tab Classical
+@item  33 @tab Instrumental
+@item  34 @tab Acid
+@item  35 @tab House
+@item  36 @tab Game
+@item  37 @tab Sound Clip
+@item  38 @tab Gospel
+@item  39 @tab Noise
+@item  40 @tab AlternRock
+@item  41 @tab Bass
+@item  42 @tab Soul
+@item  43 @tab Punk
+@item  44 @tab Space
+@item  45 @tab Meditative
+@item  46 @tab Instrumental Pop
+@item  47 @tab Instrumental Rock
+@item  48 @tab Ethnic
+@item  49 @tab Gothic
+@item  50 @tab Darkwave
+@item  51 @tab Techno-Industrial
+@item  52 @tab Electronic
+@item  53 @tab Pop-Folk
+@item  54 @tab Eurodance
+@item  55 @tab Dream
+@item  56 @tab Southern Rock
+@item  57 @tab Comedy
+@item  58 @tab Cult
+@item  59 @tab Gangsta
+@item  60 @tab Top 40
+@item  61 @tab Christian Rap
+@item  62 @tab Pop/Funk
+@item  63 @tab Jungle
+@item  64 @tab Native American
+@item  65 @tab Cabaret
+@item  66 @tab New Wave
+@item  67 @tab Psychadelic
+@item  68 @tab Rave
+@item  69 @tab Showtunes
+@item  70 @tab Trailer
+@item  71 @tab Lo-Fi
+@item  72 @tab Tribal
+@item  73 @tab Acid Punk
+@item  74 @tab Acid Jazz
+@item  75 @tab Polka
+@item  76 @tab Retro
+@item  77 @tab Musical
+@item  78 @tab Rock & Roll
+@item  79 @tab Hard Rock
+@item  80 @tab Folk
+@item  81 @tab Folk-Rock
+@item  82 @tab National Folk
+@item  83 @tab Swing
+@item  84 @tab Fast Fusion
+@item  85 @tab Bebob
+@item  86 @tab Latin
+@item  87 @tab Revival
+@item  88 @tab Celtic
+@item  89 @tab Bluegrass
+@item  90 @tab Avantgarde
+@item  91 @tab Gothic Rock
+@item  92 @tab Progressive Rock
+@item  93 @tab Psychedelic Rock
+@item  94 @tab Symphonic Rock
+@item  95 @tab Slow Rock
+@item  96 @tab Big Band
+@item  97 @tab Chorus
+@item  98 @tab Easy Listening
+@item  99 @tab Acoustic
+@item 100 @tab Humour
+@item 101 @tab Speech
+@item 102 @tab Chanson
+@item 103 @tab Opera
+@item 104 @tab Chamber Music
+@item 105 @tab Sonata
+@item 106 @tab Symphony
+@item 107 @tab Booty Bass
+@item 108 @tab Primus
+@item 109 @tab Porn Groove
+@item 110 @tab Satire
+@item 111 @tab Slow Jam
+@item 112 @tab Club
+@item 113 @tab Tango
+@item 114 @tab Samba
+@item 115 @tab Folklore
+@item 116 @tab Ballad
+@item 117 @tab Power Ballad
+@item 118 @tab Rhythmic Soul
+@item 119 @tab Freestyle
+@item 120 @tab Duet
+@item 121 @tab Punk Rock
+@item 122 @tab Drum Solo
+@item 123 @tab A capella
+@item 124 @tab Euro-House
+@item 125 @tab Dance Hall
+@end multitable
+
 @node Copying This Manual
 @appendix GNU Free Documentation License
 @include fdl.texi