Provided by: libmp3-tag-perl_1.13-1.1_all bug

NAME

       typeset_audio_dir - produce TeX listing of directories with audio files.

SYNOPSIS

         # E.g.: current directory contains 1 subdirectory-per-performer.
         # Inside each directory the structure is
         #   Composer/single*.mp3         (fine-grain output: <title> field)
         # and
         #   Composer/MultiPart/part*.mp3 (fine-grain output: <album> field)
         # Emit year and duration info; use "Quartets" as basename
         typeset_audio_dir -y -T -B Quartets *

         # Likewise, but this directory structure is w.r.t. current directory;
         # Do not emit year and duration, output to STDOUT
         typeset_audio_dir .
         typeset_audio_dir

         # Use artist as toplevel heading, album as the 2nd level; use track numbers;
         # name is based on title for any depth in directory hierarchy;
         # likewise for generation of 2nd level heading.  Mark audios with lyrics
         typeset_audio_dir -ynTL -P long -B All

         # Likewise, but the name is based on the album; ignore comments
         typeset_audio_dir -yTn -P short -B All_short

         # Likewise, but produce both long and short listings.  The short one serves
         # as a table-of-contents for the long one
         typeset_audio_dir -ynTL -P short,long -B All

DESCRIPTION

       Scans directory (or directories) given on the command line, using MP3::Tag to obtain
       information about audio files (to process non-MP3 files, extra modules may be needed, see
       MP3::Tag, and -r FILENAME_FILTER option must be given).  Produces (one or more, depending
       on -B option) TeX files with commands to typeset human-readable listings.  Non-directories
       on the command line are ignored.  (May also be used to process non-audio files, if
       MP3::Tag may extract the title/etc info from them.)

       With -B, the file *_list.tex contains all the data about audio files (when -P with both
       "short,long" is given, another similar file *_list_long.tex is also written); the file
       *_titles.tex contains a 0th approximation to the possible "title" of the collection (one
       based on -N option and a short summary of toplevel directories).  The file *_common.tex
       contains macros common for the following files.  The remaining files define different
       environments to typeset the listing (including two TeX files with "content" as needed): a
       "normal" listing (for A4/Letter, *_text.tex), two flavors of a "compressed" listing (for
       jewel case insert, *_cdbooklet.tex and *_cdcover.tex), and a back insert for the jewel
       case (*_backcover.tex).

       The intent is to support many different layouts of directories with audio files with as
       little tinkering with command-line options as possible; thus "type_audio_dir" tries to do
       as much as possible by guestimates.  Similtaneously, one should be able to tune the script
       to handle the layout they have.

       The script emits headers for several levels of "grouping".  The "toplevel" group header is
       emited once for every "toplevel" directory (with audio files), further headers are emited
       based on changes in descriptors of the audio files during scan.

