* src/preproc/pic/pic.man: Add info on conversion of pic images to

other graphic formats.

2 files changed, 143 insertions, 17 deletions

diff --git a/ChangeLog b/ChangeLog
index 4fa48b30..3ab86b7b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2000-03-08  Bernd Warken  <bwarken@mayn.de>
+
+	* src/preproc/pic/pic.man: Add info on conversion of pic images to
+	other graphic formats.
+
 2000-03-07  OKAZAKI Tetsurou  <okazaki@be.to>
 
 	* Makefile.in, contrib/mm/Makefile.sub, src/preproc/eqn/Makefile.sub,
diff --git a/src/preproc/pic/pic.man b/src/preproc/pic/pic.man
index 22481019..2b09fe78 100644
--- a/src/preproc/pic/pic.man
+++ b/src/preproc/pic/pic.man
@@ -52,7 +52,6 @@ the original English.
 \&.\|.\|.
 ]
 .SH DESCRIPTION
-.LP
 This manual page describes the GNU version of
 .BR pic ,
 which is part of the groff document formatting system.
@@ -82,7 +81,6 @@ appropriate definitions can be obtained with
 .BR \-mpic :
 these will center each picture.
 .SH OPTIONS
-.LP
 Options that do not take arguments may be grouped behind a single
 .BR \- .
 The special option
@@ -118,7 +116,8 @@ The extensions are described in
 .BR groff_out (@MAN5EXT@).
 The
 .B \-n
-option also causes pic
+option also causes
+.B pic
 not to use zero-length lines to draw dots in troff mode.
 .TP
 .B \-t
@@ -179,15 +178,20 @@ output generated by
 .B pic
 is device-independent.
 .SH USAGE
-This section describes only the differences between GNU pic and the original
-version of pic.
-Many of these differences also apply to newer versions of Unix pic.
+This section describes only the differences between GNU
+.B pic
+and the original version of
+.BR pic .
+Many of these differences also apply to newer versions of Unix
+.BR pic .
 .SS \*(tx mode
 .LP
 \*(tx mode is enabled by the
 .B \-t
 option.
-In \*(tx mode, pic will define a vbox called
+In \*(tx mode,
+.B pic
+will define a vbox called
 .B \egraph
 for each picture.
 You must yourself print that vbox using, for example, the command
@@ -404,7 +408,8 @@ is used.
 Attributes can be specified in the same way as for a normal text
 object.
 Be very careful that you specify an appropriate format string;
-pic does only very limited checking of the string.
+.B pic
+does only very limited checking of the string.
 This is deprecated in favour of
 .BR sprintf .
 .TP
@@ -580,13 +585,15 @@ line can have a second argument specifying a maximum height for
 the picture.
 If the width of zero is specified the width will be ignored in computing
 the scaling factor for the picture.
-Note that GNU pic will always scale a picture by the same amount
-vertically as horizontally.
+Note that GNU
+.B pic
+will always scale a picture by the same amount vertically as horizontally.
 This is different from the
 .SM DWB
-2.0 pic which may scale a picture by a
-different amount vertically than horizontally if a height is
-specified.
+2.0
+.B pic
+which may scale a picture by a different amount vertically than
+horizontally if a height is specified.
 .LP
 Each text object has an invisible box associated with it.
 The compass points of a text object are determined by this box.
@@ -687,7 +694,9 @@ Initially
 .B arrowhead
 has a value of 1.
 .LP
-The troff output of pic is device-independent.
+The troff output of
+.B pic
+is device-independent.
 The
 .B \-T
 option is therefore redundant.
@@ -726,6 +735,98 @@ for i = 1 to 4 do {
    line from `i'th box.nw to `i+1'th box.se
 }
 .fi
+.SH CONVERSION
+To obtain a stand-alone picture from a
+.B pic
+file, enclose your
+.B pic
+code with
+.B .PS
+and
+.B .PE
+requests;
+.B roff
+configuration commands may be added at the beginning of the file, but no
+.B roff
+text.
+.LP
+It is necessary to feed this file into
+.B groff
+without adding any page information, so you must check which
+.B .PS
+and
+.B .PE
+requests are actually called.
+For example, the mm macro package adds a page number, which is very
+annoying.
+At the moment, calling standard
+.B groff
+without any macro package works.
+Alternatively, you can define your own requests, e.g. to do nothing:
+.LP
+.RS
+.nf
+.ft B
+\&.de PS
+\&..
+\&.de PE
+\&..
+.ft
+.fi
+.RE
+.LP
+.B groff
+itself does not provide direct conversion into other graphics file
+formats.
+But there are lots of possibilities if you first transform your picture
+into PostScript\*R format using the
+.B groff
+option
+.BR -Tps .
+Since this
+.IR ps -file
+lacks BoundingBox information it is not very useful by itself, but it
+may be fed into other conversion programs, usually named
+.BI ps2 other
+or
+.BI psto other
+or the like.
+Moreover, the PostScript interpreter
+.B ghostscript
+.RB ( gs )
+has built-in graphics conversion devices that are called with the option
+.LP
+.RS
+.BI "gs -sDEVICE=" <devname>
+.RE
+.LP
+Call
+.RS
+.B gs --help
+.RE
+.LP
+for a list of the available devices.
+.LP
+As the Encapsulated PostScript File Format
+.B EPS
+is getting more and more important, and the conversion wasn't regarded
+trivial in the past you might be interested to know that there is a
+conversion tool named
+.B ps2eps
+which does the right job.
+It is much better than the tool
+.B ps2epsi
+packaged with
+.BR gs .
+.LP
+For bitmapped graphic formats, you should use
+.BR pstopnm ;
+the resulting (intermediate)
+.B PNM
+file can be then converted to virtually any graphics format using the tools
+of the
+.B netpbm
+package .
 .SH FILES
 .Tp \w'\fB@MACRODIR@/tmac.pic'u+3n
 .B
@@ -738,15 +839,33 @@ macros.
 .SH "SEE ALSO"
 .BR @g@troff (@MAN1EXT@),
 .BR groff_out (@MAN5EXT@),
-.BR tex (1)
-.br
+.BR tex (1),
+.BR gs (1),
+.BR ps2eps (1),
+.BR pstopnm (1),
+.BR ps2epsi (1),
+.BR pnm (5)
+.LP
 Tpic: Pic for \*(tx
-.br
+.LP
 Brian W. Kernighan,
 PIC \(em A Graphics Language for Typesetting (User Manual).
 AT&T Bell Laboratories, Computing Science Technical Report No.\ 116
 <URL:http://cm.bell-labs.com/cm/cs/cstr/116.ps.gz>
 (revised May, 1991).
+.LP
+.B ps2eps
+is available from CTAN mirrors, e.g.
+.br
+<ftp://ftp.dante.de/tex-archive/support/ps2eps/>
+.LP
+W. Richard Stevens - Turning PIC Into HTML
+.br
+<http://www.kohala.com/start/troff/pic2html.html>
+.LP
+W. Richard Stevens - Examples of picMacros
+.br
+<http://www.kohala.com/start/troff/pic.examples.ps>
 .SH BUGS
 .LP
 Input characters that are illegal for
@@ -760,3 +879,5 @@ The interpretation of
 .B fillval
 is incompatible with the pic in 10th edition Unix,
 which interprets 0 as black and 1 as white.
+.LP
+PostScript\*R is a registered trademark of Adobe Systems Incorporation.