7a515757db
This patch addresses bugzilla 29521: Bug 29521 - [docs] man pages are not in the release tarball The dependence on help2man to create the man pages has been eliminated. All man pages are now written in Texinfo. Texi2pod and pod2man are used to generate the man pages from the source. The user guide has been significantly expanded. It also includes all the man pages. These are formatted appropriately in the INFO, PDF, and HTML formats. The index in the user guide has been enhanced to include an overview of all options and commands that have been documented so far. The work on the documentation has not been completed, but this is a significant step forward. gprofng/ChangeLog 2023-04-15 Vladimir Mezentsev <vladimir.mezentsev@oracle.com> PR gprofng/29521 * doc/Makefile.am: Build documentation. * doc/gprofng.texi: Update documentation. * doc/version.texi: Likewise. * src/Makefile.am: Move the man pages generation to doc/Makefile.am. * gp-display-html/Makefile.am: Likewise. * doc/gp-archive.texi: New file. * doc/gp-collect-app.texi: New file. * doc/gp-display-html.texi: New file. * doc/gp-display-src.texi: New file. * doc/gp-display-text.texi: New file. * doc/gp-macros.texi: New file. * doc/gprofng_ug.texi: New file. * doc/Makefile.in: Rebuild. * gp-display-html/Makefile.in: Rebuild. * src/Makefile.in" Rebuild.
252 lines
8.1 KiB
Text
252 lines
8.1 KiB
Text
@c ----------------------------------------------------------------------------
|
|
@c This is the Texinfo source file for the gp-collect-app man page.
|
|
@c
|
|
@c Author: Ruud van der Pas
|
|
@c ----------------------------------------------------------------------------
|
|
@ifset man
|
|
\input texinfo @c -*-texinfo-*-
|
|
@setfilename gprofng display html
|
|
@settitle Generate an HTML based directory structure to browse the profiles
|
|
@include gp-macros.texi
|
|
@end ifset
|
|
|
|
@c ----------------------------------------------------------------------------
|
|
@c This is from the man-pages(7) man page
|
|
@c
|
|
@c "The list below shows conventional or suggested sections. Most manual pages
|
|
@c should include at least the highlighted sections. Arrange a new manual
|
|
@c page so that sections are placed in the order shown in the list."
|
|
@c
|
|
@c NAME
|
|
@c SYNOPSIS
|
|
@c CONFIGURATION [Normally only in Section 4]
|
|
@c DESCRIPTION
|
|
@c OPTIONS [Normally only in Sections 1, 8]
|
|
@c EXIT STATUS [Normally only in Sections 1, 8]
|
|
@c RETURN VALUE [Normally only in Sections 2, 3]
|
|
@c ERRORS [Typically only in Sections 2, 3]
|
|
@c ENVIRONMENT
|
|
@c FILES
|
|
@c VERSIONS [Normally only in Sections 2, 3]
|
|
@c ATTRIBUTES [Normally only in Sections 2, 3]
|
|
@c CONFORMING TO
|
|
@c NOTES
|
|
@c BUGS
|
|
@c EXAMPLES
|
|
@c AUTHORS [Discouraged]
|
|
@c REPORTING BUGS [Not used in man-pages]
|
|
@c COPYRIGHT [Not used in man-pages]
|
|
@c SEE ALSO
|
|
@c
|
|
@c This is what the texi2pod.pl tool recognizes:
|
|
@c
|
|
@c for $sect (qw(NAME SYNOPSIS TARGET DESCRIPTION OPTIONS ENVIRONMENT FILES
|
|
@c BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) {
|
|
@c
|
|
@c What is interesting is that it places "SEE ALSO" before "COPYRIGHT", which
|
|
@c makes sense and adhered to for the other formats.
|
|
@c ----------------------------------------------------------------------------
|
|
|
|
@c ----------------------------------------------------------------------------
|
|
@c NAME section
|
|
@c ----------------------------------------------------------------------------
|
|
|
|
@ManPageStart{NAME}
|
|
@c man begin NAME
|
|
|
|
gprofng display html - Generate an HTML based directory structure to browse the profiles
|
|
|
|
@c man end
|
|
@ManPageEnd{}
|
|
|
|
@c ----------------------------------------------------------------------------
|
|
@c SYNOPSIS section
|
|
@c ----------------------------------------------------------------------------
|
|
|
|
@ManPageStart{SYNOPSIS}
|
|
@c man begin SYNOPSIS
|
|
|
|
@command{gprofng display html} [@var{option(s)}] @var{experiment(s)}
|
|
|
|
@c man end
|
|
@ManPageEnd{}
|
|
|
|
@c ----------------------------------------------------------------------------
|
|
@c DESCRIPTION section
|
|
@c ----------------------------------------------------------------------------
|
|
|
|
@ManPageStart{DESCRIPTION}
|
|
@c man begin DESCRIPTION
|
|
|
|
Process one or more experiments to generate a directory containing the
|
|
@file{index.html} file that may be used to browse the experiment data.
|
|
|
|
@c man end
|
|
@ManPageEnd{}
|
|
|
|
@c ----------------------------------------------------------------------------
|
|
@c OPTIONS section
|
|
@c ----------------------------------------------------------------------------
|
|
|
|
@ManPageStart{OPTIONS}
|
|
@c man begin OPTIONS
|
|
|
|
@table @gcctabopt
|
|
|
|
@item --version
|
|
@ifclear man
|
|
@IndexSubentry{Options, @code{--version}}
|
|
@end ifclear
|
|
|
|
Print the version number and exit.
|
|
|
|
@item --help
|
|
@ifclear man
|
|
@IndexSubentry{Options, @code{--help}}
|
|
@end ifclear
|
|
|
|
Print usage information and exit.
|
|
|
|
@item --verbose @{on|off@}
|
|
@ifclear man
|
|
@IndexSubentry{Options, @code{--verbose}}
|
|
@end ifclear
|
|
|
|
Enable (@samp{on}) or disable (@samp{off)} verbose mode.
|
|
The default is @samp{off}.
|
|
|
|
@item --debug @{on|s|m|l|xl|off@}
|
|
@item -d @{on|s|m|l|xl|off@}
|
|
@ifclear man
|
|
@IndexSubentry{Options, @code{-d}}
|
|
@IndexSubentry{Options, @code{--debug}}
|
|
@end ifclear
|
|
|
|
Control the printing of run time information to assist with troubleshooting,
|
|
or further development of this tool. The keyword is case insensitive.
|
|
A setting of @samp{on} gives a modest amount of information. The keywords
|
|
@samp{s}, @samp{m}, @samp{l}, and @samp{xl} give an increasing amount of
|
|
information, while @samp{off} disables the printing of debug information.
|
|
This is also the default.
|
|
|
|
Note that currently @samp{on}, @samp{s}, @samp{m}, and @samp{l} are
|
|
equivalent. This is expected to change in future updates.
|
|
|
|
@item ---highlight-percentage @var{value}
|
|
@item -hp @var{value}
|
|
@ifclear man
|
|
@IndexSubentry{Options, @code{--highlight-percentage}}
|
|
@IndexSubentry{Options, @code{-hp}}
|
|
@end ifclear
|
|
|
|
Set a percentage value in the interval [0,100] to select and color code source
|
|
lines, as well as instructions, that are within this percentage of the maximum
|
|
metric value(s). The default is 90 (%).
|
|
|
|
A value of zero @samp{(-hp 0)} disables this feature.
|
|
|
|
@item --output @var{dirname}
|
|
@item -o @var{dirname}
|
|
@ifclear man
|
|
@IndexSubentry{Options, @code{--output}}
|
|
@IndexSubentry{Options, @code{-o}}
|
|
@end ifclear
|
|
|
|
Use @var{dirname} as the directory name to store the HTML files in.
|
|
The default name is @samp{display.<n>.html} with @var{<n>} the first
|
|
positive integer number not in use. An existing directory with the
|
|
same name is not overwritten.
|
|
|
|
@item --overwrite @var{dirname}
|
|
@item -O @var{dirname}
|
|
@ifclear man
|
|
@IndexSubentry{Options, @code{--overwrite}}
|
|
@IndexSubentry{Options, @code{-O}}
|
|
@end ifclear
|
|
|
|
Use @var{dirname} as the directory name to store the HTML files in.
|
|
|
|
@item --quiet @{on|off@}
|
|
@item -q @{on|off@}
|
|
@ifclear man
|
|
@IndexSubentry{Options, @code{--quiet}}
|
|
@IndexSubentry{Options, @code{-q}}
|
|
@end ifclear
|
|
|
|
Control the display of all warning, debug and verbose messages.
|
|
If set to @samp{on}, the settings for verbose, warnings and debug are ignored.
|
|
By default the quiet mode is disabled (@samp{-q off}).
|
|
|
|
@item --warnings @{on|off@}
|
|
@item -w @{on|off@}
|
|
@ifclear man
|
|
@IndexSubentry{Options, @code{--warnings}}
|
|
@IndexSubentry{Options, @code{-w}}
|
|
@end ifclear
|
|
|
|
Enable (@samp{on}), or disable (@samp{off}) run time warning messages from
|
|
the tool. By default these are enabled.
|
|
|
|
@end table
|
|
|
|
@c man end
|
|
@ManPageEnd{}
|
|
|
|
@c ----------------------------------------------------------------------------
|
|
@c NOTES section
|
|
@c ----------------------------------------------------------------------------
|
|
|
|
@ManPageStart{NOTES}
|
|
@c man begin NOTES
|
|
|
|
When setting a directory name for the HTML files to be stored in, make sure that
|
|
umask is set to the correct access permissions.
|
|
|
|
Regardless of the setting for the warning messages, any warnings are accessible
|
|
through the main @file{index.html} page.
|
|
|
|
@c man end
|
|
@ManPageEnd{}
|
|
|
|
@c ----------------------------------------------------------------------------
|
|
@c SEEALSO section
|
|
@c ----------------------------------------------------------------------------
|
|
|
|
@ManPageStart{SEEALSO}
|
|
@c man begin SEEALSO
|
|
|
|
gprofng(1), gp-archive(1), gp-collect-app(1), gp-display-src(1), gp-display-text(1)
|
|
|
|
The user guide for gprofng is maintained as a Texinfo manual. If the
|
|
@command{info} and @command{gprofng} programs are correctly installed, the
|
|
command @command{info gprofng} should give access to this document.
|
|
|
|
@c man end
|
|
@ManPageEnd{}
|
|
|
|
@c ----------------------------------------------------------------------------
|
|
@c COPYRIGHT section
|
|
@c ----------------------------------------------------------------------------
|
|
|
|
@ManPageStart{COPYRIGHT}
|
|
@c man begin COPYRIGHT
|
|
|
|
Copyright @copyright{} 2022-2023 Free Software Foundation, Inc.
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3
|
|
or any later version published by the Free Software Foundation;
|
|
with no Invariant Sections, with no Front-Cover Texts, and with no
|
|
Back-Cover Texts. A copy of the license is included in the
|
|
section entitled ``GNU Free Documentation License''.
|
|
|
|
@c man end
|
|
@ManPageEnd{}
|
|
|
|
@c ----------------------------------------------------------------------------
|
|
@c If this text is used for a man page, exit. Otherwise we need to continue.
|
|
@c ----------------------------------------------------------------------------
|
|
|
|
@ifset man
|
|
@bye
|
|
@end ifset
|