multipage_hp2ps
[ghc.git] / utils / hp2ps / hp2ps.1
1 .\" man page for hp2ps
2 .ds PS P\s-2OST\s+2S\s-2CRIPT\s+2
3 .\" typeset examples in fixed size font as indented paragraph
4 .de Ex
5 .sp
6 .RS
7 .nf
8 .ft C
9 ..
10 .de Xe
11 .RE
12 .sp
13 .fi
14 ..
15 .TH HP2PS 1 "18 April 1992" 
16 .SH NAME
17 hp2ps \- convert a heap profile to a \*(PS graph
18 .SH SYNOPSIS
19 .B hp2ps
20 [flags] [file][.hp] 
21 .SH DESCRIPTION
22 The program
23 .B hp2ps
24 converts a heap profile stored in
25 .IR file
26 into a \*(PS graph, sending the result to
27 .IR file.ps.
28 By convention, files to be processed by 
29 .B hp2ps
30 have a 
31 .I .hp
32 extension. However, for compatibility with older versions of
33 .B hp2ps, 
34 this extension can be omitted. If 
35 .IR file
36 is omitted entirely, then the program behaves as a filter.
37 .SH OPTIONS
38 The flags are:
39 .IP "\fB\-d\fP"
40 In order to make graphs more readable,
41 .B hp2ps
42 sorts the shaded bands for each identifier. The default sort ordering is for
43 the bands with the largest area to be stacked on top of the smaller ones.
44 The
45 .B \-d
46 option causes rougher bands (those reprsenting series of values with the
47 largest standard deviations) to be stacked on top of smoother ones.
48 .IP "\fB\-b\fP"
49 Normally,
50 .B hp2ps
51 puts the title of the graph in a small box at the top of the page. However, 
52 if the JOB string is too long to fit in a small box (more than 35 characters), 
53 then
54 .B hp2ps
55 will choose to use a big box instead. The
56 .B \-b
57 option forces
58 .B hp2ps
59 to use a big box.
60 .IP "\fB\-e\fP \fIfloat\fP[in|mm|pt]"
61 Generate encapsulated \*(PS suitable for inclusion in LaTeX documents.
62 Usually, the \*(PS graph is drawn in landscape mode in an area 
63 9 inches wide by 6 inches high, and
64 .B hp2ps
65 arranges for this area to be approximately centered on a sheet of a4
66 paper. This format is convenient of studying the graph in detail, but
67 it is unsuitable for inclusion in LaTeX documents. The 
68 .B \-e 
69 option causes the graph to be drawn in portrait mode, with 
70 .I float
71 specifying the width in inches, millimetres or points (the default).
72 The resulting \*(PS file conforms to the  
73 .I "Encapsulated Post Script"
74 (EPS) convention, and it can be included in a LaTeX document using Rokicki's 
75 dvi-to-\*(PS converter
76 .B dvips.
77 .B hp2ps
78 requires the width to exceed 2 inches.
79 .IP "\fB\-g\fP" 
80 Create output suitable for the
81 .B gs
82 \*(PS previewer (or similar). In this case the graph is printed in portrait
83 mode without scaling. The output is unsuitable for a laser printer.
84 .IP "\fB\-p\fP"
85 Use previous parameters. By default, the \*(PS graph is automatically
86 scaled both horizontally and vertically so that it fills the page.
87 However, when preparing a seires of graphs for use in a presentation, 
88 it is often useful to draw a new graph using the same scale, shading and
89 ordering as a previous one. The
90 .B \-p
91 flag causes the graph to be drawn using the parameters determined by
92 a previous run of 
93 .B hp2ps
94 on
95 .IR file.  
96 .IP "\fB\-s\fP"
97 Use a small box for the title.
98 .IP "\fB\-y\fP"
99 Draw the graph in the traditional York style, ignoring marks.
100 .IP "\fB\-?\fP"
101 Print out usage information. 
102 .SH "INPUT FORMAT"
103 The format of a heap profile is best described by example:
104 .Ex
105 JOB "a.out -p"
106 DATE "Fri Apr 17 11:43:45 1992"
107 SAMPLE_UNIT "seconds"
108 VALUE_UNIT "bytes"
109 BEGIN_SAMPLE 0.00
110   SYSTEM 24
111 END_SAMPLE 0.00
112 BEGIN_SAMPLE 1.00
113   elim 180
114   insert 24
115   intersect 12
116   disin 60
117   main 12
118   reduce 20
119   SYSTEM 12
120 END_SAMPLE 1.00
121 MARK 1.50
122 MARK 1.75
123 MARK 1.80
124 BEGIN_SAMPLE 2.00
125   elim 192
126   insert 24
127   intersect 12
128   disin 84
129   main 12
130   SYSTEM 24
131 END_SAMPLE 2.00
132 BEGIN_SAMPLE 2.82 
133 END_SAMPLE 2.82 
134
135 .Xe
136 .SH "SEE ALSO"
137 dvips(1), latex(1), hbchp (1), lmlchp(1)
138 .br
139 C. Runciman and D. Wakeling,
140 .I
141 Heap Profiling for Lazy Functional Languages, YCS-172, University of York, 1992
142 .SH NOTES
143 \*(PS is a registered trademark of Adobe Systems Incorporated.
144 .SH AUTHOR
145 David Wakeling of the University of York.