xref: /netbsd-src/external/gpl3/binutils/dist/gprofng/doc/gp-display-html.texi (revision cb63e24e8d6aae7ddac1859a9015f48b1d8bd90e)
1*cb63e24eSchristos@c ----------------------------------------------------------------------------
2*cb63e24eSchristos@c This is the Texinfo source file for the gp-display-html man page.
3*cb63e24eSchristos@c
4*cb63e24eSchristos@c Author: Ruud van der Pas
5*cb63e24eSchristos@c ----------------------------------------------------------------------------
6*cb63e24eSchristos@ifset man
7*cb63e24eSchristos\input texinfo @c -*-texinfo-*-
8*cb63e24eSchristos@setfilename gp-display-html
9*cb63e24eSchristos@settitle Generate an HTML based directory structure to browse the profiles
10*cb63e24eSchristos@include gp-macros.texi
11*cb63e24eSchristos@end ifset
12*cb63e24eSchristos
13*cb63e24eSchristos@c ----------------------------------------------------------------------------
14*cb63e24eSchristos@c This is from the man-pages(7) man page
15*cb63e24eSchristos@c
16*cb63e24eSchristos@c "The list below shows conventional or suggested sections.  Most manual pages
17*cb63e24eSchristos@c  should include at least the highlighted sections.  Arrange a new manual
18*cb63e24eSchristos@c  page so that sections are placed in the order shown in the list."
19*cb63e24eSchristos@c
20*cb63e24eSchristos@c              NAME
21*cb63e24eSchristos@c              SYNOPSIS
22*cb63e24eSchristos@c              CONFIGURATION    [Normally only in Section 4]
23*cb63e24eSchristos@c              DESCRIPTION
24*cb63e24eSchristos@c              OPTIONS          [Normally only in Sections 1, 8]
25*cb63e24eSchristos@c              EXIT STATUS      [Normally only in Sections 1, 8]
26*cb63e24eSchristos@c              RETURN VALUE     [Normally only in Sections 2, 3]
27*cb63e24eSchristos@c              ERRORS           [Typically only in Sections 2, 3]
28*cb63e24eSchristos@c              ENVIRONMENT
29*cb63e24eSchristos@c              FILES
30*cb63e24eSchristos@c              VERSIONS         [Normally only in Sections 2, 3]
31*cb63e24eSchristos@c              ATTRIBUTES       [Normally only in Sections 2, 3]
32*cb63e24eSchristos@c              CONFORMING TO
33*cb63e24eSchristos@c              NOTES
34*cb63e24eSchristos@c              BUGS
35*cb63e24eSchristos@c              EXAMPLES
36*cb63e24eSchristos@c              AUTHORS          [Discouraged]
37*cb63e24eSchristos@c              REPORTING BUGS   [Not used in man-pages]
38*cb63e24eSchristos@c              COPYRIGHT        [Not used in man-pages]
39*cb63e24eSchristos@c              SEE ALSO
40*cb63e24eSchristos@c
41*cb63e24eSchristos@c This is what the texi2pod.pl tool recognizes:
42*cb63e24eSchristos@c
43*cb63e24eSchristos@c for $sect (qw(NAME SYNOPSIS TARGET DESCRIPTION OPTIONS ENVIRONMENT FILES
44*cb63e24eSchristos@c               BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) {
45*cb63e24eSchristos@c
46*cb63e24eSchristos@c What is interesting is that it places "SEE ALSO" before "COPYRIGHT", which
47*cb63e24eSchristos@c makes sense and adhered to for the other formats.
48*cb63e24eSchristos@c ----------------------------------------------------------------------------
49*cb63e24eSchristos
50*cb63e24eSchristos@c ----------------------------------------------------------------------------
51*cb63e24eSchristos@c NAME section
52*cb63e24eSchristos@c ----------------------------------------------------------------------------
53*cb63e24eSchristos
54*cb63e24eSchristos@ManPageStart{NAME}
55*cb63e24eSchristos@c man begin NAME
56*cb63e24eSchristos
57*cb63e24eSchristosgp-display-html - Generate an HTML based directory structure to browse the
58*cb63e24eSchristosprofiles
59*cb63e24eSchristos
60*cb63e24eSchristos@c man end
61*cb63e24eSchristos@ManPageEnd{}
62*cb63e24eSchristos
63*cb63e24eSchristos@c ----------------------------------------------------------------------------
64*cb63e24eSchristos@c SYNOPSIS section
65*cb63e24eSchristos@c ----------------------------------------------------------------------------
66*cb63e24eSchristos
67*cb63e24eSchristos@ManPageStart{SYNOPSIS}
68*cb63e24eSchristos@c man begin SYNOPSIS
69*cb63e24eSchristos
70*cb63e24eSchristos@command{gprofng display html} [@var{option(s)}] @var{experiment(s)}
71*cb63e24eSchristos
72*cb63e24eSchristos@c man end
73*cb63e24eSchristos@ManPageEnd{}
74*cb63e24eSchristos
75*cb63e24eSchristos@c ----------------------------------------------------------------------------
76*cb63e24eSchristos@c DESCRIPTION section
77*cb63e24eSchristos@c ----------------------------------------------------------------------------
78*cb63e24eSchristos
79*cb63e24eSchristos@ManPageStart{DESCRIPTION}
80*cb63e24eSchristos@c man begin DESCRIPTION
81*cb63e24eSchristos
82*cb63e24eSchristosProcess one or more experiments to generate a directory containing the
83*cb63e24eSchristos@file{index.html} file that may be used to browse the experiment data.
84*cb63e24eSchristos
85*cb63e24eSchristos@c man end
86*cb63e24eSchristos@ManPageEnd{}
87*cb63e24eSchristos
88*cb63e24eSchristos@c ----------------------------------------------------------------------------
89*cb63e24eSchristos@c OPTIONS section
90*cb63e24eSchristos@c ----------------------------------------------------------------------------
91*cb63e24eSchristos
92*cb63e24eSchristos@ManPageStart{OPTIONS}
93*cb63e24eSchristos@c man begin OPTIONS
94*cb63e24eSchristos
95*cb63e24eSchristos@table @gcctabopt
96*cb63e24eSchristos
97*cb63e24eSchristos@item --version
98*cb63e24eSchristos@ifclear man
99*cb63e24eSchristos@IndexSubentry{Options, @code{--version}}
100*cb63e24eSchristos@end ifclear
101*cb63e24eSchristos
102*cb63e24eSchristosPrint the version number and exit.
103*cb63e24eSchristos
104*cb63e24eSchristos@item --help
105*cb63e24eSchristos@ifclear man
106*cb63e24eSchristos@IndexSubentry{Options, @code{--help}}
107*cb63e24eSchristos@end ifclear
108*cb63e24eSchristos
109*cb63e24eSchristosPrint usage information and exit.
110*cb63e24eSchristos
111*cb63e24eSchristos@item --verbose
112*cb63e24eSchristos@ifclear man
113*cb63e24eSchristos@IndexSubentry{Options, @code{--verbose}}
114*cb63e24eSchristos@end ifclear
115*cb63e24eSchristos
116*cb63e24eSchristosEnable verbose mode to show diagnostic messages about the processing of the
117*cb63e24eSchristosdata.  By default verbose mode is disabled.
118*cb63e24eSchristos
119*cb63e24eSchristos@item -d [@var{db-vol-size}], --debug[=@var{db-vol-size}]
120*cb63e24eSchristos@ifclear man
121*cb63e24eSchristos@IndexSubentry{Options, @code{-d}}
122*cb63e24eSchristos@IndexSubentry{Options, @code{--debug}}
123*cb63e24eSchristos@end ifclear
124*cb63e24eSchristos
125*cb63e24eSchristosControl the printing of run time debug information to assist with the
126*cb63e24eSchristostroubleshooting, or further development of this tool.
127*cb63e24eSchristos
128*cb63e24eSchristosThe @var{db-vol-size} parameter controls the output volume and is one from
129*cb63e24eSchristosthe list @samp{s}, @samp{S}, @samp{m}, @samp{M}, @samp{l}, @samp{L}, @samp{xl},
130*cb63e24eSchristosor @samp{XL}.  If @var{db-vol-size} is not set, a modest amount of information
131*cb63e24eSchristosis printed.  This is equivalent to select @samp{s}, or @samp{S}.  The volume
132*cb63e24eSchristosof data goes up as the size increases.  Note that currently @samp{l/L} is
133*cb63e24eSchristosequivalent to @samp{xl/XL}, but this is expected to change in future updates.
134*cb63e24eSchristosBy default debug mode is disabled.
135*cb63e24eSchristos
136*cb63e24eSchristos@item --highlight-percentage=@var{value}
137*cb63e24eSchristos@ifclear man
138*cb63e24eSchristos@IndexSubentry{Options, @code{--highlight-percentage}}
139*cb63e24eSchristos@end ifclear
140*cb63e24eSchristos
141*cb63e24eSchristosSet a percentage value in the interval [0,100] to select and color code source
142*cb63e24eSchristoslines, as well as instructions, that are within this percentage of the maximum
143*cb63e24eSchristosmetric value(s).  The default is 90 (%).  A value of zero disables this
144*cb63e24eSchristosfeature.
145*cb63e24eSchristos
146*cb63e24eSchristos@item -o @var{dirname}, --output=@var{dirname}
147*cb63e24eSchristos@ifclear man
148*cb63e24eSchristos@IndexSubentry{Options, @code{-o}}
149*cb63e24eSchristos@IndexSubentry{Options, @code{--output}}
150*cb63e24eSchristos@end ifclear
151*cb63e24eSchristos
152*cb63e24eSchristosUse @var{dirname} as the directory name to store the results in.  In
153*cb63e24eSchristosabsence of this option, the default name is @samp{display.<n>.html}.
154*cb63e24eSchristosThis directory is created in the current directory.
155*cb63e24eSchristosThe number @var{<n>} is the first positive integer number not in use in
156*cb63e24eSchristosthis naming scheme.  An existing directory with the same name is not
157*cb63e24eSchristosoverwritten.
158*cb63e24eSchristosIn case the directory exists already, an error message is printed and
159*cb63e24eSchristosthe tool terminates.
160*cb63e24eSchristos
161*cb63e24eSchristos@item -O @var{dirname}, --overwrite=@var{dirname}
162*cb63e24eSchristos@ifclear man
163*cb63e24eSchristos@IndexSubentry{Options, @code{-O}}
164*cb63e24eSchristos@IndexSubentry{Options, @code{--overwrite}}
165*cb63e24eSchristos@end ifclear
166*cb63e24eSchristos
167*cb63e24eSchristosUse @var{dirname} as the directory name to store the results in.  In
168*cb63e24eSchristosabsence of this option, the default name is @samp{display.<n>.html}.
169*cb63e24eSchristosThis directory is created in the current directory.
170*cb63e24eSchristosThe number @var{<n>} is the first positive integer number not in use in
171*cb63e24eSchristosthis naming scheme.  An existing directory with the same name is silently
172*cb63e24eSchristosoverwritten.
173*cb63e24eSchristos
174*cb63e24eSchristos@item -q,  --quiet
175*cb63e24eSchristos@ifclear man
176*cb63e24eSchristos@IndexSubentry{Options, @code{-q}}
177*cb63e24eSchristos@IndexSubentry{Options, @code{--quiet}}
178*cb63e24eSchristos@end ifclear
179*cb63e24eSchristos
180*cb63e24eSchristosDisable the display of all warning, debug, verbose and any other messages.
181*cb63e24eSchristosIf enabled, the settings for verbose and debug are accepted, but ignored.
182*cb63e24eSchristosWith this option, there is no screen output, other than errors.  By default
183*cb63e24eSchristosquiet mode is disabled.
184*cb63e24eSchristos
185*cb63e24eSchristos@item --nowarnings
186*cb63e24eSchristos@ifclear man
187*cb63e24eSchristos@IndexSubentry{Options, @code{--nowarnings}}
188*cb63e24eSchristos@end ifclear
189*cb63e24eSchristos
190*cb63e24eSchristosDisable the printing of warning messages on stdout.  By default warning
191*cb63e24eSchristosmessages are printed.
192*cb63e24eSchristos
193*cb63e24eSchristos@end table
194*cb63e24eSchristos
195*cb63e24eSchristos@c man end
196*cb63e24eSchristos@ManPageEnd{}
197*cb63e24eSchristos
198*cb63e24eSchristos@c ----------------------------------------------------------------------------
199*cb63e24eSchristos@c NOTES section
200*cb63e24eSchristos@c ----------------------------------------------------------------------------
201*cb63e24eSchristos
202*cb63e24eSchristos@ManPageStart{NOTES}
203*cb63e24eSchristos@c man begin NOTES
204*cb63e24eSchristos
205*cb63e24eSchristos@itemize @minus
206*cb63e24eSchristos
207*cb63e24eSchristos@item
208*cb63e24eSchristosThe options and values are case sensitive.
209*cb63e24eSchristos
210*cb63e24eSchristos@item
211*cb63e24eSchristosIn this release, the option syntax has changed to be more compliant with other
212*cb63e24eSchristostools and commands.
213*cb63e24eSchristos
214*cb63e24eSchristosThe options that used to have an @samp{on} or @samp{off} value only, now act
215*cb63e24eSchristosas a switch.  The option negates the default setting.  For example, by
216*cb63e24eSchristosdefault, verbose mode is disabled.  It is enabled by using the
217*cb63e24eSchristos@samp{--verbose} option.
218*cb63e24eSchristos
219*cb63e24eSchristosThe long options, those starting with @code{--}, that require a value, expect
220*cb63e24eSchristosthe @code{=} sign between the option and the value.
221*cb63e24eSchristos
222*cb63e24eSchristosWhile the previous syntax and choices are accepted still, we strongly
223*cb63e24eSchristosrecommend to change the usage of the options according to the new syntax
224*cb63e24eSchristosand values.  At some point, these legacy settings may no longer be accepted.
225*cb63e24eSchristos
226*cb63e24eSchristosTo assist with the transition, a warning message is shown if the legacy
227*cb63e24eSchristossyntax, or value, or both, are used.
228*cb63e24eSchristos
229*cb63e24eSchristos@item
230*cb63e24eSchristosThe @samp{-hp} option is still accepted, but it will be deprecated in a
231*cb63e24eSchristosfuture release.  Use the @samp{--highlight-percentage} option instead.
232*cb63e24eSchristos
233*cb63e24eSchristos@item
234*cb63e24eSchristosWhen setting a directory name for the HTML files to be stored in, make sure
235*cb63e24eSchristosthat umask is set to the correct access permissions.
236*cb63e24eSchristos
237*cb63e24eSchristos@item
238*cb63e24eSchristosRegardless of the setting for the warning messages, if there are warnings, they
239*cb63e24eSchristosare accessible through the main @file{index.html} page.
240*cb63e24eSchristos
241*cb63e24eSchristos@item
242*cb63e24eSchristosThe tool tries to accumulate as many warnings and errors as possible, before
243*cb63e24eSchristostaking action.  In this way, it is easier to address multiple issues at
244*cb63e24eSchristosonce.  As a result of this approach, it may be that the messages do not show
245*cb63e24eSchristosimmediately.  In particular, warnings are shown towards the end of the
246*cb63e24eSchristosexecution, but one or more errors will terminate execution before the
247*cb63e24eSchristosprocessing begins.
248*cb63e24eSchristos
249*cb63e24eSchristos@end itemize
250*cb63e24eSchristos
251*cb63e24eSchristos@c man end
252*cb63e24eSchristos@ManPageEnd{}
253*cb63e24eSchristos
254*cb63e24eSchristos@c ----------------------------------------------------------------------------
255*cb63e24eSchristos@c SEEALSO section
256*cb63e24eSchristos@c ----------------------------------------------------------------------------
257*cb63e24eSchristos
258*cb63e24eSchristos@ManPageStart{SEE ALSO}
259*cb63e24eSchristos@c man begin SEEALSO
260*cb63e24eSchristos
261*cb63e24eSchristosgprofng(1),
262*cb63e24eSchristosgp-archive(1),
263*cb63e24eSchristosgp-collect-app(1),
264*cb63e24eSchristosgp-display-gui(1),
265*cb63e24eSchristosgp-display-src(1),
266*cb63e24eSchristosgp-display-text(1)
267*cb63e24eSchristos
268*cb63e24eSchristos@iftex
269*cb63e24eSchristos@vspace{1}
270*cb63e24eSchristos@end iftex
271*cb63e24eSchristos
272*cb63e24eSchristosThe user guide for gprofng is maintained as a Texinfo manual.  If the
273*cb63e24eSchristos@command{info} and @command{gprofng} programs are correctly installed, the
274*cb63e24eSchristoscommand @command{info gprofng} should give access to this document.
275*cb63e24eSchristos
276*cb63e24eSchristos@c man end
277*cb63e24eSchristos@ManPageEnd{}
278*cb63e24eSchristos
279*cb63e24eSchristos@c ----------------------------------------------------------------------------
280*cb63e24eSchristos@c COPYRIGHT section
281*cb63e24eSchristos@c ----------------------------------------------------------------------------
282*cb63e24eSchristos
283*cb63e24eSchristos@ManPageStart{COPYRIGHT}
284*cb63e24eSchristos@c man begin COPYRIGHT
285*cb63e24eSchristos
286*cb63e24eSchristosCopyright @copyright{} 2022-2024 Free Software Foundation, Inc.
287*cb63e24eSchristos
288*cb63e24eSchristosPermission is granted to copy, distribute and/or modify this document
289*cb63e24eSchristosunder the terms of the GNU Free Documentation License, Version 1.3
290*cb63e24eSchristosor any later version published by the Free Software Foundation;
291*cb63e24eSchristoswith no Invariant Sections, with no Front-Cover Texts, and with no
292*cb63e24eSchristosBack-Cover Texts.  A copy of the license is included in the
293*cb63e24eSchristossection entitled ``GNU Free Documentation License''.
294*cb63e24eSchristos
295*cb63e24eSchristos@c man end
296*cb63e24eSchristos@ManPageEnd{}
297*cb63e24eSchristos
298*cb63e24eSchristos@c ----------------------------------------------------------------------------
299*cb63e24eSchristos@c If this text is used for a man page, exit.  Otherwise we need to continue.
300*cb63e24eSchristos@c ----------------------------------------------------------------------------
301*cb63e24eSchristos
302*cb63e24eSchristos@ifset man
303*cb63e24eSchristos@bye
304*cb63e24eSchristos@end ifset
305