OPTIONS

       -B  gives basename of the output file.  Without this option the script will output to
           STDOUT.  With this option, script separates the layout from content, and produces 6
           TeX files:

             basename_text.tex
             basename_cdcover.tex
             basename_cdbooklet.tex
             basename_backcover.tex
             basename_list.tex
             basename_titles.tex
             basename_common.tex

           The last file contains the common macros needed for typesetting.  The previous two
           files contain the information about audio files encountered.  The others files contain
           frameworks to typeset this information.

           The first four files are supposed to be human-editable; they will not be overwritten
           by a following rerun with the same basename given to the script.  By editing these
           files, one can choose between several encodings, languages, multicolumn output, font
           size, interline spacing, margins, page size etc.

           The "*_titles.tex" file is of mixed nature: it reflects the content of audio files,
           and is supposed to be human-editable.  It will be overwritten unless it is Read-Only;
           so if you hand-edit it, make it Read-Only.  Similar overwrite logic is applied to
           "*_common.tex" file too.

       -P "plan"
           a shortcut to setting hairy options; currently, two values of "plan" are supported:

             short   =>    -1 ""  -2 ""   -t -1e100 -a -1e100 -c
             long    =>    -1 ""  -2 "@l" -t  1e100 -a  1e100

           for generation of short/long listings.  In the short listing, records correspond to
           the album names.  In the long listing, records correspond to individual files, and
           album names serve as second-level headings.

       -y  Emit year (or date) information if present.  Very long date descriptors (e.g., when
           multiple ranges of dates are present) are compressed as much as possible.

       -Y  Emit the whole date information if present.

       -T  Emit duration information.

       -n  Enable emit track number.  Environment variable TYPESET_AUDIO_TRACK may contain the
           format to interpolate for typesetting (defaults to "%{mA}%{n1}").  For example, set
           TYPESET_AUDIO_TRACK to "%{n1}" to use "pure" track number instead of combination of
           media/disk number and track number.

       -1  Toplevel header format; is interpolate()d by MP3::Tag based on the content of the
           first audio file encountered during scan of this toplevel directory.  The empty value
           is the default; in this case the header is based on the name of the directory (with
           some normalization: underscore is converted to space).

       -2  Second-level heading format; is interpolate()d by MP3::Tag.  Calculated based on the
           content of each audio file.  The heading is emited when the interpolated value changes
           (subject to option -a).

           Empty string disables generation.

       -a  Ignore changes to the second-level heading for directories deeper than this inside
           top-level directory.  Defaults to 2.  For example, in

             Performer/Composer/Collection/part1.mp3
             Performer/Composer/Collection/part2.mp3
             Performer/Composer/single1.mp3
             Performer/Composer/single2.mp3

           if the toplevel directory is Performer, then changes of the second-level header in
           single*.mp3 would create a new second-level heading.  However, similar changes in
           part*.mp3 will not create a new heading.

           NOTE: maybe this default of 2 is not very intuitive.  It is recommended to explicitly
           set this option to the value you feel appropriate (1e100 would play role of infinity -
           so any change will generate a new second-level heading).

       -t  The title-cutoff depth (w.r.t. toplevel directory).  Defaults to 2.  In audio files
           deeper than this the album %l is used as the name; otherwise the title %t of the audio
           file is used.

           Set to "-1e100" to always use %l, and to 1e100 to always use %a.

       -@  Replace all "@" by "%" in options.  Very useful with DOSISH shells to include
           "%"-escapes necessary for MP3::Tag's interpolate().

       -e ENCODINGS
           Sets encodings for output files, directory names (when uses to generate headings), and
           hint files.  ENCODINGS is a comma-separated list of directives; each directive is
           either an encoding name (to use for all targets), or "TARGET_LETTERS:encoding".
           Target letters are "o", "d", and "h" for output, names of directories, and files
           .top_heading correspondingly.  Use 0 instead of an encoding to do byte-oriented
           read/write.

       -c  What to use as "comment" for a record (a part which is typeset differently).  If not
           given, the ID3v2 frame "TXXX[add-to:file-by-person,l,t,n]" is used.

           If the content of this field is contained at end of the title, nothing is added, just
           this part is typeset differently.

       -L  Mark files with embedded (un)syncronized lyrics and pictures.  Put the explanation of
           used symbols at the end of the listing.

       -N COLLECTION_NAME
           (defaults to "COLLECTION") the name of the collection to insert into the file
           *_title.tex.  The interaction with encoding may be less than intuitive; you may want
           to check/edit this file for corrections.

       -F FONT_ENCODING_SYMBOL
           (defaults to "T2A"): the name of "LaTeX" font encoding.  If your installation is
           broken and "T2A" is not available, you may try "T1" or "OT1".  See "PROBLEMS when
           TYPESETTING".

       -r FILENAME_FILTER
           sets the regular expression for filenames to look for (the default is "(?i:\.mp3$)".

Info read from file system

       The following files are used to give hints to typeset_audio_dir:

       .content_comment
           Content of this file is used as a comment field in the output for all files in this
           directory.

       .top_heading
           If empty, indicates that when the depth of files modifies the output, it is calculated
           w.r.t. the subdirectories of the directory of this file (ouph!).  If contains a
           number, it is added to this depth.

           Example: suppose your section heading is based on directory names.  Suppose the
           directory tree to process contains a directory Mixed/2009.  If you want names of
           subdirectories of this directory to become section headings, make file
           Mixed/2009/.top_heading which contains 0.  If the same holds for other subdirectories
           of Mixed, instead of creation of such file in all year-subdirectories, one can make
           file Mixed/.top_heading which contains "-1".

           Otherwise the content of this file is used as a toplevel heading for this directory.

TYPESETTING

       Running this script will only generate necessary TeX files, but will not typeset them
       (they will look much better if you first edit the files to suit your needs).  Recall how
       to typeset TeX documents (here we assume PDF target):

         latex document.tex && dvips document.dvi && ps2pdf document

       (a lot of temporary files are going to be generated too; you can break this into multiple
       commands on "&&").  Some of the files (e.g., ..._cdcover.tex) fit better with landscape
       orientation; one needs

         latex document.tex && dvips -t landscape document.dvi && ps2pdf document

       With ..._cdbooklet.tex, for best result, one better should rearrange pages for booklet 2up
       2-pages-per-side printing:

         latex document.tex
           && dvips -t landscape -f < document.dvi | psbook | pstops "2:0(0,-6cm)+1(0,6cm)" > document.ps
           && ps2pdf -dAutoRotatePages=/None document

       (all on one line, or give 3 separate commands, breaking on "&&"; more details on running
       dvips is put in the beginning of the TeX file).  If you can easily print a .ps file, you
       can omit the last step.  (The option "-dAutoRotatePages=/None" interferes with viewing;
       one may omit it unless one does "extra flipping of even pages", as below.)

       Note that this assumes that when you send files to printer you request duplexing with
       "binding on the short side of paper".  If you printer can survive manual duplexing, do as
       usual: print first the even pages in opposite order, reload paper, then print odd pages
       (you need to understand in which orientation you must put paper back when reloading; there
       are 4 variants, and only one is correct ;-).  For "real" duplex printers, see below.

PROBLEMS when TYPESETTING

       incomplete installations
             ! Font T2A/cmr/m/n/10.95=larm1095 at 10.95pt not loadable:
               Metric (TFM) file not found.

           For best multilanguage coverage I could find, by default the generated LaTeX files use
           "T2A"-encoded-fonts with extra Latin characters provided by "textcomp".  Apparently,
           some "TeX" installations omit "T2A" encoding tables.  You may want to change "T2A" to,
           e.g., "T1" by using option "-F T1".

       In a booklet, page 1 is at end, the rest is a mess
           The "landscape" option of "geometry" package should rotate the page 90 degrees.
           Depending on the way it is configured, the direction of rotation varies.  If .pdf file
           obtained with "-dAutoRotatePages=/None" option has top of page on the left, you may
           need to invert the direction of shifting: instead of "2:0(0,-6cm)+1(0,6cm)" one should
           use "2:0(0,6cm)+1(0,-6cm)".

       Duplexing with "bind on the long side of paper"
           By default, most duplex printers are configured to "bind on the long side of paper";
           so to avoid manual setup of binding options, you may want to flip even pages in the
           generated file.  To do this, add an extra ps2ps step at the end of pipeline, e.g.:

             ... psbook | pstops "2:0(0,-6cm)+1(0,6cm)" | pstops "2:0,1U(1w,1h)" > document.ps

       A4-sized paper vs. Letter-sized paper
           Some TeX/PS installations do not have correctly set-up site configuration files, so do
           not know what is the usual paper size on your printer.  Fortunately, all steps of the
           typesetting pipeline allow a manual reconfiguration.  Unfortunately, command options
           for the required reconfigurations are subtly different for different steps.

           For example, if your TeX/PS-utils think that your paper size is "letter", while what
           you actually print to is "a4", you need to do the following (depending on which
           configuration files are broken, you might be able to omit some modifications):

           1.  Add "a4paper" to the "\usepackage[...,...]{geometry}" options (the comma-separated
               list in brackets) in TeX files which use "geometry".

           2.  Add "-t a4" as a "dvips" options.

           3.  Add "-pa4" as a "pstops" option.  (If it breaks rotation, omit it, sigh!)

           4.  Add "-sPAPERSIZE=a4" as a "ps2pdf" option.

           Example commandline working with some of complications

             dvips -t landscape -f < All_cdbooklet-a4.dvi | psbook | pstops -pa4 "2:0(0,-6cm)+1(0,6cm)" | pstops -pa4 "2:0,1U(1w,1h)" > Output-even_flipped-a4.ps
               && ps2pdf -sPAPERSIZE=a4 -dAutoRotatePages=/None Output-even_flipped-a4

           Likewise, quite often one needs to add "-pletter" to "ps2ps" commandlines for correct
           printing to letter-size paper.  You can check the resulting PDF file in a viewer: the
           status line should show the correct paper size (e.g., 8.5in x 11in is "Letter"), even
           pages should be flipped (for binding "on the long side"), and the wireframes on
           different pages should be positioned exactly at same positions (for visual
           verification, choose "fit-to-page" scaling, and quickly switch pages back-and-forth by
           keyboard or by "Next page" button).

       Warnings from dvips
           Note also that if your "TeX/dvips" installation is completely correct, you can remove
           "-t landscape" from your "dvips" command line; not removing it would produce a warning
           "both both landscape and papersize specified: ignoring landscape".

       Systematic duplexing offset
           Some printers can't reliably match positions on the front and back side when printing;
           there is little one can do with it.  However, if your printer adds some consistent
           misplacement of front and back sides, one can put workarounds for it.

           For example, when "binding on the short side", the common error is that (in landscape
           orientation) backside is offset horizontally w.r.t. frontside.  For example, if offset
           is 3.4mm to the left, one can shift the image on the page by half of this, 0.17cm to
           the left: replace "2:0(0,-6cm)+1(0,6cm)" by "2:0(0,-6.17cm)+1(0,5.83cm)".

           With "binding on the long side", the typical error is vertical offset.  To work
           around, one needs to shift vertically (again, by half the amount) after flipping even
           pages.  To shift 0.17cm up, add an extra step "pstops "(0.17cm,0)"" to the pipeline
           after the "2:0,1U(1w,1h)" step (untested).

HINTS

       The default font sizes and density of type is chosen to optimize printing of a DL-DVD
       collection of short high quality audio (of song-like duration: about 100 subheadings, and
       2000 audio files).  You may improve the visual quality if you tune the typesetting to your
       particular needs.

       The most commonly changed settings are on top of the generated files.  These are fonts and
       degrees of vertical squeeze of paragraphs for the principal title, titles of sections (1st
       level) and subsections (2nd level), and of actual records emited for each audio file, as
       well as the number of columns.  Slightly further in the file are settings for gaps to left
       around section headings, and for fine-tuning of squeezing.

       Do not forget that if you can't describe a complicated layout by command-line options, you
       still have a possibility to run this script many times (once per directory with "handable
       layout", using -B and other options suitable for this subdirectory).  Then you can use
       LaTeX "\input" directives to include the generated basename_list.tex files into the
       toplevel "LaTeX" file.

       You can also redefine "\preSection * \postSection" to do nothing, and put the necessary
       code to generate the headers into the top-level file.

       Modify the formatting macros to suit your needs.  (Of more tricky stuff, mention
       "\squeezeContunuationLines" and "\parskip", which regulate the density of lines - without
       changing the line font; note that setting "\parskip" is a part of the action of
       "\squeezeContunuationLines".  "\columnsep" regulates the horizontal separation of columns.
       One can also fine-tune the vertical position of the start of the first page; for
       backcover, also tune up "\CDbackMargin" and "\CDbackTopMargin".  The definition(s) of
       "\squeezeContunuationLines" are commented out (by "%") in non-*_common.tex files; you may
       uncomment it, and tune it up separately for each TeX file.)

       One can combine two (or more) lists (e.g., one with the short style, and one with the long
       style) into one output file; the generated files ..._cdbooklet.tex and ..._text.tex
       already have a necessary template (disabled) at the end.  (Moreover, with -P "short,long",
       this is done automatically.

       For example, with two lists created in "SYNOPSIS", All_list.tex, and All_short_list.tex,
       find "\iffalse" near the end of All_short_cdbooklet.tex and change it to "\iftrue"; then
       change the name in the directive

           \input{another_list}

       to All_list

       This will make the "short" cdbooklet become a kind of "table of contents" for the combined
       "short+long" cdbooklet.  (Of course, one can change the values of macros "\SectionFont"
       etc, "\COLUMNS", type of squeeze to suit your needs - the point is that they should not be
       necessarily the same for the second list.)

WORKFLOW

       The module is quite flexible; here is one of the possible workflows (suitable if all you
       need is -P <short> and -P <long>:

       Put all the "toplevel" directories as subdirectories of the current directory (well, this
       is not really necessary!), and put the heading to use for each directory into a file
       .top_heading.  You may need to specify the encoding used in this file into the options (do
       similar to "-e h:cp1252").