/contrib/groff/contrib/pic2graph/pic2graph.man

  1.\" $Id: pic2graph.man,v 1.5 2003/10/28 07:46:24 wlemb Exp $
  2.\" This documentation is released to the public domain.
  3.TH PIC2GRAPH @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
  4.IX pic2graph
  5.SH NAME
  6pic2graph \- convert a PIC diagram into a cropped image
  7.
  8.
  9.SH SYNOPSIS
 10.B pic2graph
 11[
 12.B \-unsafe
 13]
 14[
 15.BI \-format\  fmt
 16]
 17[
 18.BI \-eqn\  delim
 19]
 20.
 21.
 22.SH DESCRIPTION
 23Reads a PIC program as input; produces an image file (by default in
 24Portable Network Graphics format) suitable for the Web as output.
 25Also translates
 26.BR @g@eqn (@MAN1EXT@)
 27constructs, so it can be used for generating images of mathematical
 28formulae.
 29.P
 30PIC is a rather expressive graphics minilanguage suitable for
 31producing box-and-arrow diagrams of the kind frequently used in
 32technical papers and textbooks.  The language is sufficiently flexible
 33to be quite useful for state charts, Petri-net diagrams, flow charts,
 34simple circuit schematics, jumper layouts, and other kinds of
 35illustration involving repetitive uses of simple geometric forms and
 36splines.  Because PIC descriptions are procedural and object-based,
 37they are both compact and easy to modify.
 38.P
 39The PIC language is fully documented in "\fIMaking Pictures With GNU
 40PIC\fP", a document which is part of the
 41.BR groff (@MAN1EXT@)
 42distribution.
 43.P
 44Your input PIC code should \fInot\fR be wrapped with the .PS and .PE macros
 45that normally guard it within 
 46.BR groff (@MAN1EXT@) 
 47macros.
 48.P
 49The output image will be a black-on-white graphic clipped to the
 50smallest possible bounding box that contains all the black pixels.
 51By specifying command-line options to be passed to 
 52.BR convert (1)
 53you can give it a border, set the background transparent, set the
 54image's pixel density, or perform other useful transformations.
 55.P
 56This program uses 
 57.BR @g@pic (@MAN1EXT@),
 58.BR @g@eqn (@MAN1EXT@),
 59.BR groff (@MAN1EXT@),
 60.BR gs (1),
 61and the ImageMagick
 62.BR convert (1)
 63program.
 64These programs must be installed on your system and accessible on your
 65$PATH for \fBpic2graph\fR to work.
 66.
 67.
 68.SH OPTIONS
 69.TP
 70.B \-unsafe
 71Run 
 72.BR @g@pic (@MAN1EXT@)
 73and
 74.BR groff (@MAN1EXT@)
 75in the `unsafe' mode enabling the PIC macro
 76.B sh
 77to execute arbitrary commands.  The default is to forbid this.
 78.TP
 79.BI \-format\  fmt
 80Specify an output format; the default is PNG (Portable Network Graphics).
 81Any format that
 82.BR convert (1)
 83can emit is supported.
 84.TP
 85.BI \-eqn\  delim
 86Change the fencepost characters that delimit 
 87.BR @g@eqn (@MAN1EXT@)
 88directives
 89.RB ( $
 90and
 91.BR $ ,
 92by default).  This option requires an argument, but an empty string is
 93accepted as a directive to disable
 94.BR @g@eqn (@MAN1EXT@)
 95processing.
 96.PP
 97Command-line switches and arguments not listed above are passed to
 98.BR convert (1).
 99.
100.
101.SH FILES
102.TP \w'\fB@MACRODIR@/eqnrc'u+2n
103.B @MACRODIR@/eqnrc
104The 
105.BR @g@eqn (@MAN1EXT@)
106initialization file.
107.
108.
109.SH ENVIRONMENT
110.TP
111.B GROFF_TMPDIR
112The directory in which temporary files will be created.
113If this is not set
114.B pic2graph
115searches the environment variables
116.BR \%TMPDIR ,
117.BR TMP ,
118and
119.B TEMP
120(in that order).
121Otherwise, temporary files will be created in
122.BR /tmp .
123.
124.
125.SH "SEE ALSO"
126.BR eqn2graph (@MAN1EXT@),
127.BR grap2graph (@MAN1EXT@),
128.BR @g@pic (@MAN1EXT@),
129.BR @g@eqn (@MAN1EXT@),
130.BR groff (@MAN1EXT@),
131.BR gs (1),
132.BR convert (1).
133.
134.
135.SH AUTHOR
136Eric S. Raymond <esr@thyrsus.com>, based on a recipe by W. Richard Stevens.
137.
138.\" Local Variables:
139.\" mode: nroff
140.\" End: