NAME

       Games::Go::Dg2TeX - Perl extension to convert Games::Go::Diagrams to TeX

SYNOPSIS

       use Games::Go::Dg2TeX

        my $dg2tex = B<Games::Go::Dg2TeX-E<gt>new> (options);
        my $tex = $gd2tex->convertDiagram($diagram);

DESCRIPTION

       A Games::Go::Dg2TeX object converts a Games::Go::Diagram object into TeX source code which
       can be used stand-alone, or it can be incorporated into larger TeX documents.

METHODS

       my $dg2tex = Games::Go::Dg2TeX->new (?options?)
           A new Games::Go::D2TeX 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

       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 Games::Go::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

       file => 'filename' | $descriptor | \$string | \@array
           If file is defined, the TeX source is dumped into the target.  The target can be any
           of:

           filename
               The filename will be opened using IO::File->new.  The filename should include the
               '>' or '>>' operator as described in 'perldoc IO::File'.  TeX source is written
               into the file.

           descriptor
               A file descriptor as returned by IO::File->new, or a \*FILE descriptor.  TeX
               source is written into the file.

           reference to a string scalar
               TeX source is concatenated to the end of the string.

           reference to an array
               TeX source is split on "\n" and each line is pushed onto the array.

           Default: undef

       print => sub { my ($dg2tex, @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 Dg2TeX object and a
           list of lines that are part of the TeX diagram source.

   Dg2TeX-specific options
       longComments => true | false
           In its default usage, the comments to each diagram comprise an unbreakable vbox---they
           must all appear on one page. This can cause problems if the comments are very
           extensive. This option generates more complicated TeX macros which allow the comments
           to be broken across pages. This option may not be used with -simple or -longComments.

           Default: true

       simple => true | false
           This generates very simple TeX which may not look so good on the page, but is
           convenient if you intend to edit the TeX. This option should not be used with
           -longComments.

           Default: false

       twoColumn => true | false
           This generates a two-column format using smaller fonts. This option forces simple
           true, and it may not be used with -longComments or -coords.

           Default: false

       coords => true | false
           Generates a coordinate grid. This option may not be used with -twoColumn.

           Default: false

       bigFonts => true | false
           Use fonts magnified 1.2 times.

           Default: false

       texComments => true | false
           If this option is NOT used then the characters {, } and \ found in comments are
           replaced by [, ] and /, since TeX roman fonts do not have these characters. If this
           option is used, these substitutions are not made, so you can embed TeX source (like
           {\bf change fonts}) directly inside the comments.

       gap => number of points
           The gap in points between diagrams.

           Default: 12

   Interactions between options
       If coords and twoColumn are both true, Dg2TeX warns and turns off coords.  If longComments
       and simple are both true, warns and turns off longComments.  If longComments and twoColumn
       are both true, warns and turns off longComments.  Finally, if twoColumn is true, turns
       simple on (no warning).

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

       $dg2tex->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.

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

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

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

       my $tex = $dg2tex->TeXifyText ($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.  TeXifyText behavior is
           modified by texComments and simple options.

           Returns the converted text.

       $tex_title = $dg2tex->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.

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

SEE ALSO

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

BUGS

       Nah.  At least, I don't think so.  Well, I hope not.

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.