contrib/groff/contrib/pic2graph/pic2graph.man

   1 .\" $Id: pic2graph.man,v 1.7 2008/09/29 21:55:15 wl Exp $
   2 .\" This documentation is released to the public domain.
   3 .TH PIC2GRAPH @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
   4 .IX pic2graph
   5 .SH NAME
   6 pic2graph \- 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
  23 Reads a PIC program as input; produces an image file (by default in
  24 Portable Network Graphics format) suitable for the Web as output.
  25 Also translates
  26 .BR @g@eqn (@MAN1EXT@)
  27 constructs, so it can be used for generating images of mathematical
  28 formulae.
  29 .P
  30 PIC is a rather expressive graphics minilanguage suitable for
  31 producing box-and-arrow diagrams of the kind frequently used in
  32 technical papers and textbooks.
  33 The language is sufficiently flexible to be quite useful for state
  34 charts, Petri-net diagrams, flow charts, simple circuit schematics,
  35 jumper layouts, and other kinds of illustration involving repetitive
  36 uses of simple geometric forms and splines.
  37 Because PIC descriptions are procedural and object-based, they are
  38 both compact and easy to modify.
  39 .P
  40 The PIC language is fully documented in
  41 .IR "Making Pictures With GNU PIC" ,
  42 a document which is part of the
  43 .BR groff (@MAN1EXT@)
  44 distribution.
  45 .P
  46 Your input PIC code should
  47 .I not
  48 be wrapped with the \&.PS and \&.PE macros that normally guard it within
  49 .BR groff (@MAN1EXT@)
  50 macros.
  51 .P
  52 The output image will be clipped to the smallest possible bounding box
  53 that contains all the black pixels.
  54 Older versions of
  55 .BR \%convert (1)
  56 will produce a black-on-white graphic; newer ones may produce a
  57 black-on-transparent graphic.
  58 By specifying command-line options to be passed to
  59 .BR \%convert (1)
  60 you can give it a border, force the background transparent, set the
  61 image's pixel density, or perform other useful transformations.
  62 .P
  63 This program uses
  64 .BR @g@pic (@MAN1EXT@),
  65 .BR @g@eqn (@MAN1EXT@),
  66 .BR groff (@MAN1EXT@),
  67 .BR gs (1),
  68 and the ImageMagick
  69 .BR \%convert (1)
  70 program.
  71 These programs must be installed on your system and accessible on your
  72 $PATH for
  73 .B pic2graph
  74 to work.
  75 .
  76 .
  77 .SH OPTIONS
  78 .TP
  79 .B \-unsafe
  80 Run
  81 .BR @g@pic (@MAN1EXT@)
  82 and
  83 .BR groff (@MAN1EXT@)
  84 in the `unsafe' mode enabling the PIC macro
  85 .B sh
  86 to execute arbitrary commands.
  87 The default is to forbid this.
  88 .TP
  89 .BI \-format\  fmt
  90 Specify an output format; the default is PNG (Portable Network Graphics).
  91 Any format that
  92 .BR \%convert (1)
  93 can emit is supported.
  94 .TP
  95 .BI \-eqn\  delim
  96 Change the fencepost characters that delimit
  97 .BR @g@eqn (@MAN1EXT@)
  98 directives
  99 .RB ( $
 100 and
 101 .BR $ ,
 102 by default).
 103 This option requires an argument, but an empty string is
 104 accepted as a directive to disable
 105 .BR @g@eqn (@MAN1EXT@)
 106 processing.
 107 .PP
 108 Command-line switches and arguments not listed above are passed to
 109 .BR \%convert (1).
 110 .
 111 .
 112 .SH FILES
 113 .TP \w'\fB@MACRODIR@/eqnrc'u+2n
 114 .B @MACRODIR@/eqnrc
 115 The
 116 .BR @g@eqn (@MAN1EXT@)
 117 initialization file.
 118 .
 119 .
 120 .SH ENVIRONMENT
 121 .TP
 122 .B GROFF_TMPDIR
 123 The directory in which temporary files will be created.
 124 If this is not set
 125 .B pic2graph
 126 searches the environment variables
 127 .BR \%TMPDIR ,
 128 .BR TMP ,
 129 and
 130 .B TEMP
 131 (in that order).
 132 Otherwise, temporary files will be created in
 133 .BR /tmp .
 134 .
 135 .
 136 .SH BUGS
 137 Due to changes in the behavior of ImageMagick
 138 .BR \%convert (1)
 139 that are both forward and backward-incompatible,
 140 mismatches between your
 141 .B pic2graph
 142 and
 143 .BR \%convert (1)
 144 versions may produce zero-sized or untrimmed output images.
 145 For this version of
 146 .B pic2graph
 147 you will need a version of
 148 .BR \%convert (1)
 149 that supports the
 150 .B \-trim
 151 option; older versions of
 152 .B pic2graph
 153 used
 154 .BR \-crop\~0x0 ,
 155 which no longer has trimming behavior.
 156 .
 157 .
 158 .SH "SEE ALSO"
 159 .BR eqn2graph (@MAN1EXT@),
 160 .BR grap2graph (@MAN1EXT@),
 161 .BR @g@pic (@MAN1EXT@),
 162 .BR @g@eqn (@MAN1EXT@),
 163 .BR groff (@MAN1EXT@),
 164 .BR gs (1),
 165 .BR \%convert (1).
 166 .
 167 .
 168 .SH AUTHOR
 169 Eric S. Raymond <esr@thyrsus.com>, based on a recipe by W. Richard Stevens.
 170 .
 171 .\" Local Variables:
 172 .\" mode: nroff
 173 .\" End: