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