NAME

       Games::Go::Dg2Mp - Perl extension to convert Games::Go::Diagrams to John Hobby's MetaPost
       (which is adapted from Donald Knuth's Metafont).

SYNOPSIS

       use Games::Go::Dg2Mp

        my $dg2mp = B<Games::Go::Dg2Mp-E<gt>new> (options);
        $dg2mp->convertDiagram($diagram);

DESCRIPTION

       A Games::Go::Dg2Mp object converts a Games::Go::Diagram object into a TeX (.tex) and a
       MetaPost (.mp) file.  The MetaPost file contains figures for each of the diagrams and
       overstones required to make the complete game diagram.  Running MetaPost (mpost or
       possibly mp) on the .mp file creates a set of figure files, each of which is an
       Encapsulated PostScript figure.  Running TeX (tex) on the .tex file creates a .dvi file
       which tries to include the Encapsulated PostScript figures.  Running dvips on the .dvi
       file (from TeX) creates the final PostScript (.ps) file containing the complete game
       diagram.

       See 'man mpost' (or possibly 'man 'mp') for more details of the overall MetaPost system
       and environment.

METHODS

       my $dg2mp = Games::Go::Dg2Mp->new (?options?)
           A new Games::Go::Dg2Mp takes the following options:

   General Dg2 Converter Options:
       boardSize => number
           Sets the size of the board.

           Default: 19

       doubleDigits => true | false
           Numbers on stones are wrapped back to 1 after they reach 100.  Numbers associated with
           comments and diagram titles are not affected.

           Default: false

       stone_width => points
       stone_height => points
           The stone_width and stone_height determine the size of the stones and diagrams.

           If stone_width is not explicitly set, it is calculated from the stone_fontSize to
           allow up to three digits on a stone .  The default stone_fontSize allows for three
           diagrams (with -coords) per 'letter' page if comments don't take up extra space below
           diagrams.  If doubleDigits is specified, the stones and board are slightly smaller
           (stone 100 may look a bit cramped).

           If stone_height is not explicitly set, it will be 1.05 * stone_width, creating a
           slightly rectangular diagram.

           Default: undef - determined from stone_fontSize

       coords => true | false
           Generates a coordinate grid.

           Default: false

       topLine     => number (Default: 1)
       bottomLine  => number (Default: 19)
       leftLine    => number (Default: 1)
       rightLine   => number (Default: 19)
           The edges of the board that should be displayed.  Any portion of the board that
           extends beyond these numbers is not included in the output.

       diaCoords => sub { # convert $x, $y to Diagram coordinates }
           This callback defines a subroutine to convert coordinates from $x, $y to whatever
           coordinates are used in the Games::Go::Diagram object.  The default diaCoords converts
           1-based $x, $y to the same coordinates used in SGF format files.  You only need to
           define this if you're using a different coordinate system in the Diagram.

           Default:
               sub { my ($x, $y) = @_;
                     $x = chr($x - 1 + ord('a')); # convert 1 to 'a', etc
                     $y = chr($y - 1 + ord('a'));
                     return("$x$y"); },           # concatenate two letters

       print => sub { my ($dg2mp, @tex) = @_; ... }
           A user defined subroutine to replace the default printing method.  This callback is
           called from the print method (below) with the reference to the Dg2Mp object and a list
           of lines that are part of the TeX diagram source.

   Dg2Mp-specific options:
       stone_fontName => 'font'  Default: 'cmssbx10'
           Quoting from the discussion on fonts in section 7 of _A User's Manual for MetaPost_
           (by John D. Hobby):

           "...the new font name should be something that TEX would understand since MetaPost
           gets height and width information by reading the tfm file. (This is explained in The
           TEXbook. [5] ) It should be possible to use built-in PostScript fonts, but the names
           for them are system-dependent. Some systems may use rptmr or ps-times-roman instead of
           Times-Roman. A TEX font such as cmr10 is a little dangerous because it does not have a
           space character or certain ASCII symbols. In addition, MetaPost does not use the
           ligatures and kerning information that comes with a TEX font."

       stone_fontSize => points
           The stone_fontSize determines the size of the stones and diagrams.  Stone size is
           chosen to allow up to three digits on a stone.

           If doubleDigits is specified, the stones and board are slightly smaller (stone 100 may
           look a bit cramped).

           Default: 8

       $dg2mp->configure (option => value, ?...?)
           Change Dg2Mp options from values passed at new time.

       $dg2mp->print ($tex ? , ... ?)
           prints raw TeX code to file as defined at new time.  Whether or not file was defined,
           print accumulates the TeX code for later retrieval with converted.  The TeX output
           filename is derived from the MetaPost filename by changing the .mp extension to .tex.

       $dg2mp->print ($tex ? , ... ?)
           prints raw MetaPost code to MetaPost output file (as defined at ->new or ->configure
           time).

       my $tex = $dg2mp->converted ($replacement_tex)
           Returns the TeX source code converted so far for the Dg2Mp object.  If
           $replacement_tex is defined, the accumulated TeX source code is replaced by
           $replacement_tex.

       $dg2mp->comment ($comment ? , ... ?)
           Inserts the TeX comment character ('%') in front of each line of each comment and
           prints it to file.

       my $tex_source = $dg2mp->convertDiagram ($diagram)
           Converts a Games::Go::Diagram into TeX/MetaPost.  If file was defined in the new
           method, the TeX source is dumped into the file.tex and the MetaPost source into
           file.mp.  In any case, the TeX source is returned as a string scalar.

       my $tex = $dg2mp->convertText ($text)
           Converts $text into TeX code by changing certain characters that are not available in
           TeX cmr10 font, and by converting \n\n into \hfil\break.  convertText behavior is
           modified by texComments and simple options.

           Returns the converted text.

       $tex_title = $dg2mp->convertProperties (\%sgfHash)
           convertProperties takes a reference to a hash of properties as extracted from an SGF
           file.  Each hash key is a property ID and the hash value is a reference to an array of
           property values: $hash->{propertyId}->[values].  The following SGF properties are
           recognized:

           GN GameName
           EV EVent
           RO ROund
           PW PlayerWhite
           WR WhiteRank
           PB PlayerBlack
           BR BlackRank
           DT DaTe
           PC PlaCe
           GC GameComment
           KM KoMi
           RE REsult
           TM TiMe

           Both long and short property names are recognized, and all unrecognized properties are
           ignored with no warnings.  Note that these properties are all intended as game-level
           notations.

       $dg2mp->close
           print the TeX closer (\bye) and close the dg2mp object.  Also closes file if
           appropriate.

SEE ALSO

       sgf2dg(1)
           Script to convert SGF format files to Go diagrams

BUGS

       Is this a trick question?

AUTHOR

       Reid Augustin, <reid@hellosix.com>

COPYRIGHT AND LICENSE

       Copyright (C) 2005 by Reid Augustin

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself, either Perl version 5.8.5 or, at your option, any later version of
       Perl 5 you may have available.