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.