.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "TYPESET_AUDIO_DIR 1p"
.TH TYPESET_AUDIO_DIR 1p "2009-12-30" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
typeset_audio_dir \- produce TeX listing of directories with audio files.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 7
\&  # 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
.Ve
.SH "DESCRIPTION"
.IX Header "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 \fB\-r
\&\s-1FILENAME_FILTER\s0\fR option must be given).  Produces
(one or more, depending on \fB\-B\fR option) \fBTeX\fR 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.)
.PP
With \fB\-B\fR, the file \fI*_list.tex\fR contains all the data about audio
files (when \fB\-P\fR with both \f(CW\*(C`short,long\*(C'\fR is given, another similar file
\&\fI*_list_long.tex\fR is also written); the file \fI*_titles.tex\fR contains
a 0th approximation to the possible \*(L"title\*(R" of the collection (one
based on \fB\-N\fR option and a short summary of toplevel directories).
The file \fI*_common.tex\fR contains macros common for the following
files.  The remaining files define different environments to typeset
the listing (including two TeX files with \*(L"content\*(R" as needed): a
\&\*(L"normal\*(R" listing (for A4/Letter, \fI*_text.tex\fR), two flavors of a
\&\*(L"compressed\*(R" listing (for jewel case insert, \fI*_cdbooklet.tex\fR and
\&\fI*_cdcover.tex\fR), and a back insert for the jewel case
(\fI*_backcover.tex\fR).
.PP
The intent is to support many different layouts of directories with
audio files with as little tinkering with command-line options as
possible; thus \f(CW\*(C`type_audio_dir\*(C'\fR tries to do as much as possible by
guestimates.  Similtaneously, one should be able to tune the script to
handle the layout they have.
.PP
The script emits headers for several levels of \*(L"grouping\*(R".  The
\&\*(L"toplevel\*(R" group header is emited once for every \*(L"toplevel\*(R" directory
(with audio files), further headers are emited based on changes in
descriptors of the audio files during scan.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-B\fR" 4
.IX Item "-B"
gives basename of the output file.  Without this option the script
will output to \s-1STDOUT\s0.  With this option, script separates the layout
from content, and produces 6 \fBTeX\fR files:
.Sp
.Vb 7
\&  basename_text.tex
\&  basename_cdcover.tex
\&  basename_cdbooklet.tex
\&  basename_backcover.tex
\&  basename_list.tex
\&  basename_titles.tex
\&  basename_common.tex
.Ve
.Sp
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.
.Sp
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.
.Sp
The \f(CW\*(C`*_titles.tex\*(C'\fR file is of mixed nature: it reflects the content of
audio files, \fIand\fR 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 \f(CW\*(C`*_common.tex\*(C'\fR file too.
.ie n .IP "\fB\-P\fR ""plan""" 4
.el .IP "\fB\-P\fR \f(CWplan\fR" 4
.IX Item "-P plan"
a shortcut to setting hairy options; currently, two values of \f(CW\*(C`plan\*(C'\fR are
supported:
.Sp
.Vb 2
\&  short   =>    \-1 ""  \-2 ""   \-t \-1e100 \-a \-1e100 \-c
\&  long    =>    \-1 ""  \-2 "@l" \-t  1e100 \-a  1e100
.Ve
.Sp
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.
.IP "\fB\-y\fR" 4
.IX Item "-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.
.IP "\fB\-Y\fR" 4
.IX Item "-Y"
Emit the whole date information if present.
.IP "\fB\-T\fR" 4
.IX Item "-T"
Emit duration information.
.IP "\fB\-n\fR" 4
.IX Item "-n"
Enable emit track number.  Environment variable \s-1TYPESET_AUDIO_TRACK\s0
may contain the format to interpolate for typesetting (defaults to
\&\f(CW\*(C`%{mA}%{n1}\*(C'\fR).  For example, set \s-1TYPESET_AUDIO_TRACK\s0 to \f(CW\*(C`%{n1}\*(C'\fR
to use \*(L"pure\*(R" track number instead of combination of media/disk number
and track number.
.IP "\fB\-1\fR" 4
.IX Item "-1"
Toplevel header format; is \fIinterpolate()\fRd 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).
.IP "\fB\-2\fR" 4
.IX Item "-2"
Second-level heading format; is \fIinterpolate()\fRd by MP3::Tag.
Calculated based on the content of each audio file.  The heading is
emited when the interpolated value changes (subject to option \fB\-a\fR).
.Sp
Empty string disables generation.
.IP "\fB\-a\fR" 4
.IX Item "-a"
Ignore changes to the second-level heading for directories deeper than
this inside top-level directory.  Defaults to 2.  For example, in
.Sp
.Vb 4
\&  Performer/Composer/Collection/part1.mp3
\&  Performer/Composer/Collection/part2.mp3
\&  Performer/Composer/single1.mp3
\&  Performer/Composer/single2.mp3
.Ve
.Sp
if the toplevel directory is \fIPerformer\fR, then changes of the
second-level header in \fIsingle*.mp3\fR would create a new second-level
heading.  However, similar changes in \fIpart*.mp3\fR will not create a
new heading.
.Sp
\&\fB\s-1NOTE:\s0\fR maybe this default of 2 is not very intuitive.  It is
recommended to explicitly set this option to the value you feel
appropriate (\f(CW1e100\fR would play role of infinity \- so any change will
generate a new second-level heading).
.IP "\fB\-t\fR" 4
.IX Item "-t"
The title-cutoff depth (w.r.t. toplevel directory).  Defaults to 2.
In audio files deeper than this the album \f(CW%l\fR is used as the name;
otherwise the title \f(CW%t\fR of the audio file is used.
.Sp
Set to \f(CW\*(C`\-1e100\*(C'\fR to always use \f(CW%l\fR, and to \f(CW1e100\fR to always use \f(CW%a\fR.
.IP "\fB\-@\fR" 4
.IX Item "-@"
Replace all \f(CW\*(C`@\*(C'\fR by \f(CW\*(C`%\*(C'\fR in options.  Very useful with \s-1DOSISH\s0 shells
to include \f(CW\*(C`%\*(C'\fR\-escapes necessary for MP3::Tag's \fIinterpolate()\fR.
.IP "\fB\-e \s-1ENCODINGS\s0\fR" 4
.IX Item "-e ENCODINGS"
Sets encodings for output files, directory names (when uses to generate
headings), and hint files.  \fB\s-1ENCODINGS\s0\fR is a comma-separated list of
directives; each directive is either an encoding name (to use for all targets),
or \f(CW\*(C`TARGET_LETTERS:encoding\*(C'\fR.  Target letters are \f(CW\*(C`o\*(C'\fR, \f(CW\*(C`d\*(C'\fR, and \f(CW\*(C`h\*(C'\fR
for output, names of directories, and files \fI.top_heading\fR correspondingly.
Use 0 instead of an encoding to do byte-oriented read/write.
.IP "\fB\-c\fR" 4
.IX Item "-c"
What to use as \*(L"comment\*(R" for a record (a part which is typeset differently).
If not given, the ID3v2 frame \f(CW\*(C`TXXX[add\-to:file\-by\-person,l,t,n]\*(C'\fR is used.
.Sp
If the content of this field is contained at end of the title, nothing
is added, just this part is typeset differently.
.IP "\fB\-L\fR" 4
.IX Item "-L"
Mark files with embedded (un)syncronized lyrics and pictures.  Put the
explanation of used symbols at the end of the listing.
.IP "\fB\-N \s-1COLLECTION_NAME\s0\fR" 4
.IX Item "-N COLLECTION_NAME"
(defaults to \*(L"\s-1COLLECTION\s0\*(R") the name of the collection to insert into
the file \fI*_title.tex\fR.  The interaction with encoding may be less than
intuitive; you may want to check/edit this file for corrections.
.IP "\fB\-F \s-1FONT_ENCODING_SYMBOL\s0\fR" 4
.IX Item "-F FONT_ENCODING_SYMBOL"
(defaults to \f(CW\*(C`T2A\*(C'\fR): the name of \f(CW\*(C`LaTeX\*(C'\fR font encoding.  If your
installation is broken and \f(CW\*(C`T2A\*(C'\fR is not available, you may try \f(CW\*(C`T1\*(C'\fR
or \f(CW\*(C`OT1\*(C'\fR.  See \*(L"\s-1PROBLEMS\s0 when \s-1TYPESETTING\s0\*(R".
.IP "\fB\-r \s-1FILENAME_FILTER\s0\fR" 4
.IX Item "-r FILENAME_FILTER"
sets the regular expression for filenames to look for (the default is
\&\f(CW\*(C`(?i:\e.mp3$)\*(C'\fR.
.SH "Info read from file system"
.IX Header "Info read from file system"
The following files are used to give hints to \fItypeset_audio_dir\fR:
.IP "\fI.content_comment\fR" 4
.IX Item ".content_comment"
Content of this file is used as a comment field in the output for all
files in this directory.
.IP "\fI.top_heading\fR" 4
.IX Item ".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.
.Sp
\&\fBExample\fR: suppose your section heading is based on directory names.
Suppose the directory tree to process contains a directory \fIMixed/2009\fR.
If you want names of subdirectories of this directory to become
section headings, make file \fIMixed/2009/.top_heading\fR which contains \f(CW0\fR.
If the same holds for other subdirectories of \fIMixed\fR, instead of
creation of such file in all year-subdirectories, one can make file
\&\fIMixed/.top_heading\fR which contains \f(CW\*(C`\-1\*(C'\fR.
.Sp
Otherwise the content of this file is used as a toplevel heading for
this directory.
.SH "TYPESETTING"
.IX Header "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 \s-1PDF\s0 target):
.PP
.Vb 1
\&  latex document.tex && dvips document.dvi && ps2pdf document
.Ve
.PP
(a lot of temporary files are going to be generated too; you can break
this into multiple commands on \f(CW\*(C`&&\*(C'\fR).  Some of the files (e.g.,
\&\fI..._cdcover.tex\fR) fit better with landscape orientation; one needs
.PP
.Vb 1
\&  latex document.tex && dvips \-t landscape document.dvi && ps2pdf document
.Ve
.PP
With \fI..._cdbooklet.tex\fR, for best result, one better should
rearrange pages for booklet 2up 2\-pages\-per\-side printing:
.PP
.Vb 3
\&  latex document.tex
\&    && dvips \-t landscape \-f < document.dvi | psbook | pstops "2:0(0,\-6cm)+1(0,6cm)" > document.ps
\&    && ps2pdf \-dAutoRotatePages=/None document
.Ve
.PP
(all on one line, or give 3 separate commands, breaking on \f(CW\*(C`&&\*(C'\fR; more
details on running dvips is put in the beginning of the TeX file).  If
you can easily print a \fI.ps\fR file, you can omit the last step.  (The
option \f(CW\*(C`\-dAutoRotatePages=/None\*(C'\fR interferes with viewing; one may
omit it \fIunless\fR one does \*(L"extra flipping of even pages\*(R", as below.)
.PP
Note that this assumes that when you send files to printer you request
duplexing with \*(L"binding on the short side of paper\*(R".  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 \*(L"real\*(R" duplex printers,
see below.
.SH "PROBLEMS when TYPESETTING"
.IX Header "PROBLEMS when TYPESETTING"
.IP "incomplete installations" 4
.IX Item "incomplete installations"
.Vb 2
\&  ! Font T2A/cmr/m/n/10.95=larm1095 at 10.95pt not loadable:
\&    Metric (TFM) file not found.
.Ve
.Sp
For best multilanguage coverage I could find, by default the generated
LaTeX files use \f(CW\*(C`T2A\*(C'\fR\-encoded\-fonts with extra Latin characters
provided by \f(CW\*(C`textcomp\*(C'\fR.  Apparently, some \f(CW\*(C`TeX\*(C'\fR installations omit
\&\f(CW\*(C`T2A\*(C'\fR encoding tables.  You may want to change \f(CW\*(C`T2A\*(C'\fR to, e.g., \f(CW\*(C`T1\*(C'\fR by using option \f(CW\*(C`\-F T1\*(C'\fR.
.IP "In a booklet, page 1 is at end, the rest is a mess" 4
.IX Item "In a booklet, page 1 is at end, the rest is a mess"
The \f(CW\*(C`landscape\*(C'\fR option of \f(CW\*(C`geometry\*(C'\fR package should rotate the page
90 degrees.  Depending on the way it is configured, the direction of
rotation varies.  If \fI.pdf\fR file obtained with
\&\f(CW\*(C`\-dAutoRotatePages=/None\*(C'\fR option has top of page on the left, you may
need to invert the direction of shifting: instead of
\&\f(CW\*(C`2:0(0,\-6cm)+1(0,6cm)\*(C'\fR one should use \f(CW\*(C`2:0(0,6cm)+1(0,\-6cm)\*(C'\fR.
.ie n .IP "Duplexing with ""bind on the long side of paper""" 4
.el .IP "Duplexing with ``bind on the long side of paper''" 4
.IX Item "Duplexing with bind on the long side of paper"
By default, most duplex printers are configured to \*(L"bind on the long
side of paper\*(R"; 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 \fIps2ps\fR step at the end of pipeline, e.g.:
.Sp
.Vb 1
\&  ... psbook | pstops "2:0(0,\-6cm)+1(0,6cm)" | pstops "2:0,1U(1w,1h)" > document.ps
.Ve
.IP "A4\-sized paper vs. Letter-sized paper" 4
.IX Item "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.
.Sp
For example, if your TeX/PS\-utils think that your paper size is
\&\f(CW\*(C`letter\*(C'\fR, while what you actually print to is \f(CW\*(C`a4\*(C'\fR, you need to do
the following (depending on which configuration files are broken, you
might be able to omit some modifications):
.RS 4
.IP "1." 4
Add \f(CW\*(C`a4paper\*(C'\fR to the \f(CW\*(C`\eusepackage[...,...]{geometry}\*(C'\fR options (the
comma-separated list in brackets) in TeX files which use \f(CW\*(C`geometry\*(C'\fR.
.IP "2." 4
Add \f(CW\*(C`\-t a4\*(C'\fR as a \f(CW\*(C`dvips\*(C'\fR options.
.IP "3." 4
Add \f(CW\*(C`\-pa4\*(C'\fR as a \f(CW\*(C`pstops\*(C'\fR option.  (If it breaks rotation, omit it, sigh!)
.IP "4." 4
Add \f(CW\*(C`\-sPAPERSIZE=a4\*(C'\fR as a \f(CW\*(C`ps2pdf\*(C'\fR option.
.RE
.RS 4
.Sp
Example commandline working with some of complications
.Sp
.Vb 2
\&  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
.Ve
.Sp
Likewise, quite often one needs to add \f(CW\*(C`\-pletter\*(C'\fR to \f(CW\*(C`ps2ps\*(C'\fR commandlines
for correct printing to letter-size paper.  You can check the resulting \s-1PDF\s0
file in a viewer: the status line should show the correct paper size
(e.g., 8.5in x 11in is \*(L"Letter\*(R"), even pages should be flipped (for binding
\&\*(L"on the long side\*(R"), and the wireframes on different pages should be
positioned exactly at same positions (for visual verification, choose
\&\*(L"fit-to-page\*(R" scaling, and quickly switch pages back-and-forth by keyboard
or by \*(L"Next page\*(R" button).
.RE
.IP "Warnings from dvips" 4
.IX Item "Warnings from dvips"
Note also that if your \f(CW\*(C`TeX/dvips\*(C'\fR installation is \fIcompletely correct\fR,
you can remove \f(CW\*(C`\-t landscape\*(C'\fR from your \f(CW\*(C`dvips\*(C'\fR command line; not removing
it would produce a warning \f(CW\*(C`both both landscape and papersize specified:
ignoring landscape\*(C'\fR.
.IP "Systematic duplexing offset" 4
.IX Item "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 \fIconsistent\fR misplacement of front and back sides,
one can put workarounds for it.
.Sp
For example, when \*(L"binding on the short side\*(R", 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 \f(CW"2:0(0,\-6cm)+1(0,6cm)"\fR
by \*(L"2:0(0,\-6.17cm)+1(0,5.83cm)\*(R".
.Sp
With \*(L"binding on the long side\*(R", the typical error is
vertical offset.  To work around, one needs to shift vertically (again,
by half the amount) \fIafter\fR flipping even pages.  To shift 0.17cm up,
add an extra step \f(CW\*(C`pstops "(0.17cm,0)"\*(C'\fR to the pipeline after the
\&\f(CW"2:0,1U(1w,1h)"\fR step (untested).
.SH "HINTS"
.IX Header "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.
.PP
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.
.PP
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 \*(L"handable layout\*(R", using \fB\-B\fR and
other options suitable for this subdirectory).  Then you can use
\&\fBLaTeX\fR \f(CW\*(C`\einput\*(C'\fR directives to include the generated \fIbasename_list.tex\fR
files into the toplevel \f(CW\*(C`LaTeX\*(C'\fR file.
.PP
You can also redefine \f(CW\*(C`\epreSection * \epostSection\*(C'\fR to do nothing, and put the
necessary code to generate the headers into the top-level file.
.PP
Modify the formatting macros to suit your needs.  (Of more tricky
stuff, mention \f(CW\*(C`\esqueezeContunuationLines\*(C'\fR and \f(CW\*(C`\eparskip\*(C'\fR, which
regulate the density of lines \- without changing the line font; note
that setting \f(CW\*(C`\eparskip\*(C'\fR is a part of the action of
\&\f(CW\*(C`\esqueezeContunuationLines\*(C'\fR.  \f(CW\*(C`\ecolumnsep\*(C'\fR 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 \f(CW\*(C`\eCDbackMargin\*(C'\fR
and \f(CW\*(C`\eCDbackTopMargin\*(C'\fR.  The definition(s) of \f(CW\*(C`\esqueezeContunuationLines\*(C'\fR
are commented out (by \f(CW\*(C`%\*(C'\fR) in non\-\fI*_common.tex\fR files; you may uncomment
it, and tune it up separately for each TeX file.)
.PP
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
\&\fI..._cdbooklet.tex\fR and \fI..._text.tex\fR already have a necessary
template (disabled) at the end.  (Moreover, with \fB\-P\fR \f(CW\*(C`short,long\*(C'\fR, this
is done automatically.
.PP
For example, with two lists created in
\&\*(L"\s-1SYNOPSIS\s0\*(R", \fIAll_list.tex\fR, and \fIAll_short_list.tex\fR, find
\&\f(CW\*(C`\eiffalse\*(C'\fR near the end of \fIAll_short_cdbooklet.tex\fR and change it
to \f(CW\*(C`\eiftrue\*(C'\fR; then change the name in the directive
.PP
.Vb 1
\&    \einput{another_list}
.Ve
.PP
to \fIAll_list\fR
.PP
This will make the \*(L"short\*(R" cdbooklet become a kind of \*(L"table of
contents\*(R" for the combined \*(L"short+long\*(R" cdbooklet.  (Of course, one
can change the values of macros \f(CW\*(C`\eSectionFont\*(C'\fR etc, \f(CW\*(C`\eCOLUMNS\*(C'\fR, type of
squeeze to suit your needs \- the point is that they should not be necessarily
the same for the second list.)
.SH "WORKFLOW"
.IX Header "WORKFLOW"
The module is quite flexible; here is one of the possible workflows (suitable
if all you need is \fB\-P\fR <short> and \fB\-P\fR <long>:
.PP
Put all the \*(L"toplevel\*(R" 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 \fI.top_heading\fR.  You may need to specify the encoding
used in this file into the options (do similar to \f(CW\*(C`\-e h:cp1252\*(C'\fR).