.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Games::Go::Sgf2Dg::Dg2Mp 3pm"
.TH Games::Go::Sgf2Dg::Dg2Mp 3pm "2019-10-27" "perl v5.30.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Games::Go::Sgf2Dg::Dg2Mp \- Perl extension to convert Games::Go::Sgf2Dg::Diagrams to
John Hobby's MetaPost (which is adapted from Donald Knuth's
Metafont).
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
use Games::Go::Sgf2Dg::Dg2Mp
.PP
.Vb 2
\& my $dg2mp = B<Games::Go::Sgf2Dg::Dg2Mp\-E<gt>new> (options);
\& $dg2mp\->convertDiagram($diagram);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A Games::Go::Sgf2Dg::Dg2Mp object converts a Games::Go::Sgf2Dg::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.
.PP
See 'man mpost' (or possibly 'man 'mp') for more details of the
overall MetaPost system and environment.
.SH "NEW"
.IX Header "NEW"
.ie n .IP "my $dg2mp = \fBGames::Go::Sgf2Dg::Dg2Mp\->new\fR (?options?)" 4
.el .IP "my \f(CW$dg2mp\fR = \fBGames::Go::Sgf2Dg::Dg2Mp\->new\fR (?options?)" 4
.IX Item "my $dg2mp = Games::Go::Sgf2Dg::Dg2Mp->new (?options?)"
A \fBnew\fR Games::Go::Sgf2Dg::Dg2Mp takes the following options:
.IP "\fBboardSizeX\fR => number" 8
.IX Item "boardSizeX => number"
.PD 0
.IP "\fBboardSizeY\fR => number" 8
.IX Item "boardSizeY => number"
.PD
Sets the size of the board.
.Sp
Default: 19
.IP "\fBdoubleDigits\fR => true | false" 8
.IX Item "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.
.Sp
Default: false
.IP "\fBstone_width\fR => points" 8
.IX Item "stone_width => points"
.PD 0
.IP "\fBstone_height\fR => points" 8
.IX Item "stone_height => points"
.PD
The \fBstone_width\fR and \fBstone_height\fR determine the size of the
stones and diagrams.
.Sp
If \fBstone_width\fR is not explicitly set, it is calculated from the
\&\fBstone_fontSize\fR to allow up to three digits on a stone .  The
default \fBstone_fontSize\fR allows for three diagrams (with \-coords)
per 'letter' page if comments don't take up extra space below
diagrams.  If \fBdoubleDigits\fR is specified, the stones and board are
slightly smaller (stone 100 may look a bit cramped).
.Sp
If \fBstone_height\fR is not explicitly set, it will be 1.05 *
\&\fBstone_width\fR, creating a slightly rectangular diagram.
.Sp
Default: undef \- determined from \fBstone_fontSize\fR
.IP "\fBcoords\fR => true | false" 8
.IX Item "coords => true | false"
Generates a coordinate grid.
.Sp
Default: false
.IP "\fBtopLine\fR     => number (Default: 1)" 8
.IX Item "topLine => number (Default: 1)"
.PD 0
.IP "\fBbottomLine\fR  => number (Default: 19)" 8
.IX Item "bottomLine => number (Default: 19)"
.IP "\fBleftLine\fR    => number (Default: 1)" 8
.IX Item "leftLine => number (Default: 1)"
.IP "\fBrightLine\fR   => number (Default: 19)" 8
.IX Item "rightLine => number (Default: 19)"
.PD
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.
.ie n .IP "\fBdiaCoords\fR => sub { # convert $x, $y to Diagram coordinates }" 8
.el .IP "\fBdiaCoords\fR => sub { # convert \f(CW$x\fR, \f(CW$y\fR to Diagram coordinates }" 8
.IX Item "diaCoords => sub { # convert $x, $y to Diagram coordinates }"
This callback defines a subroutine to convert coordinates from \f(CW$x\fR,
\&\f(CW$y\fR to whatever coordinates are used in the Games::Go::Sgf2Dg::Diagram
object.  The default \fBdiaCoords\fR converts 1\-based \f(CW$x\fR, \f(CW$y\fR to the
same coordinates used in \s-1SGF\s0 format files.  You only need to define
this if you're using a different coordinate system in the Diagram.
.Sp
Default:
.Sp
.Vb 4
\&    sub { my ($x, $y) = @_;
\&          $x = chr($x \- 1 + ord(\*(Aqa\*(Aq)); # convert 1 to \*(Aqa\*(Aq, etc
\&          $y = chr($y \- 1 + ord(\*(Aqa\*(Aq));
\&          return("$x$y"); },           # concatenate two letters
.Ve
.Sp
See also the \fBdiaCoords\fR method below.
.ie n .IP "\fBprint\fR => sub { my ($dg2mp, @tex) = @_; ... }" 8
.el .IP "\fBprint\fR => sub { my ($dg2mp, \f(CW@tex\fR) = \f(CW@_\fR; ... }" 8
.IX Item "print => sub { my ($dg2mp, @tex) = @_; ... }"
A user defined subroutine to replace the default printing method.
This callback is called from the \fBprint\fR method (below) with the
reference to the \fBDg2Mp\fR object and a list of lines that are
part of the TeX diagram source.
.IP "\fBstone_fontName\fR => 'font'  Default: 'cmssbx10'" 8
.IX Item "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):
.Sp
\&\*(L"...the new font name should be something that \s-1TEX\s0 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 \s-1TEX\s0 font such as cmr10 is a little
dangerous because it does not have a space character or certain
\&\s-1ASCII\s0 symbols. In addition, MetaPost does not use the ligatures and
kerning information that comes with a \s-1TEX\s0 font.\*(R"
.IP "\fBstone_fontSize\fR => points" 8
.IX Item "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.
.Sp
If \fBdoubleDigits\fR is specified, the stones and board are slightly
smaller (stone 100 may look a bit cramped).
.Sp
Default: 8
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "$dg2mp\->\fBconfigure\fR (option => value, ?...?)" 4
.el .IP "\f(CW$dg2mp\fR\->\fBconfigure\fR (option => value, ?...?)" 4
.IX Item "$dg2mp->configure (option => value, ?...?)"
Change Dg2Mp options from values passed at \fBnew\fR time.
.ie n .IP "my $coord = $dg2mp\->\fBdiaCoords\fR ($x, $y)" 4
.el .IP "my \f(CW$coord\fR = \f(CW$dg2mp\fR\->\fBdiaCoords\fR ($x, \f(CW$y\fR)" 4
.IX Item "my $coord = $dg2mp->diaCoords ($x, $y)"
Provides access to the \fBdiaCoords\fR option (see above).  Returns
coordinates in the converter's coordinate system for board coordinates ($x,
\&\f(CW$y\fR).  For example, to get a specific intersection structure:
.Sp
.Vb 1
\&    my $int = $diagram\->get($dg2mp\->diaCoords(3, 4));
.Ve
.ie n .IP "$dg2mp\->\fBprint\fR ($tex ? , ... ?)" 4
.el .IP "\f(CW$dg2mp\fR\->\fBprint\fR ($tex ? , ... ?)" 4
.IX Item "$dg2mp->print ($tex ? , ... ?)"
\&\fBprint\fRs raw TeX code to \fBfile\fR as defined at \fBnew\fR time.
Whether or not \fBfile\fR was defined, \fBprint\fR accumulates the TeX
code for later retrieval with \fBconverted\fR.
The TeX output filename is derived from the MetaPost filename by
changing the .mp extension to .tex.
.ie n .IP "$dg2mp\->\fBprint\fR ($tex ? , ... ?)" 4
.el .IP "\f(CW$dg2mp\fR\->\fBprint\fR ($tex ? , ... ?)" 4
.IX Item "$dg2mp->print ($tex ? , ... ?)"
\&\fBprint\fRs raw MetaPost code to MetaPost output file (as defined at
\&\->\fBnew\fR or \->\fBconfigure\fR time).
.ie n .IP "my $tex = $dg2mp\->\fBconverted\fR ($replacement_tex)" 4
.el .IP "my \f(CW$tex\fR = \f(CW$dg2mp\fR\->\fBconverted\fR ($replacement_tex)" 4
.IX Item "my $tex = $dg2mp->converted ($replacement_tex)"
Returns the TeX source code converted so far for the \fBDg2Mp\fR
object.  If \f(CW$replacement_tex\fR is defined, the accumulated TeX source
code is replaced by \f(CW$replacement_tex\fR.
.ie n .IP "$dg2mp\->\fBcomment\fR ($comment ? , ... ?)" 4
.el .IP "\f(CW$dg2mp\fR\->\fBcomment\fR ($comment ? , ... ?)" 4
.IX Item "$dg2mp->comment ($comment ? , ... ?)"
Inserts the TeX comment character ('%') in front of each line of
each comment and \fBprint\fRs it to \fBfile\fR.
.ie n .IP "my $tex_source = $dg2mp\->\fBconvertDiagram\fR ($diagram)" 4
.el .IP "my \f(CW$tex_source\fR = \f(CW$dg2mp\fR\->\fBconvertDiagram\fR ($diagram)" 4
.IX Item "my $tex_source = $dg2mp->convertDiagram ($diagram)"
Converts a \fIGames::Go::Sgf2Dg::Diagram\fR into TeX/MetaPost.  If \fBfile\fR was
defined in the \fBnew\fR method, the TeX source is dumped into the
\&\fBfile\fR.tex and the MetaPost source into \fBfile\fR.mp.  In any case,
the TeX source is returned as a string scalar.
.ie n .IP "my $tex = $dg2mp\->\fBconvertText\fR ($text)" 4
.el .IP "my \f(CW$tex\fR = \f(CW$dg2mp\fR\->\fBconvertText\fR ($text)" 4
.IX Item "my $tex = $dg2mp->convertText ($text)"
Converts \f(CW$text\fR into TeX code by changing certain characters that are
not available in TeX cmr10 font, and by converting \en\en into
\&\ehfil\ebreak.  \fBconvertText\fR behavior is modified by \fBtexComments\fR
and \fBsimple\fR options.
.Sp
Returns the converted text.
.ie n .IP "$dg2mp\->\fBclose\fR" 4
.el .IP "\f(CW$dg2mp\fR\->\fBclose\fR" 4
.IX Item "$dg2mp->close"
\&\fBprint\fR the TeX closer (\ebye) and close the dg2mp object.  Also
closes \fBfile\fR if appropriate.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "sgf2dg(1)" 4
.IX Item "sgf2dg(1)"
Script to convert \s-1SGF\s0 format files to Go diagrams
.SH "BUGS"
.IX Header "BUGS"
Is this a trick question?