Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

PostScript::Calendar
Generate a monthly calendar in PostScript

PostScript::Calendar - Generate a monthly calendar in PostScript


NAME

PostScript::Calendar - Generate a monthly calendar in PostScript


VERSION

This document describes PostScript::Calendar version 0.03


SYNOPSIS


  use PostScript::Calendar;

  my $cal = PostScript::Calendar->new($year, $month, phases => 1,

                                      mini_calendars => 'before');

  $cal->output('filename');


DESCRIPTION

PostScript::Calendar generates printable calendars using PostScript.

PostScript::Calendar uses Date::Calc's *_to_Text functions, so you can change the language used by calling Date::Calc's Language function before creating your calendar.

Years must be fully specified (e.g., use 1990, not 90). Months range from 1 to 12. Days of the week can be specified as 0 to 7 (where Sunday is either 0 or 7, Monday is 1, etc.).

All dimensions are specified in PostScript points (72 per inch).


INTERFACE

$cal = PostScript::Calendar->new($year, $month, [key => value, ...])

This constructs a new PostScript::Calendar object for $year and $month.

There are a large number of parameters you can pass to customize how the calendar is displayed. They are all passed as name => value > pairs.

border
If false, omit the border around the calendar grid (only internal grid lines are drawn). The default is true.

condense
If true, reduce calendars that would span 6 rows down to 5 rows by combining either the first or last day with its neighbor. The default is false.

