NAME

PostScript::CDCover - a simple module that generates CD covers in Postscript

SYNOPSIS

    use PostScript::CDCover;

    my $cd = new PostScript::CDCover -root => 'root', -title => 'Backup';
    $cd->add_file('root/sub1/file11');
    $cd->add_file('root/sub1/file12');
    $cd->add_file('root/sub2/file21');
    $cd->add_file('root/sub2/file22');

    $cd->flush();

DESCRIPTION

This class generates a Postscript program that prints a CD cover suitable for a CD jewel case. A directory tree is printed on the cover in columns, first on the front page, then on the inner page (the one that is visible when the box is open), and finally on the back label. All in all, the output consists of two A4 pages, one for the front and inner pages, and one for the back label. People using exotic paper formats should still be able to print, provided that their paper size is close enough to A4, as the labels are drawn rather far from the paper edge. Notably, printing on Letter has been reported to not cause any trouble.

A title is printed on top of the front page, and on the sides of the back label. Various attributes alter the behaviour of the module and the layout of the generated cover.

Typically, a program using this module should:

Instantiate the PostScript::CDCover class, possibly giving values to attributes by passing arguments to the constructor. Setting these values can also be achieved by calling the accessor methods directly.
Feed information about subdirectories and files in the directory tree by means of the add_directory() and add_file() methods.
Call the flush() method to actually generate the Postscript program.

Such a program (too usable actually to be called a mere example) is shipped with this module: pscdcover(1)

Editing the output

The output generated by the flush() method can be directly printed or converted to PDF or whatever. However, it has been designed to be easily modified, even without much knowledge of the Postscript language.

The layout of the file and directory names in the different columns and pages is done by the PostScript program. This makes it possible and easy to edit the resulting PostScript program with a text editor and remove some lines.

The editable section looks like this (text within parentheses are the files and directory names, the figure that follows it is the depth in the directory tree):

    (directory 1) 0 folder_title
      (file 1) 1 file_title
      (file 2) 1 file_title
      (file 3) 1 file_title
      (file 4) 1 file_title
      (file 5) 1 file_title
      (file 6) 1 file_title
      (file 7) 1 file_title
      (file 8) 1 file_title
      (file 9) 1 file_title
      (file 10) 1 file_title
      (file 11) 1 file_title
      (file 12) 1 file_title
    (directory 2) 0 folder_title

In order to shorten the list (so that it fits on the three pages, for instance), you may simply change the above to:

    (directory 1) 0 folder_title
      (...) 1 file_title
      (lots of files) 1 file_title
      (...) 1 file_title
    (directory 2) 0 folder_title

You need not worry about the final layout, whether a directory has changed columns or not, all this is taken care of by the PostScript interpreter.

Constructor

new() creates and returns an instance of PostScript::CDCover. new() accepts as arguments a list of key/value pairs to initialize attributes. Each value is simply passed to the method named after the key. The key may optionally be prefixed with a dash, and of course, the use of double-barrel arrows => is recommended for readability.

These two code snippets are equivalent:

    my $cd = new PostScript::CDCover;
    $cd->all(1);
    $cd->box(1);
    $cd->files(0);

    my $cd = new PostScript::CDCover -all => 1, -box => 1, -files => 0;

Attributes

Attributes are accessed through accessor methods. These methods, when called without aN ARGUMENt, will return the attribute's value. With an argument, they will set the attribute's value to that argument, and return the former value.

When applicable, the default value is given in parentheses.

all (0): Forces the printing of all the pages (front and back), even if the whole directory tree could be printed on only the first page.
box (1): By default, the edges of the cover are drawn in dim gray. Set this to 0 to prevent this (only the text will be printed out). You probably want to leave the default if you use cisors to cut the covers.
color (0): Generate color output: the CD and folder icons will be drawn in colors. The colors can be changed with the cdcolor and foldercolor attributes.
cdcolor (0xccd8e5, i.e. light blue)
foldercolor (0xffff80, i.e. light yellow): Colors of the CD icon and folder icon, respectively. They should be the integer value of an hexadecimal triplet representing the shares of red, green and blue in the desired color, like those commonly found in HTML or CSS.
columns (2): The number of columns to print on each page. When set to 0, the column widths will be calculated dynamically, so that the longest filename in each column fits.
minwidth (25): The minimum allowed width for a column (in millimeters). If the room left on the right side of the page is lower than this limit, the next column will be printed on the next page. This option is only relevant with columns set to 0.
output (\*STDOUT): Where the generated PostScript code will be written to. The value can be one of: a file GLOB opened ready for output (the default is \*STDOUT, meaning the standard output), a reference to a scalar to which the output is appended, a reference to a subroutine which is called, passing the output as a parameter, or any object reference which implements a print() method (e.g. IO::Handle) which will be called, passing the generated output as a parameter.
ps: The path to the Postscript program. This is actually a template as it requires some processing before being fed to the printer. By default, the template is located in the same directory as the PostScript::CDCover module itself.
root (/media/cdrom): The directory at the root of the CD-ROM, i.e., its mount point. This value will be removed from entries added with add_directory() or add_file(), so that the CD-ROM mount point does not show on the CD cover.
separator (0): Set this to 1 to draw a line as column separator.
title (undef): Provides a title for the CD. The title will be printed on top of the first page, and on the sides of the back label.

Methods

add_directory(path)

add_file(path)

Adds a directory or a file to the CD content. The path argument should start with the value of attribute root(). Both add_directory() and add_file() will call add_directory() for any parent directory along the way. Calling add_directory() is still useful for empty directories, non empty ones would be created when adding files within.

flush

Generates the Postscript program, taking all the attributes and the contents into account. flush() can called repeatedly, changing a couple of attributes in between, e.g.:

    $cd->color(1);
    $cd->flush();
    $cd->color(0);
    $cd->flush();

BUGS

Very likely.

AUTHOR

Cédric Bouvier <cbouvi@cpan.org>

Thank you to Terry Gliedt, Sean the RIMBoy, Michael M. Tung for their help with bug fixing and enhancing, and to Andy Wardley (of Template Toolkit fame) whom I borrowed the versatile output destination code from.

PostScript::CDCover - a simple module that generates CD covers in Postscript