1CDLABELGEN(1)         User Contributed Perl Documentation        CDLABELGEN(1)
2
3
4

NAME

6       cdlabelgen - CD/DVD labels, jewel case inserts, and envelopes creator.
7       Generates frontcards and traycards for CD cases, single-cd envelopes,
8       DVD case inserts, as well as output suitable for direct printing on
9       CD/DVD.
10

SYNOPSIS

12       cdlabelgen [ -c <category> -s <subcategory> -i <item1%item2%etc> -f
13       <itemsfile>  -v <num_items_cover> -e <cover_epsfile> -S
14       <cover_eps_scaleratio>[,<image_x_offset>,<image_y_offset_inches>] -E
15       <tray_epsfile> -T
16       <tray_eps_scaleratio>[,<image_x_offset>,<image_y_offset_inches>] -d
17       <date> -D -o <outputfile> -t <template> -b -C -w -h -m -M -O -p -y
18       <page_offset_inches>  -l <line_width_points>] --create-dvd-inside
19       --create-dvd-outside --slim-double-case --double-case --create-cdlabel
20       --rotate-endcaps --plaque-color <r,g,b> --category-color <r,g,b>
21       --subcategory-color <r,g,b> --text-color <r,g,b> -n <volume/number in
22       set> --rows-columns <row_count_for_items,column_count_for_items>
23       --tray-overlay <overlay_epsfile> --tray-overlay-scaleratio
24       <tray_overlay_image_scaleratio>[,<image_x_offset>,<image_y_offset_inches>]
25

VERSION

27       Version 4.2.0, April 2012
28

DESCRIPTION

30       cdlabelgen's purpose in life is twofold:
31
32       ·   To be run automatically and swiftly from a shell script and
33           automatically generate a frontcard and a traycard for a cd--usually
34           data archive cd's. The traycard (which goes behind the CD itself)
35           is U-shaped and the ends of the CD case bear the label of what the
36           CD is.  Inside inserts for DVDs are also supported.
37
38       ·   To have a minimum of dependencies--cdlabelgen only requires perl.
39
40       cdlabelgen was designed to simplify the process of generating labels
41       for CD's. It originated as a program to allow auto generation of
42       frontcards and traycards for CD's burned via an automated mechanism
43       (specifically for archiving data), but has now become popular for
44       labelling CD compilations of mp3's, and copies of CDs. Note that
45       cdlabelgen does not actually print anything--it just spits out
46       postscript, which you can then do with as you please. It can also be
47       combined with output from other programs such as "barcodegen" - to
48       print a barcode as a tray overlay image.
49
50       The latest version of cdlabelgen as well as this document can be found
51       at http://www.aczoom.com/tools/cdinsert/. The software package includes
52       CGI scripts that can be used to serve cdlabelgen over the internet.  An
53       older version may be available at:
54       http://www.red-bean.com/~bwf/software/cdlabelgen/.
55
56       cdlabelgen comes with several eps images for you to use on your labels.
57       These images can be found in /usr/local/lib/cdlabelgen or
58       /usr/share/cdlabelgen or /opt/lib/cdlabelgen/ or
59       /usr/local/share/cdlabelgen, depending on your installation. Included
60       are a Recycling icon, an mp3 icon, the Compact Disc icon (with and
61       without 'Digital' on it), Tux the penguin, and the new Debian 'swirl'
62       logo. Two color background images called Music Notes are also
63       available.
64
65       CDs: cdlabelgen prints a 'tongue' as part of the traycard. This folds
66       around and is viewable from the front in jewel boxes that are entirely
67       clear (CD holder piece is not opaque). If you do not have a clear CD
68       holder in your jewel box, you may find it easier to just cut the
69       'tongue' off--it's a bit easier to fold without it.
70
71       Paper Sizes: Normal CD cases, Slim CD cases, DVD inside inserts can be
72       printed on a letter or A4 sized page.  CD/DVD Envelopes and DVD outside
73       inserts will not fit on a letter sized paper, a larger paper size will
74       be needed to make it fit.
75
76       cdlabelgen requires Perl Version 5.003 or greater. Ghostscript is not
77       required, but is recommended so that you can test out your labels
78       without wasting paper.
79

