.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" 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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Dg2TeX 3pm"
.TH Dg2TeX 3pm "2009-11-01" "perl v5.24.1" "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::Dg2TeX \- Perl extension to convert Games::Go::Diagrams to TeX
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
use Games::Go::Dg2TeX
.PP
.Vb 2
\& my $dg2tex = B<Games::Go::Dg2TeX\-E<gt>new> (options);
\& my $tex = $gd2tex\->convertDiagram($diagram);
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "my $dg2tex = \fBGames::Go::Dg2TeX\->new\fR (?options?)" 4
.el .IP "my \f(CW$dg2tex\fR = \fBGames::Go::Dg2TeX\->new\fR (?options?)" 4
.IX Item "my $dg2tex = Games::Go::Dg2TeX->new (?options?)"
A \fBnew\fR Games::Go::D2TeX takes the following options:
.SS "General Dg2 Converter Options:"
.IX Subsection "General Dg2 Converter Options:"
.IP "\fBboardSize\fR => number" 4
.IX Item "boardSize => number"
Sets the size of the board.
.Sp
Default: 19
.IP "\fBdoubleDigits\fR => true | false" 4
.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 "\fBtopLine\fR     => number (Default: 1)" 4
.IX Item "topLine => number (Default: 1)"
.PD 0
.IP "\fBbottomLine\fR  => number (Default: 19)" 4
.IX Item "bottomLine => number (Default: 19)"
.IP "\fBleftLine\fR    => number (Default: 1)" 4
.IX Item "leftLine => number (Default: 1)"
.IP "\fBrightLine\fR   => number (Default: 19)" 4
.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 Games::Go::Diagram coordinates }" 4
.el .IP "\fBdiaCoords\fR => sub { # convert \f(CW$x\fR, \f(CW$y\fR to Games::Go::Diagram coordinates }" 4
.IX Item "diaCoords => sub { # convert $x, $y to Games::Go::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::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:
    sub { my ($x, \f(CW$y\fR) = \f(CW@_\fR;
          \f(CW$x\fR = chr($x \- 1 + ord('a')); # convert 1 to 'a', etc
          \f(CW$y\fR = chr($y \- 1 + ord('a'));
          return(\*(L"$x$y\*(R"); },           # concatenate two letters
.ie n .IP "\fBfile\fR => 'filename' | $descriptor | \e$string | \e@array" 4
.el .IP "\fBfile\fR => 'filename' | \f(CW$descriptor\fR | \e$string | \e@array" 4
.IX Item "file => 'filename' | $descriptor | $string | @array"
If \fBfile\fR is defined, the TeX source is dumped into the target.
The target can be any of:
.RS 4
.IP "filename" 4
.IX Item "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.
.IP "descriptor" 4
.IX Item "descriptor"
A file descriptor as returned by IO::File\->new, or a \e*FILE
descriptor.  TeX source is written into the file.
.IP "reference to a string scalar" 4
.IX Item "reference to a string scalar"
TeX source is concatenated to the end of the string.
.IP "reference to an array" 4
.IX Item "reference to an array"
TeX source is split on \*(L"\en\*(R" and each line is pushed onto the array.
.RE
.RS 4
.Sp
Default: undef
.RE
.ie n .IP "\fBprint\fR => sub { my ($dg2tex, @tex) = @_; ... }" 4
.el .IP "\fBprint\fR => sub { my ($dg2tex, \f(CW@tex\fR) = \f(CW@_\fR; ... }" 4
.IX Item "print => sub { my ($dg2tex, @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 \fBDg2TeX\fR object and a list of lines that are
part of the TeX diagram source.
.SS "Dg2TeX\-specific options"
.IX Subsection "Dg2TeX-specific options"
.IP "\fBlongComments\fR => true | false" 4
.IX Item "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 \fB\-simple\fR or \fB\-longComments\fR.
.Sp
Default: true
.IP "\fBsimple\fR => true | false" 4
.IX Item "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 \fB\-longComments\fR.
.Sp
Default: false
.IP "\fBtwoColumn\fR => true | false" 4
.IX Item "twoColumn => true | false"
This generates a two-column format using smaller fonts. This
option forces \fBsimple\fR true, and it may not be used with
\&\fB\-longComments\fR or \fB\-coords\fR.
.Sp
Default: false
.IP "\fBcoords\fR => true | false" 4
.IX Item "coords => true | false"
Generates a coordinate grid. This option may not be used with \fB\-twoColumn\fR.
.Sp
Default: false
.IP "\fBbigFonts\fR => true | false" 4
.IX Item "bigFonts => true | false"
Use fonts magnified 1.2 times.
.Sp
Default: false
.IP "\fBtexComments\fR => true | false" 4
.IX Item "texComments => true | false"
If this option is \s-1NOT\s0 used then the characters {, } and \e 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 {\ebf change fonts}) directly inside the comments.
.IP "\fBgap\fR => number of points" 4
.IX Item "gap => number of points"
The \fBgap\fR in points between diagrams.
.Sp
Default: 12
.SS "Interactions between options"
.IX Subsection "Interactions between options"
If \fBcoords\fR and \fBtwoColumn\fR are both true, Dg2TeX warns and
turns off \fBcoords\fR.  If \fBlongComments\fR and \fBsimple\fR are both
true, warns and turns off \fBlongComments\fR.  If \fBlongComments\fR
and \fBtwoColumn\fR are both true, warns and turns off
\&\fBlongComments\fR.  Finally, if \fBtwoColumn\fR is true, turns
\&\fBsimple\fR on (no warning).
.ie n .IP "$dg2tex\->\fBconfigure\fR (option => value, ?...?)" 4
.el .IP "\f(CW$dg2tex\fR\->\fBconfigure\fR (option => value, ?...?)" 4
.IX Item "$dg2tex->configure (option => value, ?...?)"
Change Dg2TeX options from values passed at \fBnew\fR time.
.ie n .IP "$dg2tex\->\fBprint\fR ($tex ? , ... ?)" 4
.el .IP "\f(CW$dg2tex\fR\->\fBprint\fR ($tex ? , ... ?)" 4
.IX Item "$dg2tex->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.
.ie n .IP "my $tex = $dg2tex\->\fBconverted\fR ($replacement_tex)" 4
.el .IP "my \f(CW$tex\fR = \f(CW$dg2tex\fR\->\fBconverted\fR ($replacement_tex)" 4
.IX Item "my $tex = $dg2tex->converted ($replacement_tex)"
Returns the TeX source code converted so far for the \fBDg2TeX\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 "$dg2tex\->\fBcomment\fR ($comment ? , ... ?)" 4
.el .IP "\f(CW$dg2tex\fR\->\fBcomment\fR ($comment ? , ... ?)" 4
.IX Item "$dg2tex->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 = $dg2tex\->\fBconvertDiagram\fR ($diagram)" 4
.el .IP "my \f(CW$tex_source\fR = \f(CW$dg2tex\fR\->\fBconvertDiagram\fR ($diagram)" 4
.IX Item "my $tex_source = $dg2tex->convertDiagram ($diagram)"
Converts a \fIGames::Go::Diagram\fR into TeX.  If \fBfile\fR was defined
in the \fBnew\fR method, the TeX source is dumped into the \fBfile\fR.
In any case, the TeX source is returned as a string scalar.
.ie n .IP "my $tex = $dg2tex\->\fBTeXifyText\fR ($text)" 4
.el .IP "my \f(CW$tex\fR = \f(CW$dg2tex\fR\->\fBTeXifyText\fR ($text)" 4
.IX Item "my $tex = $dg2tex->TeXifyText ($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.  \fBTeXifyText\fR behavior is modified by \fBtexComments\fR
and \fBsimple\fR options.
.Sp
Returns the converted text.
.ie n .IP "$tex_title = $dg2tex\->\fBconvertProperties\fR (\e%sgfHash)" 4
.el .IP "\f(CW$tex_title\fR = \f(CW$dg2tex\fR\->\fBconvertProperties\fR (\e%sgfHash)" 4
.IX Item "$tex_title = $dg2tex->convertProperties (%sgfHash)"
\&\fBconvertProperties\fR takes a reference to a hash of properties as
extracted from an \s-1SGF\s0 file.  Each hash key is a property \s-1ID\s0 and the
hash value is a reference to an array of property values:
\&\f(CW$hash\fR\->{propertyId}\->[values].  The following \s-1SGF\s0 properties are
recognized:
.RS 4
.IP "\s-1GN\s0 GameName" 4
.IX Item "GN GameName"
.PD 0
.IP "\s-1EV\s0 EVent" 4
.IX Item "EV EVent"
.IP "\s-1RO\s0 ROund" 4
.IX Item "RO ROund"
.IP "\s-1PW\s0 PlayerWhite" 4
.IX Item "PW PlayerWhite"
.IP "\s-1WR\s0 WhiteRank" 4
.IX Item "WR WhiteRank"
.IP "\s-1PB\s0 PlayerBlack" 4
.IX Item "PB PlayerBlack"
.IP "\s-1BR\s0 BlackRank" 4
.IX Item "BR BlackRank"
.IP "\s-1DT\s0 DaTe" 4
.IX Item "DT DaTe"
.IP "\s-1PC\s0 PlaCe" 4
.IX Item "PC PlaCe"
.IP "\s-1GC\s0 GameComment" 4
.IX Item "GC GameComment"
.IP "\s-1KM\s0 KoMi" 4
.IX Item "KM KoMi"
.IP "\s-1RE\s0 REsult" 4
.IX Item "RE REsult"
.IP "\s-1TM\s0 TiMe" 4
.IX Item "TM TiMe"
.RE
.RS 4
.PD
.Sp
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.
.RE
.ie n .IP "$dg2tex\->\fBclose\fR" 4
.el .IP "\f(CW$dg2tex\fR\->\fBclose\fR" 4
.IX Item "$dg2tex->close"
\&\fBprint\fR the TeX closer (\ebye) and close the dg2tex 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"
Nah.  At least, I don't think so.  Well, I hope not.
.SH "AUTHOR"
.IX Header "AUTHOR"
Reid Augustin, <reid@hellosix.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2005 by Reid Augustin
.PP
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.