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").