SWITCHES

81       -c, --category <category>
82           Set the category (title) for the CD
83
84       -s, --subcategory <subcategory>
85           Set the subcategory (subtitle) for the CD
86
87       -i, --items <items>
88           'items' should be a '%' separated list of items to print on the
89           traycard of the CD.  Note that if the number of items are too many
90           to fit on the tray card, cdlabelgen will leave out some items at
91           the end.  cdlabelgen automatically flows the items into 2, 3, 4, or
92           5 columns and scales the fontsize accordingly, unless the "-P"
93           option is used.  You can insert blank lines by inserting 2 percent
94           signs in a row into the items list.
95
96       -f, --items-from-file <filename>
97           Get item names from file named filename. Each item should be on its
98           own line separated by carriage returns.  cdlabelgen automatically
99           flows the items into 2, 3, 4, or 5 columns and scales the fontsize
100           or clips the items as needed.  You can insert blank lines by
101           placing blank lines between items in this file.
102
103           Special commands can be embedded in the file, all of these commands
104           should be present starting at the first column of the line.  The
105           codes are used to change the font for an item, the code itself is
106           not printed in the output.
107
108            {#BI}     - make the item bold and italic
109            {#I}      - make the item italic
110            {#B}      - make the item bold
111            {#M}      - make the item mono-spaced (Courier font)
112            {#MB}     - make the item monospaced and bold (Courier-Bold font)
113
114           Example:
115
116            {#MB}    Text 1 Item
117           would print the line "    Text 1 Item" in a monospaced bold font.
118
119       -v, --cover-items <number_of_items_for_cover>
120           Normally, all the items are printed on the tray card.  But if you
121           have a large number of items, you may wish to print some items on
122           the cover, and rest on the tray card.  This option provides a way
123           of specifying how many items should be printed on the cover.
124           Default is 0 (i.e., print no item on the cover, print all items on
125           the tray). The items to be printed on the cover are taken from the
126           list of items, from the top of the list.  Note that if the number
127           of items is too many to fit on the cover, it will result in items
128           being dropped. As of Jan 2002, around 250-300 items can be fitted
129           on the cover or the tray, depending on whether a
130           title/subtitle/date is used or not.
131
132       -d, --date <date>
133           Set the date to be used as 'date' if not set or not overridden with
134           the -D flag, today's date will be used (default is today's date).
135           Use this option if you don't like cdlabelgen's default format of
136           YYCC-MM-YY, for example.
137
138       -D, --no-date
139           Do not print any date (overrides -d as well)
140
141       -e, --cover-image <cover_epsfile>
142           Filename of eps file to print on cover. Note that cdlabelgen
143           requires that the eps file contain a proper '%%BoundingBox LLx LLy
144           URx URy' declaration according to the PostScript Document
145           Structuring Conventions. cdlabelgen uses this line to determine the
146           dimensions of the eps graphic so that it can position it
147           appropriately on the cover. Note that cdlabelgen first looks for
148           this file in your working directory. If it doesn't find it there,
149           it will look in the list of directories where the default eps files
150           are stored (see @where_is_the_template). This makes it easy to use
151           the images shipped with cdlabgelgen without typing miles of
152           pathnames.
153
154       -S, --cover-image-scaleratio <cover_eps_scaleratio
155       [,image_x_offset,image_y_offset_inches]>
156           The ratio by which you want to scale the epsfile that appears on
157           the cover. If you omit this flag, cdlabelgen assumes a scaleratio
158           of 1.0. This flag allows you to squeeze larger graphics into the
159           cover or expand smaller graphics to fill the cover. Scaleratio must
160           be a number (int or float).
161
162           If the scale value passed is 0 (or 0.0), then the logo is used as a
163           background image - it will be scaled as required to fit the entire
164           cover.
165
166           The -S option also takes optional translate arguments.  Normally
167           images are printed on the cover and the tray so that the bottom-
168           right of the image is anchored to the bottom-right of the cover or
169           tray. To move the images away from the bottom and right borders,
170           use this option. For example, to leave two inches of gap between
171           the image and the bottom border, and 0.5 inches from the left
172           border, and use 1.0 scaleratio, use this: -S 1.0,-2,0.5
173
174           This offset only applies when the image is being used as a logo -
175           i.e., image is not being used as background to fill the entire
176           cover or tray.
177
178       -E, --tray-image <tray_epsfile>
179           Filename of eps file to print on traycard. Note that cdlabelgen
180           requires that the eps file contain a proper '%%BoundingBox LLx LLy
181           URx URy' declaration according to the PostScript Document
182           Structuring Conventions. cdlabelgen uses this line to determine the
183           dimensions of the eps graphic so that it can position it
184           appropriately on the cover. Note that cdlabelgen first looks for
185           this file in your working directory. If it doesn't find it there,
186           it will look in the list of directories where the default eps files
187           are stored (see @where_is_the_template). This makes it easy to use
188           the images shipped with cdlabgelgen without typing miles of
189           pathnames.
190
191       -T, --tray-image-scaleratio <tray_eps_scaleratio
192       [,image_x_offset,image_y_offset_inches]>
193           The ratio by which you want to scale the epsfile that appears on
194           the traycard. If you omit this flag, cdlabelgen assumes a
195           scaleratio of 1. This flag allows you to squeeze larger graphics
196           into the traycard or expand smaller graphics to fill the traycard.
197           Scaleratio must be a positive number (int or float) specifying the
198           scale.
199
200           If the scale value passed is the word fill1, then the image is used
201           as a background - it is scaled so that it completely fills the
202           interior tray card region.  The value 0 (or 0.0) works same as the
203           fill1 argument.
204
205           If the value passed is the word fill2, then the image is used as a
206           background to fill more than just the tray.  For normal CD cases,
207           the image is scaled so that it completely fills both the tray card
208           region, and the two endcaps (but not the extreme right-hand
209           'tongue-cap') for normal cd cases.  For Slim CD cases or DVD
210           Inside/Outside covers, the tray image will fill both the tray and
211           cover regions (including any spines).  For directly printing on a
212           CD (--create-cdlabel), fill2 option works like the fill1 option.
213
214           The -T option also takes optional translate arguments.  Normally
215           images are printed on the cover and the tray so that the bottom-
216           right of the image is anchored to the bottom-right of the cover or
217           tray. To move the images away from the bottom and right borders,
218           use this option. For example, to leave two inches of gap between
219           the image and the bottom border, and 0.5 inches from the left
220           border, and use 1.0 scaleratio, use this: -T 1.0,-2,0.5
221
222           This offset only applies when the image is being used as a logo -
223           i.e., image is not being used as background to fill the entire
224           cover or tray.
225
226       -o, --output-file <outputfile>
227           If the -o flag is used, cdlabelgen prints to outputfile instead of
228           STDOUT.
229
230       -t, --template <template>
231           Specify explicitly which template to use. This is useful if you
232           need to debug the PostScript code in the template, use a different
233           template, or if you have created your own template to use in lieu
234           of the one provided with cdlabelgen.
235
236       -b, --no-tray-plaque
237           Suppresses printing of the Plaque on the traycard, thus allowing
238           you to either fit even more items on the traycard, or to use a
239           slightly larger font size for the items.
240
241       -C, --no-cover-plaque
242           Suppresses printing of the plaque on the front cover, thus allowing
243           a cover image that fills the front cover, but still displaying
244           category and sub-category information in the other usual places.
245
246       -h, --help
247           print out the usage message
248
249       -w, --tray-word-wrap
250           Enables word wrapping of the items that print on the traycard. Note
251           that this is *not* extensively tested and may be buggy! Make sure
252           that you preview your label before printing it if you use this
253           flag.
254
255           If there is a problem with "-w", the best option right now is to
256           split lines in the input itself, and to omit the "-w" option.
257
258       -m, --slim-case
259           Creates covers suitable for use in slim cd-cases, this means no
260           tray card (the tray card is now the inside front cover).  This
261           creates a two page, folding cover insert. This could also be used
262           in normal cd cases as an inside insert.
263
264           Slim case option can be used with outside dvd inserts (
265           --create-dvd-outside ) also - in which case the outside insert is
266           created for half-height DVD case.
267
268       -O, --outside-foldout
269           Output slim cd cover cases (or dvd inserts) with the order of the
270           pages switched so the folding line lies on the outside of a normal
271           case. Can be used when printing either the slim-cd-case or dvd-
272           inside inserts.
273
274           This option is best used along with option -m (--slim-case) or
275           --create-dvd-inside.
276
277       --rotate-endcaps
278           Endcap text is rotated by 180 degrees, to flip the text around.
279
280       -M, --create-envelope
281           Creates covers suitable for use as envelopes for a CD. Guide lines
282           are printed, to aid in folding the printout correctly.
283
284       --create-dvd-inside
285           Creates inserts suitable for use as inside insert for a normal DVD
286           case.  Guide lines are printed, to aid in folding the printout
287           correctly.  Note: DVD inserts may not print fully on Letter or A4
288           sized paper printers; it may require larger paper sizes.
289
290       --create-dvd-outside
291           Creates inserts suitable for use as outside cover inserts for a
292           normal DVD case.  Guide lines are printed, to aid in folding the
293           printout correctly.  Note: DVD inserts may not print fully on
294           Letter or A4 sized paper printers; it may require larger paper
295           sizes.
296
297           Slim case option ( --slim-case ) can be used with outside dvd
298           inserts also - in which case the outside insert is created for
299           half-height DVD case.
300
301       --double-case
302           Create covers for double-sided DVD cases that hold 6 DVDs.  Only
303           double-width DVD cases are supported, double-width CD cases are not
304           supported.  Therefore, using --double-case also implies the
305           --create-dvd-outside option.  Note: DVD inserts may not print fully
306           on Letter or A4 sized paper printers; it may require larger paper
307           sizes.
308
309       --slim-double-case
310           Create covers for double-sided DVD cases that hold 6 DVDs in boxes
311           1.5 times the depth of normal dvd cases.  Only DVD cases are
312           supported with this option, slim-double-width CD cases are not
313           supported.  Therefore, using --slim-double-case also implies the
314           --create-dvd-outside option.  Note: DVD inserts may not print fully
315           on Letter or A4 sized paper printers; it may require larger paper
316           sizes.
317
318       --create-cdlabel
319           For directly printing on a CD or DVD. As of January 2005, there are
320           inkjets printers that can print on certain types of blank CD/DVD
321           discs.  Only a small number of items can be printed on the CD, and
322           the number of characters in the title and subtitle is also limited.
323           Always check the output visually by using PostScript viewers or
324           printing on paper, before printing on the CD.
325
326           With this option, the top portion of the disc represents the
327           "cover" area - so arguments related to the cover: title
328           (--category), subtitle (--subcategory), --no-cover-plaque,
329           --cover-items, --cover-image, etc all apply to the top area.  The
330           bottom portion of the disc represents the "tray" area, so arguments
331           related to the tray: --no-tray-plaque, --tray-image, etc all apply
332           to the bottom area.  The date (--date) string, if present, is
333           printed along the bottom curved edge of the disc.
334
335           Background images can be specified using the --cover-image option,
336           modified as need by the --cover-image-scaleratio.  If --tray-image
337           is also specified, note that the cover image is printed first, then
338           the tray image overwrites the cover image. The title/items text is
339           then finally printed over all the images.
340
341           The --no-tray-plaque and/or --no-cover-plaque (along with
342           --cover-items) option is also recommended with --create-cdlabel,
343           otherwise there may be no space for any items to be printed on the
344           disc.
345
346           The --clip-items option is also recommended.
347
348       -p, --clip-items
349           Enables clipping of items; uses fixed font size for all items.
350           Normally, the template.ps used by cdlabelgen will try to fit an
351           item in a given column by reducing the font size if needed. This is
352           ok if done for one or two items, but if done too often, it makes
353           the tray card look ugly, with text of varying font sizes.
354
355           Use this option to use a fixed width font for all items. If the
356           item is too large to fit in a column, the text will be clipped
357           instead.
358
359       -y, --page-offset [<page_x_offset_inches,]<page_y_offset_inches
360           Use this to move the entire output up or down (y_offset), to make
361           the output fit on appropriate sized paper. For letter sized paper,
362           0.8 works well, and for A4 paper, 1.5 works well. The value is in
363           units of inches.  An optional X-axis offset can also be specified.
364           Default values: 1 inch for X-axis, 0.8 inches for Y-axis.
365
366       -l, --line-width <line_width_points>
367           Specify size in points of the edge and interior lines of the cover
368           and tray card.  If this is 0, then the lines are omitted for both
369           the cover and tray (but guide cut lines are still printed). The
370           size is specified in points (1 point is 1/72 inch).
371
372       --plaque-color <r,g,b>
373           Specify a color to fill plaque.  Color must be specified using the
374           rgb components, each value should be between 0 and 255.
375
376       --category-color <r,g,b>
377           Specify a color for category.  Color must be specified using the
378           rgb components, each value should be between 0 and 255.
379
380       --subcategory-color <r,g,b>
381           Specify a color for subcategory.  Color must be specified using the
382           rgb components, each value should be between 0 and 255.
383
384       --text-color <r,g,b>
385           Specify a color for text - this is used for the list of items, and
386           the date display under the plaque and in the end-caps.  Color must
387           be specified using the rgb components, each value should be between
388           0 and 255.
389
390       -n, --number-in-set <string>
391           Append volume information to the end of the date string.  This
392           should be a single string.  If used in conjuction with "-D", it
393           will be in place of the date; otherwise, it is appended to the date
394           as " - <number-in-set>"
395
396       --rows-columns <row_count_for_items,column_count_for_items>
397           The --rows-columns options forces the list of items to be printed
398           using that many rows, and that many columns.  Both numbers have to
399           be provided, no spaces, for example: --rows-columns=11,3
400
401           The list of items is laid out in top-down, left-to-right fashion.
402           Use blank items in the input, to get appropriately aligned columns.
403
404           --rows-columns applies to the list of items wherever they are
405           printed - normally on the tray only, but may include cover, or the
406           top and bottom portions of the round printouts for direct CD label
407           printing.  Same values apply to all these variations, so if you
408           need different number of rows/columns for cover vs tray, you can
409           use two different runs of cdlabelgen, to get two postscript files,
410           and pick the cover from one printout, and tray from the other.
411           This will work for jewel-case inserts, but may not work for direct
412           CD label printing.
413
414       --tray-overlay overlay_epsfile
415           Filename of eps file to print as overlay on traycard. This image is
416           printed over the background image (tray-image) as well as the list
417           of items. Therefore, this is useful for things like barcodes.  In
418           terms of EPS file requirements, see the --tray-image option
419           description.
420
421       --tray-overlay-scaleratio
422       tray_overlay_image_scaleratio[,image_x_offset,image_y_offset_inches]
423           The ratio by which you want to scale the epsfile that is used with
424           the --tray-overlay option, and optionally to translate the overlay.
425           Normally overlay image is printed on the tray so that the bottom-
426           right of the image is anchored to the bottom-right of the tray. To
427           move the images away from the bottom and right borders, use this
428           option. For example, to leave 0.1 inches of gap between the image
429           and the bottom border, and 0.2 inches from the right border, and
430           use 1.0 scaleratio (no scaling), use this:
431           --tray-overlay-scaleratio 1.0,-0.2,0.1
432

EXAMPLES

434           cdlabelgen -c "My Filesystem"
435                        -s "/usr/local/foo"
436                        -e postscript/recycle.eps > foo.ps
437
438           cdlabelgen -c "title of cd"
439                        -s "subtitle"
440                        -i "Item 1%and Item 2%a third item here perhaps"
441                        -e postscript/recycle.eps -o bar.ps
442
443           cdlabelgen -c "Fitz"
444                        -s "home directory"
445                        -o qux.ps
446
447
448           cdlabelgen -c "Backups"
449                        -s "home directory"
450                        -n "4 of 5"
451
452           Direct printing on a CD or DVD, if file "example5.txt" has list of items:
453           cdlabelgen --clip-items --no-tray-plaque --date "Jan 2005"
454             -c "Collections 12" -s "- english songs -"
455             --cover-image "music2.eps" --cover-image-scaleratio 0.0
456             --tray-image "mp3.eps" --tray-image-scaleratio 0.5,-0.5,2
457             --page-offset 0.5,0.5 -f example5.txt -o test.ps
458

CHARACTER ENCODINGS - using ogonkify

460       cdlabelgen uses the Helvetica family of fonts for various text items,
461       using the default encoding of ISO-Latin1.
462
463       To use other encodings, the "ogonkify" program can be used; this is a
464       package available at http://www.pps.jussieu.fr/~jch/software/ogonkify/
465       The output from cdlabelgen can be piped into ogonkify, example for
466       Latin2 encoding:
467
468          cdlabelgen <args>  | ogonkify -H -eL2    > <outputfilename>
469
470       See the man page for ogonkify for other possible values for the
471       encoding.
472
473       Hint: if you always work with a particular encoding, you can just run
474       ogonkify on template.ps - and use the output as the new template.ps.
475
476          ogonkify -H -eL2 template.ps > template-enc.ps
477
478       This way ogonkify has to be run only once, cdlabelgen output will
479       contain the correctly encoded fonts from the modified template.ps. Use
480       the -t cdlabelgen option to specify the new template-enc.ps file, or
481       save the old template.ps and renmae template-enc.ps to template.ps.
482

PRINTING

484       When using tools such as Adobe Acrobat to print the .ps or a .pdf file,
485       make sure that "Fit To Paper" option is unchecked.  Also uncheck any
486       option that will perform scaling up or down of the cdlabelgen output
487       file.
488
489       Failure to do so will result in incorrect size printouts.
490
491       Paper Sizes: Normal CD cases, Slim CD cases, DVD inside inserts can be
492       printed on a letter or A4 sized page.  CD/DVD Envelopes and DVD outside
493       inserts will not fit on a letter sized paper, a larger paper size will
494       be needed to make it fit.
495
496       When using different sized paper, experimentation with the -y (also:
497       --page-offset) [<page_x_offset_inches,]<page_y_offset_inches> option
498       may be required to place the image in the printable region of the
499       paper.
500

AUTHOR

502       Avinash Chopde <avinash@aczoom.com>
503
504       Original author: B. W. Fitzpatrick <fitz@red-bean.com>
505

THANKS

507           - Karl Fogel, for general encouragement and that free software vibe
508           - Adam Di Carlo, for bug testing, help and making the .deb
509           - Greg Gallagher, for bug testing, coding, and tons of suggestions
510           - Goran Larsson, for feedback and date fixes
511           - Jens Claussen, for the patch to allow arbitrary ISO-Latin1 characters
512           - Bernard Quatermass, for contributing several excellent new features
513           - Sebastian Wenzler <sick@home.and.drunk.at> for reports, tests, RPM ['01]
514           - Peter Bieringer <pb@bieringer.de> for RPM .spec file ['02]
515           - Ronald Rael Harvest <number6@cox.net> for original envelope template ['02]
516           - Alessandro Dotti Contra <alessandro.dotti@libero.it> for color support,
517               man page and other improvements ['02]
518               Mathias Herberts
519           - Mathias Herberts <Mathias.Herberts@iroise.net>, for slim cdcase foldout
520           - Stephan Grund <Stephan.Grund@isst.fraunhofer.de>, for monospaced
521             font and for rotated-end-caps text support
522           - Dominique Dumont <dod@debian.org>
523               for half-height DVD case support
524               for slim-double depth DVD case support
525               (patches forwarded by Juan Manuel Garcia Molina <juanma@debian.org>)
526           - Peter Bieringer <pb@bieringer.de> for testing CD label printint ['05]
527           - Andras Salamon <asalamon@chello.hu> for double-width DVD support ['08]
528

TODO

530        ** Word wrap does not work well at all. It will clip lines, or it will
531           auto-reduce the font size, both of which option look bad.
532
533        ** Ability to change the text style on a given line:
534           {#B}Track#  {#P}Title   {#I} Text...
535           [Workaround available: just use multi columns input, use blank
536            lines to spread out input items into columns]
537
538        ** Ability to select or specify fonts for the text/items
539
540
541
542perl v5.10.0                      2012-04-15                     CDLABELGEN(1)
Impressum