day_height
The maximum height of a date row. This is useful to prevent portrait-mode calendars from taking up the entire page (which just doesn't look right). The default is 0, which means there is no maximum value. I recommend 96 for a portrait-mode calendar on US letter size paper.

mini_calendars
This causes small calendars for the previous and next months to be printed. The value should be "before" to put them before the first of the month, "after" to put them after the last day of the month, or "split" to put the previous month before and the next month after. The default is a false value (which means no mini calendars).

phases
If true, the phase of the moon icons are printed (requires Astro::MoonPhase 0.60). The default is false.

title
The title to be printed at the top of the calendar. The default is ``Month YEAR'' (where Month comes from Month_to_Text, and YEAR is numeric.) Setting this to the empty string automatically sets title_size and title_skip to 0 (completely suppressing the title).

days
An arrayref specifying the days of the week to be included in the calendar. The first day must be in the range 0 to 6 (where Sunday is 0, Monday is 1, etc.). Subsequent days must be in ascending order, up to the initial day + 6.The default is [ 0 .. 6 ] (meaning Sunday thru Saturday). Other popular values are [ 1 .. 7 ] for Monday thru Sunday or [ 1 .. 5 ] for Monday thru Friday (no weekends).

You may skip over days if you don't want them included. For example, [ 3, 5, 8 ] would display Wednesday, Friday, and Monday (with weeks starting on Wednesday).

day_names
Arrayref of the column labels. Defaults to passing the (normalized) values from days thru Date::Calc's Day_of_Week_to_Text, which is probably what you want.

title_font
The font to use for the title. Defaults to Helvetica-iso.

title_size
The size of the title_font to use. Defaults to 14.

title_skip
Extra space (in points) to leave below the title. Defaults to 5.

label_font
The font to use for the days of the week. Defaults to title_font.

label_size
The size of the label_font to use. Defaults to title_size.

label_skip
Extra space (in points) to leave below the weekday labels. Defaults to title_skip.

date_font
The font to use for the dates of the month. Defaults to Helvetica-Oblique-iso.

date_size
The size of the date_font to use. Defaults to title_size.

event_font
The font to use for text events (added by add_event). Defaults to Helvetica-iso.

event_size
The size of the event_font to use. Defaults to 8.

event_skip
Extra space (in points) to leave between lines of event text. Defaults to 2.

mini_font
The font to use for mini calendars. Defaults to Helvetica-iso.

mini_size
The size of the mini_font to use. Defaults to 6.

mini_skip
Extra space (in points) to leave between the lines of mini calendars. Defaults to 3.

date_right_margin
Space (in points) to leave between the date and the gridline. Defaults to 4.

date_top_margin
Space (in points) to leave between the date and the gridline. Defaults to 2.

event_margin
This is used as the default value for event_top_margin, event_left_margin, and event_right_margin.

event_top_margin
The space (in points) to leave above event text. Defaults to event_margin, or 2 if event_margin is not specified.

event_left_margin
The space (in points) to leave to the left of event text. Defaults to event_margin, or 3 if event_margin is not specified.

event_right_margin
The space (in points) to leave to the right of event text. Defaults to event_margin, or 2 if event_margin is not specified.

mini_margin
This is used as the default value for mini_top_margin and mini_side_margins. Defaults to 4.

mini_top_margin
The space (in points) to leave above mini calendars. Defaults to mini_margin.

mini_side_margins
The space (in points) to leave on each side of mini calendars. Defaults to mini_margin.

moon_margin
Space to leave above and to the left of the moon icon. Defaults to 6.

shade_days_of_week
An arrayref of days of the week to be passed to the shade_days_of_week method. (I found it convenient to be able to pass this to the constructor instead of making a separate method call.)

margin
This is used as the default value for top_margin, side_margins, and bottom_margin.

side_margins
The space (in points) to leave on each side of the calendar. Defaults to margin, or 24 if margin is not specified.

top_margin
The space (in points) to leave above the calendar. Defaults to margin, or 36 if margin is not specified.

bottom_margin
The space (in points) to leave below the calendar. Defaults to margin, or 24 if margin is not specified.

paper
The paper size to pass to PostScript::File. Defaults to "Letter". Not used if you supply ps_file.

landscape
If true, print calendar in landscape mode. Defaults to false. Not used if you supply ps_file.

ps_file
Allows you to pass in a PostScript::File (or compatible) object for the calendar to use. By default, a new PostScript::File object is created.

$cal->add_event($date, $message)

This prints the text $message on $date, where $date is the day of the month. You may call this multiple times for the same date. Messages will be printed in the order they were added. $message may contain newlines to force line breaks.

$cal->shade($date, ...)

This colors the background of the specified date(s) a light gray, where $date is the day of the month. Any number of dates can be given.

$cal->shade_days_of_week($day, ...)

This calls shade for all dates that fall on the specified day(s) of the week. Each $day should be 0-7 (where Sunday is either 0 or 7).

$cal->generate

This actually generates the calendar, placing it in the PostScript::File object. You shouldn't need to call this, because output calls it automatically.

$cal->output($filename)

This passes its parameters to PostScript::File::output (after calling generate if necessary). Normally, you just pass the filename to write. Note that PostScript::File will append ``.ps'' to the output filename.

$cal->ps_file

This returns the PostScript::File object that $cal is using. Only needed for advanced techniques.


DIAGNOSTICS

WARNING: Event text for YYYY-MM-DD doesn't fit
You supplied more event text for the specified date than would fit in the box. You'll have to use a smaller font, smaller margins, or less text.


CONFIGURATION AND ENVIRONMENT

PostScript::Calendar requires no configuration files or environment variables.

However, it uses the Font::AFM manpage, and unfortunately that's difficult to configure properly. I wound up creating symlinks in /usr/local/lib/afm/ (which is one of the default paths that Font::AFM searches if you don't have a METRICS environment variable):


 Helvetica.afm         -> /usr/share/fonts/afms/adobe/phvr8a.afm

 Helvetica-Oblique.afm -> /usr/share/fonts/afms/adobe/phvro8a.afm

Paths on your system may vary. I suggest searching for .afm files, and then grepping them for ``FontName Helvetica''. Helvetica and Helvetica-Oblique are the two fonts that PostScript::Calendar uses by default, and Font::AFM expects to find files named Helvetica.afm and Helvetica-Oblique.afm.


DEPENDENCIES

the Date::Calc manpage (5.0 or later), the Font::AFM manpage, and the PostScript::File manpage.

If you want to display phases of the moon, you'll need the Astro::MoonPhase manpage 0.60 or later.


INCOMPATIBILITIES

None reported.


BUGS AND LIMITATIONS

No bugs have been reported.


AUTHOR

Christopher J. Madsen <perl AT cjmweb.net>

Please report any bugs or feature requests to <bug-PostScript-Calendar AT rt.cpan.org>, or through the web interface at http://rt.cpan.org/Public/Bug/Report.html


LICENSE AND COPYRIGHT

Copyright 2007 Christopher J. Madsen. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.


DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy