From 203e43a44d4a528d047d9c35593b9705a4d88029 Mon Sep 17 00:00:00 2001 From: Jake Hunsaker Date: Mon, 25 Oct 2021 12:09:34 -0400 Subject: [sos] Add 'help' component for enhanced help information This commit marks the beginning of the addition of a new `help` component for sos, which will be used to display more in-depth help information surrounding all the different components of sos. The command is intended to be invoked with a specific help topic in mind, that mirrors our project layout. E.G. to get help on the report component, a user would use `sos help report`, whereas to get help on a specific plugin a user would use `sos help report.plugins.$plugin`. This first commit includes both the initial framework for the `help` component, as well as updating `SoSReport` and `Plugin` to provide a basic implementation for the new subcommand. Additionally, `Policy` is given a basic framework for existing policies to report certain default values as well as available presets. A stub section is provided for the base `RedHatPolicy` to serve as a redirector for the actually used policies that subclass it. Closes: #2205 --- man/en/sos-help.1 | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 man/en/sos-help.1 (limited to 'man/en') diff --git a/man/en/sos-help.1 b/man/en/sos-help.1 new file mode 100644 index 00000000..ec7777ac --- /dev/null +++ b/man/en/sos-help.1 @@ -0,0 +1,41 @@ +.TH SOS HELP 1 "Fri Nov 05 2021" +.SH NAME +sos help - get detailed help information on sos commands and components +.SH SYNOPSIS +.B sos help TOPIC + +.SH DESCRIPTION +\fBsos help\fR is used to retrieve more detailed information on the various SoS +commands and components than is directly available in either other manpages or +--help output. + +This information could for example be investigating a specific plugin to learn more +about its purpose, use case, collections, available plugin options, edge cases, and +more. +.LP +Most aspects of SoS' operation can be investigated this way - the top level functions +such as \fB report, clean,\fR and \fBcollect\fR, as well as constructs that allow those +functions to work; e.g. \fBtransports\fR within \fBsos collect\fR that define how that +function connects to remote nodes. + +.SH REQUIRED ARGUMENTS +.B TOPIC +.TP +The section or topic to retrieve detailed help information for. TOPIC takes the general +form of \fBcommand.component.entity\fR, with \fBcomponent\fR and \fBentity\fR +being optional. +.LP +Top-level \fBcommand\fR help sections will often direct users to \fBcomponent\fR sections +which in turn may point to further \fBentity\fR subsections. + +Some of the more useful or interesting sections are listed below: + + \fBTopic\fR \fBDescription\fR + + \fBreport\fR The \fBsos report\fR command + \fBreport.plugins\fR Information on what report plugins are + \fBreport.plugins.$plugin\fR Information on a specific plugin + \fBclean\fR or \fBmask\fR The \fBsos clean|mask\fR command + \fBcollect\fR The \fBsos collect\fR command + \fBcollect.clusters\fR How \fBcollect\fR enumerates nodes in a cluster + \fBpolicies\fR How SoS behaves on different distributions -- cgit