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
   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.  The language is sufficiently flexible
  33 to be quite useful for state charts, Petri-net diagrams, flow charts,
  34 simple circuit schematics, jumper layouts, and other kinds of
  35 illustration involving repetitive uses of simple geometric forms and
  36 splines.  Because PIC descriptions are procedural and object-based,
  37 they are both compact and easy to modify.
  38 .P
  39 The PIC language is fully documented in "\fIMaking Pictures With GNU
  40 PIC\fP", a document which is part of the
  41 .BR groff (@MAN1EXT@)
  42 distribution.
  43 .P
  44 Your input PIC code should \fInot\fR be wrapped with the .PS and .PE macros
  45 that normally guard it within
  46 .BR groff (@MAN1EXT@)
  47 macros.
  48 .P
  49 The output image will be a black-on-white graphic clipped to the
  50 smallest possible bounding box that contains all the black pixels.
  51 By specifying command-line options to be passed to
  52 .BR convert (1)
  53 you can give it a border, set the background transparent, set the
  54 image's pixel density, or perform other useful transformations.
  55 .P
  56 This program uses
  57 .BR @g@pic (@MAN1EXT@),
  58 .BR @g@eqn (@MAN1EXT@),
  59 .BR groff (@MAN1EXT@),
  60 .BR gs (1),
  61 and the ImageMagick
  62 .BR convert (1)
  63 program.
  64 These 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
  71 Run
  72 .BR @g@pic (@MAN1EXT@)
  73 and
  74 .BR groff (@MAN1EXT@)
  75 in the `unsafe' mode enabling the PIC macro
  76 .B sh
  77 to execute arbitrary commands.  The default is to forbid this.
  78 .TP
  79 .BI \-format\  fmt
  80 Specify an output format; the default is PNG (Portable Network Graphics).
  81 Any format that
  82 .BR convert (1)
  83 can emit is supported.
  84 .TP
  85 .BI \-eqn\  delim
  86 Change the fencepost characters that delimit
  87 .BR @g@eqn (@MAN1EXT@)
  88 directives
  89 .RB ( $
  90 and
  91 .BR $ ,
  92 by default).  This option requires an argument, but an empty string is
  93 accepted as a directive to disable
  94 .BR @g@eqn (@MAN1EXT@)
  95 processing.
  96 .PP
  97 Command-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
 104 The
 105 .BR @g@eqn (@MAN1EXT@)
 106 initialization file.
 107 .
 108 .
 109 .SH ENVIRONMENT
 110 .TP
 111 .B GROFF_TMPDIR
 112 The directory in which temporary files will be created.
 113 If this is not set
 114 .B pic2graph
 115 searches the environment variables
 116 .BR \%TMPDIR ,
 117 .BR TMP ,
 118 and
 119 .B TEMP
 120 (in that order).
 121 Otherwise, 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
 136 Eric S. Raymond <esr@thyrsus.com>, based on a recipe by W. Richard Stevens.
 137 .
 138 .\" Local Variables:
 139 .\" mode: nroff
 140 .\" End: