aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2011-08-01 00:42:16 +0300
committerSergey Poznyakoff <gray@gnu.org.ua>2011-08-01 01:31:32 +0300
commit284a1ac48b35ef107979978fd443fbde6a6b4b12 (patch)
tree126db7b2837559bd678fb976f2cda43ccbac4e0a /doc
parent9a64ffcf42132cf27fdd5a59127985f1175234c3 (diff)
downloadidest-284a1ac48b35ef107979978fd443fbde6a6b4b12.tar.gz
idest-284a1ac48b35ef107979978fd443fbde6a6b4b12.tar.bz2
Finish the docs.
* doc/.gitignore: Update. * doc/idest.texi: Document all new features. * scheme/idest/batch/setlyrics.scm: Update --help output. * scheme/idest/batch/setpic.scm: Likewise. * scheme/idest/format/lyrics.scm: Likewise. * scheme/idest/format/pic.scm: Likewise. * scheme/idest/list-modules.scm: Implement the --which option. * src/guile.c (%idest-package-site-dir) (%idest-version-site-dir) (%idest-guile-site-dir): New functions.
Diffstat (limited to 'doc')
-rw-r--r--doc/.gitignore2
-rw-r--r--doc/idest.texi738
2 files changed, 696 insertions, 44 deletions
diff --git a/doc/.gitignore b/doc/.gitignore
index 47d40b2..0bbce9e 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -4,6 +4,7 @@ idest.info*
idest.aux
idest.cp
idest.cps
+idest.fl
idest.fn
idest.kw
idest.ky
@@ -11,6 +12,7 @@ idest.log
idest.op
idest.pdf
idest.pg
+idest.pr
idest.toc
idest.tp
idest.vr
diff --git a/doc/idest.texi b/doc/idest.texi
index fa73ad4..dfe4638 100644
--- a/doc/idest.texi
+++ b/doc/idest.texi
@@ -103,18 +103,18 @@ such as artist's name, the title 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, called @dfn{frames},
+It is able 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
+ Idest is a command line tool for manipulating ID3 tags. It allows you
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
Intelligent Language for Extensions},
-@uref{http://www.gnu.org/software/guile}.}, @command{idest} allows to
-write programs of arbitrary complexity for manipulating ID3 tags and
+@uref{http://www.gnu.org/software/guile}.}, @command{idest} allows you
+to write programs of arbitrary complexity for manipulating ID3 tags and
to apply them to any number of files.
The program name is an abbreviation for @samp{ID3 Edit and Scripting
@@ -213,14 +213,13 @@ which has @samp{eng} in its language field and @samp{my-comment} in
its content descriptor field. Any of qualifiers in a fully-qualified
name can be omitted. Such an empty qualifier works as a
@dfn{wildcard}, matching any value in the actual field. Thus,
-@samp{COMM::my-comment} select the @samp{COMM} frames with content
+@samp{COMM::my-comment} selects the @samp{COMM} frames with content
descriptor @samp{my-comment}, no matter what their language.
@anchor{list-frames}
@xopindex{list-frames, introduced}
-To examine the qualifiers a particular frame has, use the
-@option{--list-frames} (@option{-L}) option. It lists all the supported
-frames:
+To see all the frames along with their qualifiers and a short
+description, use the @option{--list-frames} (@option{-L}) option:
@example
$ idest --list-frames
@@ -244,7 +243,7 @@ argument (a comma-separated list) to the @option{--filter}
@example
$ idest --list --filter=COMM,TXXX
COMM:lang:condesc Comments
-TXXX:descr User defined text information frame
+TXXX:descr User defined text information
@end example
The @option{--filter} option is a standard way to abridge
@@ -314,7 +313,8 @@ frame name in the output. This string is given as a prefix to the
frame name. The two parts are delimited by a percent sign, e.g.:
@example
-$ idest --filter=Title%title,'Encoded by'%comment::encoder track01.mp3
+$ idest --filter=Title%title,'Encoded by'%comment::encoder \
+ track01.mp3
Title: Plou i fa sol
Encoded by: lame
@end example
@@ -398,7 +398,7 @@ genre:
@chapter Modifying Existing Tags
@xopindex{set, introduced}
- To modify a particular field or frame, use the @option{--set} (@option{-s})
+ To modify a particular frame, use the @option{--set} (@option{-s})
option. For example:
@example
@@ -406,7 +406,7 @@ $ idest --set artist='Jacques Brel' track01.mp3
@end example
Several frames can be set at once. To do so you can either supply
-a distinct @option{--set} option for each frame, or to give a
+a separate @option{--set} option for each frame, or to give a
single @option{--set} option followed by as many frame assignments as
you need, for example:
@@ -427,7 +427,8 @@ You can use fully qualified form (@pxref{fully-qualified name}) for
frames that require it:
@example
-$ idest --set comment:eng:My_comment='Noise reduction on' track01.mp3
+$ idest --set comment:eng:My_comment='Noise reduction on' \
+ track01.mp3
@end example
In the example above, if a comment with this content descriptor
@@ -436,7 +437,7 @@ comment frame will be created.
If a frame which can appear multiple times (such as e.g. comment) is
being set without qualifiers, all existing frames of this type will be
-removed and replaced with a new one. Its qualifiers will be set to
+removed and replaced with the new instance. Its qualifiers will be set to
default values.
@xopindex{latin1, using with --set}
@@ -462,13 +463,14 @@ As a result of this operation all tags from @file{sample.mp3} will be
copied to @file{track1.mp3} and @file{track2.mp3}.
@anchor{filter--copy}
-@xopindex{--filter, used with @option{--copy}}.
-As with another operations, you can abridge the scope of copying to
+@xopindex{--filter, used with @option{--copy}}
+As in other operations, you can abridge the scope of copying to
a certain subset of frames by using the @option{--filter} option,
e.g.:
@example
-$ idest --copy sample.mp3 --filter TPE1,TCOM track1.mp3 track2.mp3
+$ idest --copy sample.mp3 --filter TPE1,TCOM \
+ track1.mp3 track2.mp3
@end example
You can also use @option{--copy} together with @option{--set} in a
@@ -605,9 +607,10 @@ contains size of this tag in bytes.
@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
+ @command{Idest} offers a scripting facility, which makes it possible
+to extend its functionality beyond the basic operations, described in
+previous chapters. Scripts must be written in Scheme, using
+@samp{Guile}, the
@dfn{GNU's Ubiquitous Intelligent Language for Extensions}. For
information about the language, refer to @ref{Top,,,r5rs,Revised(5)
Report on the Algorithmic Language Scheme}. For a detailed
@@ -630,21 +633,27 @@ automatically (see below).
When this option is given, the following operations are performed:
@enumerate 1
+@anchor{startup files}
@item
@findex .idest.scm
@findex idest.scm
@cindex Guile startup files
The program looks for files @file{.idest.scm}, @file{$HOME/.idest.scm}
-and @file{$GUILE_SITE/idest/idest.scm} in that order. Here,
-@samp{$HOME} stands for the user home directory and @samp{$GUILE_SITE}
-stands for the Guile site-wide directory. If any of these files is
-found, it is loaded as a Scheme source code and further search is
-discontinued. This allows you to configure Guile settings on
-per-directory, per-user and site-wide basis.
+and @file{@var{guile-site-dir}/idest/idest.scm} in that order. Here,
+@samp{$HOME} stands for the user home directory and @var{guile-site-dir}
+stands for the Guile site-wide directory, as described in
+@ref{guile-site-dir}. If any of these files is found, it is loaded as
+a Scheme source code and further search is discontinued. This allows
+you to configure Guile settings on per-directory, per-user and
+site-wide basis.
+
+@xopindex{no-init-files, described}
+This step is omitted if the program is given the
+@option{--no-init-files} (@option{-N}) option.
When a startup file is loaded, the list of files which were to be
-tried after it is passed to it as arguments. This allows to
-chain-load all files in the list using the following code:
+tried after it is passed to it as arguments. This allows for
+chain-loading all files in the list using the following code:
@lisp
(let load-loop ((name-list (cdr (command-line))))
@@ -661,9 +670,93 @@ chain-load all files in the list using the following code:
Unless the supplied script name contains directory separators
(@samp{/}), it is searched in the Guile's @code{%load-path}.
The default load path is formed as follows:
-@samp{.:$GUILE_SITE/idest:$GUILE_SITE:@var{load-path}}, where
-@samp{$GUILE_SITE} is as described above and @var{load-path} is
-the default value of @code{%load-path}.
+
+@example
+@var{version-site-dir}
+.
+@var{package-site-dir}
+@var{guile-site-dir}
+%load-path
+@end example
+
+@noindent
+where the components are as follows:
+
+@table @asis
+@item %load-path
+The standard Guile load path (@pxref{Build Config,,,guile,The Guile
+Reference Manual}).
+
+@kwindex %idest-guile-site-dir
+@anchor{guile-site-dir}
+@item guile-site-dir
+This directory is selected at compile time using the rules below.
+Its value is returned by the @code{(%idest-guile-site-dir)} primitive:
+
+@enumerate 1
+@item
+Determine actual value of the default Guile site directory, by
+inspecting the value returned by the @samp{%site-dir} primitive.
+
+@item
+If that value lies under the current installation prefix, use it.
+
+@item
+Otherwise, if the @option{--with-guile-site-dir} option is supplied:
+
+@enumerate a
+@item
+If it is used without arguments, use the @samp{%site-dir} value.
+
+@item
+Otherwise, the value of this option is taken as new site directory.
+@end enumerate
+
+@item
+Otherwise, a warning is issued and @file{$(datadir)/guile/site} is used as
+the site directory.
+@end enumerate
+
+The reason for using this directory is described in
+@uref{http://www.gnu.org.ua/software/gint/#guile-site-dir}.
+
+If @code{guile-site-dir} coincides with the standard @code{%site-dir},
+this part is omitted, because the latter is always present in the
+@code{%load-path}.
+
+@kwindex %idest-package-site-dir
+@anchor{package-site-dir}
+@item package-site-dir
+This is the directory for installing version-independent
+@command{idest} files. It is formed as follows:
+
+@example
+@code{guile-site-dir}/idest
+@end example
+
+This value is returned by the @code{(%idest-package-site-dir)} primitive.
+
+@kwindex %idest-version-site-dir
+@anchor{version-site-dir}
+@item version-site-dir
+This is the directory for installing version-dependent
+@command{idest} files. It is formed as follows:
+
+@example
+@code{package-site-dir}/@value{VERSION}
+@end example
+
+This value is returned by the @code{(%idest-version-site-dir)} primitive.
+@end table
+
+@xopindex{load-path, described}
+The load path can be modified using the @option{--load-path}
+(@option{-P}) and @option{--prepend-load-path} (@option{-p}) command
+line options. Both options take as argument a list of directory
+names, separated by colons. The @option{--load-path} option adds
+these directories to the tail of the load path list. The
+@option{--prepend-load-path} option adds them to the head of the load
+path list.
The script is loaded via @code{primitive-load-path} (@pxref{Loading,,
primitive-load-path,guile,The Guile Reference Manual}), so
@@ -683,6 +776,7 @@ changes it does to the argument list become visible to
@command{idest}. The only requirement is that the modified argument
list consist of the script name (as argv[0]) and input file names.
+@anchor{idest-main}
@item
The script's @dfn{main function} is applied to each
input file in turn.
@@ -763,6 +857,8 @@ sample scripts they discuss can be found in subdirectory
@menu
* list.scm:: Using Scripts to List ID3 Frames
* settitle.scm:: Using Scripts to Modify ID3 Frames
+* format::
+* batch::
* dry-run:: Testing Scripts
@end menu
@@ -791,11 +887,15 @@ Here is a sample output:
@example
$ idest --script list1.scm track01.scm
track01.mp3
-(TIT2 (descr . Title/songname/content description) (text . Cor i arbre))
-(TRCK (descr . Track number/position in set) (text . 1))
-(COMM (descr . Comments) (condesc . Bit_Rate) (lang . eng) (text . 320))
+(TIT2 (descr . Title/songname/content description)
+ (text . Cor i arbre))
+(TRCK (descr . Track number/position in set)
+ (text . 1))
+(COMM (descr . Comments) (condesc . Bit_Rate)
+ (lang . eng) (text . 320))
(TENC (descr . Encoded by) (text . Myencoder 1.0))
-(COMM (descr . Comments) (condesc . Sample_Rate) (lang . eng) (text . 44100))
+(COMM (descr . Comments) (condesc . Sample_Rate)
+ (lang . eng) (text . 44100))
@end example
As mentioned above, a script can access the command-line arguments.
@@ -836,7 +936,8 @@ script itself, and it should not be modified.
(exit 1))
(else
(set! frame-list (string-split (list-ref cmd 1) #\,))
- (set-program-arguments (cons (car cmd) (list-tail cmd 2))))))
+ (set-program-arguments (cons (car cmd)
+ (list-tail cmd 2))))))
@end lisp
The full script text is then:
@@ -863,17 +964,20 @@ The full script text is then:
(exit 1))
(else
(set! frame-list (string-split (list-ref cmd 1) #\,))
- (set-program-arguments (cons (car cmd) (list-tail cmd 2))))))
+ (set-program-arguments (cons (car cmd)
+ (list-tail cmd 2))))))
@end lisp
Sample usage:
@example
$ idest --script list2 TIT2,TENC track01.scm
-(TIT2 (descr . Title/songname/content description) (text . Cor i arbre))
+(TIT2 (descr . Title/songname/content description)
+ (text . Cor i arbre))
(TENC (descr . Encoded by) (text . Myencoder 1.0))
@end example
+@anchor{shortlist example}
A more elaborate example will print, for each input file, its name,
followed by the title, artist name and year, as shown in this sample output:
@@ -927,7 +1031,8 @@ created using the following algorithm:
Here is the implementation:
@lisp
-;; settitle.scm - set title (TIT2) frame based on the file name.
+;; settitle.scm - set title (TIT2) frame based on
+;; the file name.
(use-modules (ice-9 regex)
(srfi srfi-13))
@@ -962,19 +1067,511 @@ created using the following algorithm:
$ idest --script settitle *.mp3
@end example
+@node format
+@section Format
+@xopindex{format, described}
+ @dfn{Formats} are advanced scripting feature which allows for extending
+@command{idest} output by writing an appropriate script in Scheme. A
+format is invoked using the @option{--format} (@option{-H}) command
+line option. The format name is given as argument to that option.
+Similarly to @option{--source}, the @option{--format} option stops
+further argument processing and passes the rest of arguments to the
+format module, which is supposed to remove its option arguments and
+leave only the input file names. For example:
+
+@example
+$ idest --format=framelist -Q -l *.mp3
+@end example
+
+@noindent
+This example invokes @command{idest} with the @samp{framelist} format
+(@pxref{framelist}). The @option{-Q} and @option{-l} flags are format
+options.
+
+@menu
+* format modules:: How to Write New Format Modules.
+* existing formats:: Existing Formats.
+@end menu
+
+@node format modules
+@subsection How to Write Format Modules
+ The source for format module @var{name} must be saved in the file
+named @file{@var{name}.scm} located in the subdirectory
+@file{idest/format} somewhere in the Guile load path. It must begin
+with the following clause:
+
+@lisp
+(define-module (idest format @var{name}))
+@end lisp
+
+ The module must define and export the @samp{idest-main} function,
+whose calling convention and return type is the same as that in
+the usual @command{idest} scripts (@pxref{idest-main}). For example,
+the following is a simplified version of the @samp{framelist} module
+(@pxref{framelist}):
+
+@lisp
+(define-module (idest format framelist))
+
+(define frame-list '())
+
+(define-public (idest-main name frames)
+ (for-each
+ (lambda (elt)
+ (cond
+ ((member (car elt) frame-list)
+ (display (car elt))
+ (newline))))
+ frames))
+@end lisp
+
+@kwindex idest-init
+ If the module needs to process command line arguments, it may not do
+so in the main code, as the usual @command{idest} modules do.
+Instead, it should export a special function, @samp{idest-init},
+defined as:
+
+@lisp
+(define-public (idest-init)
+ ...)
+@end lisp
+
+ This function analyzes the command line, removes the consumed
+modules options and returns. For example:
+
+@lisp
+(define-public (idest-init)
+ (let ((cmd (command-line)))
+ (cond
+ ((< (length cmd) 3)
+ (error "usage: idest --format=framelist
+ FRAME-LIST FILE...")
+ (exit 1))
+ (else
+ (set! frame-list (string-split (list-ref cmd 1) #\,))
+ (set-program-arguments
+ (cons (car cmd) (list-tail cmd 2)))))))
+@end lisp
+
+@kwindex description
+ The module should also export the symbol @samp{description}, which
+should contain a string with a concise description of the module.
+This description will be shown in the @option{--format=help} output
+(@pxref{help format}). For example:
+
+@lisp
+(define-public description
+ "display a list of frames defined in each file")
+@end lisp
+
+@node existing formats
+@subsection Existing Formats
+ @command{Idest} is shipped with a set of predefined formats. These
+formats are found in the @file{scheme/idest/format} subdirectory of
+the source tree. They are installed into the
+@file{@samp{version-site-dir}/format} directory (@pxref{version-site-dir}).
+
+@menu
+* help format:: List and Describe Available Formats.
+* framelist:: Display List of Frames Present in Each File.
+* lyrics:: Display Lyrics.
+* pic:: Display Attached Pictures.
+* shortlist:: Display Short Information.
+@end menu
+
+@node help format
+@subsubsection help: List and Describe Available Formats
+@cindex help, a format
+ The @samp{help} format searches the load path for available format
+modules and lists them. For each module its name and short
+description are shown on a separate line. The output is sorted
+alphabetically by the format name:
+
+@example
+$ idest --format=help
+framelist: display a list of frames defined in each file
+lyrics: display lyrics (the USLT content), if present
+pic: show attached picture (APIC frame) or save it on disk
+shortlist: display title, artist name and year
+@end example
+
+@xopindex{which, help format option}
+If @samp{help} is used with the @option{--which} (@option{-w})
+option, the format includes the directory where the module is found:
+
+@example
+$ idest --format=help --which
+framelist (/usr/share/idest/format): display a list of frames
+defined in each file
+...
+@end example
+
+@node framelist
+@subsubsection framelist: Display List of Frames Present in Each File
+ The @samp{framelist} format displays a list of ID3 frames present in
+each input file, e.g.:
+
+@example
+$ idest --format=framelist file.mp3
+TIT2
+TRCK
+COMM
+TENC
+COMM
+@end example
+
+The following command line options are understood:
+
+@table @option
+@item -F
+@itemx --full
+Display all qualifiers. For example:
+
+@example
+$ idest --format=framelist --full file.mp3
+TIT2 descr="Title/songname/content description"
+TRCK descr="Track number/position in set"
+COMM descr="Comments" lang="eng" condesc=""
+TENC descr="Encoded by"
+COMM descr="Comments" lang="cat" condesc=""
+@end example
+
+@item -f @var{flist}
+@itemx --frames @var{flist}
+Display only frames from @var{flist}, which is a list of frame names,
+separated by commas.
+
+@item -Q
+@itemx --qualified
+Display frames in qualified form:
+
+@example
+$ idest --format=framelist --qualified file.mp3
+TIT2
+TRCK
+COMM:eng:
+TENC
+COMM:cat:
+@end example
+
+@item -l
+@itemx --single-line
+Fit output on single-line, e.g.:
+
+@example
+$ idest --format=framelist --single-line file.mp3
+TIT2,TRCK,COMM,TENC,COMM
+@end example
+
+@item -h
+@itemx --help
+Show a short help summary
+@end table
+
+@node lyrics
+@subsubsection lyrics: Display Lyrics
+ The @samp{lyrics} format displays the lyrics (as found in the
+@samp{USLT} frame). The text is preceded by the song title from
+the @samp{TIT2} frame, e.g.:
+
+@example
+$ idest --format lyrics file.mp3
+How doth the little
+
+How doth the little crocodile
+Improve his shining tail,
+And pour the waters of the Nile
+On every golden scale!
+
+How cheerfully he seems to grin,
+How neatly spreads his claws,
+And welcomse little fishes in
+With gently smiling jaws!
+@end example
+
+@vindex PAGER
+If the environment variable @env{PAGER} is set, its value is used to
+paginate the output.
+
+This module supports the following command line options:
+
+@table @option
+@item -l @var{name}
+@itemx --lang @var{name}
+Select @samp{USLT} frames with @var{name} as the value of their
+@samp{lang} qualifier.
+
+@item -c @var{text}
+@itemx --content @var{text}
+Select @samp{USLT} frames with @var{text} as the value of their
+@samp{condesc} qualifier.
+
+@item -h
+@itemx --help
+Show a short help summary
+@end table
+
+@node pic
+@subsubsection pic: Display Attached Pictures
+ The @samp{pic} format displays or stores on disk attached pictures.
+It supports the following options:
+
+@table @option
+@item -v @var{prog}
+@itemx --viewer @var{prog}
+Use @var{prog} to view images (default: @command{xv}).
+
+@item -d @var{text}
+@itemx --description @var{text}
+Look for pictures with this descriptive text.
+
+@item -m @var{type}
+@itemx --mime-type @var{type}
+Look for pictures with this MIME type.
+
+@item -s
+@itemx --store
+Store pictures on disk, instead of displaying them. The picture names
+are created by expanding the file name template, given with the
+following option:
+
+@item -f @var{template}
+@itemx --file @var{template}
+Set the template for output file names (implies --store). The
+@var{template} can contain the following meta-characters:
+
+@multitable @columnfractions 0.3 0.6
+@headitem Char @tab Expands to
+@item ~D @tab Input file directory part
+@item ~N @tab Input file base name
+@item ~C @tab Content description
+@item ~T @tab Mime type without the @samp{image/} prefix
+@item ~P @tab Picture type
+@item ~I @tab PID of the @command{idest} process
+@end multitable
+
+The default template is @samp{/tmp/~I-~N.~T}.
+
+@item -h
+@itemx --help
+Show a short help summary
+@end table
+
+@node shortlist
+@subsubsection shortlist: Display Short Information
+ The @samp{shortlist} format module is similar to the
+@samp{shortlist.scm} example program, discussed in @ref{shortlist
+example}. It does not take any command line options, everything after
+the format name is treated as file names:
+
+@example
+$ idest --format=shortlist *.mp3
+dnr.mp3: Diamonds & Rust by Joan Baez, 1975
+ams.mp3: Amsterdam, by Jacques Brel, 1968
+@end example
+
+@node batch
+@section Batch
+ @dfn{Batch modules} or @dfn{batches} are @command{idest} module files
+located in a set of predefined directories which apply a set of
+modifications to the argument files. In other words, batches are
+file-modifying counterpart of formats. A batch is invoked using the
+@option{--batch} (@option{-B}) command line option. The batch name
+is given as argument to that option. Similarly to @option{--source}
+and @option{--format} options, the @option{--batch} option stops
+further argument processing and passes the rest of arguments to the
+batch module, which is supposed to remove its option arguments and
+leave only the input file names. For example:
+
+@example
+$ idest --batch=setpic -f cover.png file.mp3
+@end example
+
+In this example, @samp{setpic} is the batch module name, @samp{-f
+cover.png} are its arguments (@pxref{setpic}), and @samp{file.mp3} is
+the argument file.
+
+@menu
+* batch modules:: How to Write New Batch Modules.
+* existing batches:: Existing Batch Modules.
+@end menu
+
+@node batch modules
+@subsection How to Write New Batch Modules
+ The rules for writing batch modules are similar to those for formats
+(@pxref{format modules}) with only few differences.
+
+ The source for format module @var{name} must be saved in the file
+named @file{@var{name}.scm} located in the subdirectory
+@file{idest/batch} somewhere in the Guile load path. It must begin
+with the following clause:
+
+@lisp
+(define-module (idest batch @var{name}))
+@end lisp
+
+@kwindex idest-main
+ The module must define and export the @samp{idest-main} function,
+whose calling convention is the same as that in
+the usual @command{idest} scripts (@pxref{idest-main}). This function
+must return the new list of frames. If it returns an empty list,
+all existing frames will be deleted. If the function chooses not
+to modify any frames, it must return @code{#f}.
+
+@kwindex idest-init
+ If the module needs to process command line arguments, it should
+do so in the function @samp{idest-init}, defined as:
+
+@lisp
+(define-public (idest-init)
+ ...)
+@end lisp
+
+@kwindex description
+Finally, the module should export the symbol @samp{description} with
+a concise description of the module. This description will be shown
+in the @option{--batch=help} output (@pxref{help batch}).
+
+To illustrate this, here is the code for module @samp{delfrm}, which
+removes the requested frames from all argument files:
+
+@lisp
+(define-module (idest batch delfrm))
+
+(define-public description
+ "remove requested frames from the input files")
+
+(define frame-list '())
+
+(define-public (idest-main)
+ (filter
+ (lambda (frame)
+ (not (member (car frame) frame-list)))
+ frames))
+
+(define-public (idest-init)
+ (let ((cmd (command-line)))
+ (cond
+ ((< (length cmd) 3)
+ (error
+ "usage: idest --batch=delfrm FRAME-LIST FILE...")
+ (exit 1))
+ (else
+ (set! frame-list (string-split (list-ref cmd 1) #\,))
+ (set-program-arguments
+ (cons (car cmd) (list-tail cmd 2)))))))
+@end lisp
+
+@node existing batches
+@subsection Existing Batch Modules
+ @command{Idest} is shipped with a set of predefined batch modules. These
+modules are found in the @file{scheme/idest/batch} subdirectory of
+the source tree. They are installed into the
+@file{@samp{version-site-dir}/batch} directory (@pxref{version-site-dir}).
+
+@menu
+* help batch:: List and Describe Available Batches.
+* setlyrics:: Set Lyrics.
+* setpic:: Attach a Picture.
+@end menu
+
+@node help batch
+@subsubsection help: List and Describe Available Batches
+@cindex help, a format
+ The @samp{help} batch searches the load path for available batch
+modules and lists them. For each module its name and short
+description are shown on a separate line. The output is sorted
+alphabetically by the format name:
+
+@example
+$ idest --format=help
+setlyrics: set song lyrics (USLT frame) from a file
+setpic: set attached picture from a file
+@end example
+
+@xopindex{which, help batch option}
+If @samp{help} is used with the @option{--which} (@option{-w})
+option, the format includes the directory where the module is found:
+
+@example
+$ idest --format=help --which
+setlyrics (/usr/share/idest/format): set song lyrics
+(USLT frame) from a file
+...
+@end example
+
+@node setlyrics
+@subsubsection setlyrics
+ The @samp{setlyrics} batch reads the text from the specified file
+(or standard input, if no file is given) and stores it in the
+@samp{USLT} frame. It supports the following command line options:
+
+@table @option
+@item -f @var{file}
+@itemx --file @var{file}
+Read text from @var{file} (default: stdin).
+
+@item -l @var{name}
+@itemx --lang @var{name}
+Set language in which the lyrics is written, i.e. the value of the
+@samp{lang} qualifier (default: @samp{eng}).
+
+@item -c @var{text}
+@item --content @var{text}
+Set content description.
+
+@item -h
+@itemx --help
+Show a short help summary
+@end table
+
+@node setpic
+@subsubsection setpic: Attach a Picture
+ The @samp{setpic} module reads a picture from a supplied file and
+attaches it to the argument files. It supports the following options:
+
+@table @option
+@item -f @var{file}
+@itemx --file @var{file}
+Read picture from @var{file}. This option is required.
+
+@item -d @var{text}
+@itemx --description @var{text}
+Set the value of @samp{condesc} qualifier.
+
+@item -m @var{type}
+@itemx --mime-type @var{type}
+Set MIME type. By default it is deduced from the picture file suffix.
+
+@item -p @var{num}
+@item --pic-type @var{num}
+Set picture type (a decimal number). Default is @samp{0}.
+
+@item -h
+@itemx --help
+Show a short help summary
+@end table
+
+For example:
+
+@example
+@group
+$ idest --batch setpic --file cover.png \
+ --description='Album Cover' file.mp3
+@end group
+@end example
+
@node dry-run
@section Testing Scripts
@cindex dry-run
@cindex test mode
+@xopindex{dry-run, introduced}
When writing a script which modifies tags, it is good idea to test
it before applying it to your data. @command{Idest} provides a
-mechanism for that. To see what your script would do without actually
-modifying your data, insert the word @samp{dry-run} between the
-@option{--script} (or @option{-S}) option and the script name in the
-program invocation, e.g.:
+special option for that: @option{--dry-run} (@option{-n}, e.g.:
@example
-$ idest --script dry-run settitle *.mp3
+$ idest --dry-run --script settitle *.mp3
@end example
This will run your script as usual, but instead of applying the
@@ -982,6 +1579,12 @@ changes to the input files, @command{idest} will verbosely print
results of each invocation of @samp{idest-main}. Input files will
then be opened in read-only mode.
+The same applies to testing batch files, e.g.:
+
+@example
+$ idest --dry-run --batch delfrm *.mp3
+@end example
+
Here is an example of the dry-run output, obtained from the command
above:
@@ -1114,16 +1717,24 @@ are listed in alphabetical order. Optional arguments are enclosed in square
brackets.
@table @option
+@opsummary{all}
@item -a
@itemx --all
Query all frames. @xref{all-frames query}.
+@opsummary{backup}
@item --backup[=@var{control}]
backup before modifying, choose version @var{control}. @xref{Backups}.
+@opsummary{backup-directory}
@item --backup-directory=@var{dir}
Backup to given directory. @xref{Backups}.
+@opsummary{backup-suffix}
+@item --backup-suffix=@var{suf}
+Set backup suffix, instead of the default @samp{~}. @xref{Backups}.
+
+@opsummary{convert}
@item -C @var{version}
@itemx --convert=@var{version}
Create tags in given @var{version}, and convert existing ones to
@@ -1131,21 +1742,25 @@ Create tags in given @var{version}, and convert existing ones to
numbers.
@xref{ID Versioning}.
+@opsummary{copy}
@item -c @var{file}
@item --copy=@var{file}
Copy tags from @var{file} to destination files. @xref{Copy}.
+@opsummary{delete}
@item -d[@var{flist}]
@itemx --delete[=@var{flist}]
Delete ID3 tags. The @var{flist} is a comma-separated list of the
names of frames to delete. If @var{flist} is not given, all frames
are deleted. @xref{Delete}.
+@opsummary{describe}
@item -D
@itemx --describe
Print verbose frame descriptions instead of short names.
@xref{describe}.
+@opsummary{filter}
@item -F @var{flist}
@itemx --filter=@var{flist}
Operate only on frames from @var{flist}. This option affects the
@@ -1154,23 +1769,51 @@ copy mode}), @option{--query} (@pxref{filter--query, filter in query
mode}), @option{--delete} (@pxref{filter--delete, filter in delete
mode}) and @option{--list-frames} (@pxref{filter--list-frames}).
+@opsummary{help}
@item -h
@itemx --help
Print a short help list.
+@opsummary{info}
@item -i
@itemx --info
Show tag structure information. @xref{Structure}.
+@opsummary{latin1}
@item --latin1
Force latin1 output, when used in query mode (@pxref{View,latin1}).
Store strings in ISO-8859-1 encoding, when used with @option{--set}
(@pxref{Modify, latin1}).
+@opsummary{list-frames}
@item -L
@item --list-frames
List the supported ID3v2 frames. @xref{list-frames}.
+@opsummary{load-path}
+@item -P @var{path}
+@item --load-path=@var{path}
+Append @var{path} to the Guile load path (@pxref{load-path}). The
+argument is a list of directory names separated by colons.
+
+@opsummary{prepend-load-path}
+@item -p @var{path}
+@itemx --prepend-load-path=@var{path}
+Add @var{path} to the beginning of the Guile load path
+(@pxref{load-path}). The argument is a list of directory names
+separated by colons.
+
+@opsummary{no-init-files}
+@item -N
+@itemx --no-init-files
+Do not load Scheme init files (@pxref{startup files}).
+
+@opsummary{dry-run}
+@item -n
+@itemx --dry-run
+Initiate the @dfn{dry-run mode}. @xref{dry-run}.
+
+@opsummary{query}
@item -q[@var{flist}]
@itemx --query[=@var{flist}]
Query mode. The @var{flist} is a comma-separated list of the
@@ -1178,31 +1821,38 @@ names of frames to query. If not given, it defaults
to @samp{title,album,track,comment,artist,year,genre}.
@xref{View}.
+@opsummary{script}
@item -S @var{file}
@itemx --script=@var{file}
Guile script name. @xref{Scripting}.
+@opsummary{set}
@item -s @var{field}=@var{value}
@itemx --set=@var{field}=@var{value}
Set @var{field} ID3 field to the given @var{value}. @xref{Modify}.
+@opsummary{trace}
@item --trace[=@var{level}]
Start with debugging evaluator and backtraces. @xref{Scripting}.
+@opsummary{id-version}
@item -V @var{version}
@item --id-version=@var{version}
Write new and changed tags in the given ID3 version. Argument is
a comma-separated list of major version numbers. @xref{ID Versioning}.
+@opsummary{default-id-version}
@item -U @var{version}
@item --default-id-version=@var{version}
Create new tags in the given @var{version}. Argument is
a comma-separated list of major version numbers. @xref{ID
Versioning}.
+@opsummary{version}
@item --version
Print program version and copyright information.
+@opsummary{usage}
@item --usage
Print a short usage message.
@end table

Return to:

Send suggestions and report system problems to the System administrator.