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