Fix some of the markup to be more consistent with sudo_plugin.mdoc.in.

Also reword a few awkward phrases.

1 files changed, 118 insertions, 95 deletions

diff --git a/docs/sudo_plugin_python.man.in b/docs/sudo_plugin_python.man.in
index 98c0abbfc..e67f55982 100644
--- a/docs/sudo_plugin_python.man.in
+++ b/docs/sudo_plugin_python.man.in
@@ -17,7 +17,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.TH "SUDO_PLUGIN_PYTHON" "5" "June 6, 2022" "Sudo @PACKAGE_VERSION@" "File Formats Manual"
+.TH "SUDO_PLUGIN_PYTHON" "5" "September 11, 2022" "Sudo @PACKAGE_VERSION@" "File Formats Manual"
 .nh
 .if n .ad l
 .SH "NAME"
@@ -96,9 +96,9 @@ When the plugin loads,
 will create an instance of this class and call the methods.
 The actual methods required depent on the type of the plugin,
 but most return an
-\(lqint\(rq
+\fIint\fR
 result code, as documented in
-sudo_plugin(@mansectsu@),
+sudo_plugin(@mansectform@),
 that indicates whether or not the method was successful.
 The Python sudo module defines the following constants to improve readability:
 .RS 4n
@@ -120,12 +120,12 @@ l l.
 .RE
 .PP
 If a function returns
-\fINone\fR
+\fRNone\fR
 (for example, if it does not call return),
 it will be considered to have returned
 \fRsudo.RC.OK\fR.
-If an exception is raised (other than sudo.PluginException), the backtrace will be
-shown to the user and the plugin function will return
+If an exception is raised (other than sudo.PluginException), the
+backtrace will be shown to the user and the plugin function will return
 \fRsudo.RC.ERROR\fR.
 If that is not acceptable, you must catch the exception and handle it yourself.
 .PP
@@ -151,7 +151,7 @@ Running the Python interpreter and bridging between C and Python is
 handled by the
 \fBsudo\fR
 plugin
-\fRpython_plugin.so\fR.
+\fIpython_plugin.so\fR.
 This shared object can be loaded like any other dynamic
 \fBsudo\fR
 plugin and should receive the path and the class name of the Python
@@ -219,7 +219,7 @@ sudo.conf(@mansectform@).
 .PP
 A policy plugin may have the following member functions:
 .TP 6n
-\fBconstructor\fR
+\fIconstructor\fR
 .nf
 .RS 6n
 __init__(self, user_env: Tuple[str, ...], settings: Tuple[str, ...],
@@ -235,7 +235,9 @@ as member variables in the object.
 .sp
 The constructor matches the
 \fBopen\fR()
-function in the C sudo plugin API.
+function in the C
+\fBsudo\fR
+plugin API.
 .sp
 The function arguments are as follows:
 .TP 6n
@@ -279,7 +281,7 @@ documentation in
 sudo_plugin(@mansectform@).
 .RE
 .TP 6n
-\fBcheck_policy\fR
+\fIcheck_policy\fR
 .nf
 .RS 6n
 check_policy(self, argv: Tuple[str, ...], env_add: Tuple[str, ...])
@@ -367,7 +369,7 @@ format.
 .RE
 .PD
 .TP 6n
-\fBinit_session\fR
+\fIinit_session\fR
 .nf
 .RS 6n
 init_session(self, user_pwd: Tuple, user_env: Tuple[str, ...])
@@ -387,8 +389,9 @@ The function arguments are as follows:
 .TP 6n
 \fIuser_pwd\fR
 A tuple describing the user's passwd entry.
-Convertible to pwd.struct_passwd or
-\fINone\fR
+Convertible to
+\fIpwd.struct_passwd or\fR
+\fRNone\fR
 if the user is not present in the password database.
 .sp
 Example conversion:
@@ -437,7 +440,7 @@ If this is omitted, no changes will be made to
 .RE
 .PD
 .TP 6n
-\fBlist\fR
+\fIlist\fR
 .nf
 .RS 6n
 list(self, argv: Tuple[str, ...], is_verbose: int, user: str)
@@ -451,7 +454,7 @@ The function arguments are as follows:
 .TP 6n
 \fIargv\fR
 If not set to
-\fINone\fR,
+\fRNone\fR,
 an argument vector describing a command the user wishes to check
 against the policy.
 .TP 6n
@@ -461,14 +464,14 @@ Flag indicating whether to list in verbose mode or not.
 \fIuser\fR
 The name of a different user to list privileges for if the policy allows it.
 If
-\fINone\fR,
+\fRNone\fR,
 the plugin should list the privileges of the invoking user.
 .PD 0
 .PP
 .RE
 .PD
 .TP 6n
-\fBvalidate\fR
+\fIvalidate\fR
 .nf
 .RS 6n
 validate(self)
@@ -479,7 +482,7 @@ validate(self)
 For policy plugins that cache authentication credentials, this function is used to validate and cache the credentials (optional).
 .RE
 .TP 6n
-\fBinvalidate\fR
+\fIinvalidate\fR
 .nf
 .RS 6n
 invalidate(self, remove: int)
@@ -499,7 +502,7 @@ invalidating them.
 .RE
 .PD
 .TP 6n
-\fBshow_version\fR
+\fIshow_version\fR
 .nf
 .RS 6n
 show_version(self, is_verbose: int)
@@ -524,7 +527,7 @@ is run as the root user.
 .RE
 .PD
 .TP 6n
-\fBclose\fR
+\fIclose\fR
 .br
 .nf
 .RS 6n
@@ -537,7 +540,9 @@ Called when a command finishes executing.
 .sp
 Works the same as the
 \fBclose\fR()
-function in the C sudo plugin API, except that it only gets called if
+function in the C
+\fBsudo\fR
+plugin API, except that it only gets called if
 \fBsudo\fR
 attempts to execute the command.
 .sp
@@ -569,8 +574,10 @@ Plugin python_policy python_plugin.so \e
 .RE
 .fi
 .PP
-Be aware, however, that you cannot enable the Python policy plugin
-in addition to another policy plugin, such as
+Only one policy plugin can be enabled at a time so you must disable
+any other policy plugin listed in
+\fI@sysconfdir@/sudo.conf\fR,
+such as
 sudoers(@mansectform@).
 .SS "I/O plugin API"
 I/O plugins must be registered in
@@ -588,7 +595,7 @@ Currently only 8 python I/O plugins can be loaded at once.
 .PP
 An I/O plugin may have the following member functions:
 .TP 6n
-\fBconstructor\fR
+\fIconstructor\fR
 .nf
 .RS 6n
 __init__(self, user_env: Tuple[str, ...], settings: Tuple[str, ...],
@@ -604,7 +611,9 @@ as member variables in the object.
 .sp
 The constructor matches the
 \fBopen\fR()
-function in the C sudo plugin API.
+function in the C
+\fBsudo\fR
+plugin API.
 .sp
 The function arguments are as follows:
 .TP 6n
@@ -648,7 +657,7 @@ documentation in
 sudo_plugin(@mansectform@).
 .RE
 .TP 6n
-\fBopen\fR
+\fIopen\fR
 .nf
 .RS 6n
 open(self, argv: Tuple[str, ...],
@@ -661,13 +670,15 @@ Receives the command the user wishes to run.
 .sp
 Works the same as the
 \fBopen\fR()
-function in the C sudo plugin API except that:
+function in the C
+\fBsudo\fR
+plugin API except that:
 .sp
 .RS 10n
 .PD 0
 .TP 3n
 \fB\(bu\fR
-It only gets called before the user would execute some command
+It only gets called when there is a command to be executed
 (and not for a version query for example).
 .TP 3n
 \fB\(bu\fR
@@ -708,7 +719,7 @@ If the function returns
 no I/O will be sent to the plugin.
 .RE
 .TP 6n
-\fBlog_ttyin\fR, \fBlog_ttyout\fR, \fBlog_stdin\fR, \fBlog_stdout\fR, \fBlog_stderr\fR
+\fIlog_ttyin\fR, \fIlog_ttyout\fR, \fIlog_stdin\fR, \fIlog_stdout\fR, \fIlog_stderr\fR
 .nf
 .RS 6n
 log_ttyin(self, buf: str) -> int
@@ -736,8 +747,8 @@ constants.
 .sp
 If
 \fRsudo.RC.ERROR\fR
-is returned, the running command will be terminated and all of the plugin's logging
-functions will be disabled.
+is returned, the running command will be terminated and all of the
+plugin's logging functions will be disabled.
 Other I/O logging plugins will still receive any remaining
 input or output that has not yet been processed.
 .sp
@@ -751,7 +762,7 @@ the command will be terminated and the data will not be written to the
 terminal, though it will still be sent to any other I/O logging plugins.
 .RE
 .TP 6n
-\fBchange_winsize\fR
+\fIchange_winsize\fR
 .nf
 .RS 6n
 change_winsize(self, line: int, cols: int) -> int
@@ -772,7 +783,7 @@ The number of columns of the terminal.
 .RE
 .PD
 .TP 6n
-\fBlog_suspend\fR
+\fIlog_suspend\fR
 .nf
 .RS 6n
 log_suspend(self, signo: int) -> int
@@ -793,7 +804,7 @@ if the command was resumed.
 .RE
 .PD
 .TP 6n
-\fBshow_version\fR
+\fIshow_version\fR
 .nf
 .RS 6n
 show_version(self, is_verbose: int)
@@ -817,7 +828,7 @@ is run as the root user.
 .RE
 .PD
 .TP 6n
-\fBclose\fR
+\fIclose\fR
 .br
 .nf
 .RS 6n
@@ -825,11 +836,13 @@ close(self, exit_status: int, error: int) -> None
 .RE
 .fi
 .RS 6n
-Called when a command execution finished.
+Called when a command finishes execution.
 .sp
 Works the same as the
 \fBclose\fR()
-function in the C sudo plugin API, except that it only gets called if
+function in the C
+\fBsudo\fR
+plugin API, except that it only gets called if
 \fBsudo\fR
 attempts to execute the command.
 .sp
@@ -849,7 +862,7 @@ system call, otherwise 0.
 .RE
 .PD
 .SS "I/O plugin example"
-Sudo ships a Python I/O plugin example.
+Sudo ships with a Python I/O plugin example.
 To try it, register it by adding the following lines to
 \fI@sysconfdir@/sudo.conf\fR:
 .nf
@@ -874,9 +887,9 @@ Plugin python_audit python_plugin.so ModulePath=<path> ClassName=<class>
 Sudo supports loading multiple audit plugins.
 Currently only 8 python audit plugins can be loaded at once.
 .PP
-An audit plugin may have the following member functions (all of them are optional):
+An audit plugin may have the following member functions (all of which are optional):
 .TP 6n
-\fBconstructor\fR
+\fIconstructor\fR
 .nf
 .RS 6n
 __init__(self, user_env: Tuple[str, ...], settings: Tuple[str, ...],
@@ -890,7 +903,9 @@ as member variables in the object.
 .sp
 The constructor matches the
 \fBopen\fR()
-function in the C sudo plugin API.
+function in the C
+\fBsudo\fR
+plugin API.
 .sp
 The function arguments are as follows:
 .TP 6n
@@ -926,7 +941,7 @@ format.
 .RE
 .PD
 .TP 6n
-\fBopen\fR
+\fIopen\fR
 .nf
 .RS 6n
 open(self, submit_optind: int,
@@ -949,7 +964,7 @@ The argument vector sudo was invoked with, including all command line options.
 .RE
 .PD
 .TP 6n
-\fBclose\fR
+\fIclose\fR
 .br
 .nf
 .RS 6n
@@ -964,7 +979,9 @@ The function arguments are as follows:
 .TP 6n
 \fIstatus_type\fR
 The type of status being passed.
-One of the sudo.EXIT_REASON.* constants.
+One of the
+\fRsudo.EXIT_REASON.*\fR
+constants.
 .TP 6n
 \fIstatus\fR
 Depending on the value of
@@ -973,11 +990,11 @@ this value is either
 ignored, the command's exit status as returned by the
 wait(2)
 system call, the value of
-\fRerrno\fR
+\fIerrno\fR
 set by the
 execve(2)
 system call, or the value of
-\fRerrno\fR
+\fIerrno\fR
 resulting from an error in the
 \fBsudo\fR
 front-end.
@@ -986,7 +1003,7 @@ front-end.
 .RE
 .PD
 .TP 6n
-\fBshow_version\fR
+\fIshow_version\fR
 .nf
 .RS 6n
 show_version(self, is_verbose: int) -> int
@@ -1011,7 +1028,7 @@ is run as the root user.
 .RE
 .PD
 .TP 6n
-\fBaccept\fR
+\fIaccept\fR
 .nf
 .RS 6n
 accept(self, plugin_name: str, plugin_type: int, command_info: Tuple[str, ...],
@@ -1075,7 +1092,7 @@ The environment the command will be run with.
 .RE
 .PD
 .TP 6n
-\fBreject\fR
+\fIreject\fR
 .nf
 .RS 6n
 reject(self, plugin_name: str, plugin_type: int, audit_msg: str,
@@ -1109,7 +1126,7 @@ front-end.
 audit_msg
 An optional string describing the reason the command was rejected by the plugin.
 If the plugin did not provide a reason, audit_msg will be
-\fINone\fR
+\fRNone\fR.
 .TP 6n
 command_info
 A vector of information describing the rejected command.
@@ -1121,7 +1138,7 @@ manual for possible values.
 .RE
 .PD
 .TP 6n
-\fBerror\fR
+\fIerror\fR
 .br
 .nf
 .RS 6n
@@ -1153,7 +1170,7 @@ front-end.
 audit_msg
 An optional string describing the plugin error.
 If the plugin did not provide a description, it will be
-\fINone\fR
+\fRNone\fR.
 .TP 6n
 command_info
 A vector of information describing the command.
@@ -1165,7 +1182,7 @@ manual for possible values.
 .RE
 .PD
 .SS "Audit plugin example"
-Sudo ships a Python Audit plugin example.
+Sudo ships with a Python Audit plugin example.
 To try it, register it by adding the following lines to
 \fI@sysconfdir@/sudo.conf\fR:
 .nf
@@ -1194,7 +1211,7 @@ Currently only 8 python approval plugins can be loaded at once.
 .PP
 An approval plugin may have the following member functions:
 .TP 6n
-\fBconstructor\fR
+\fIconstructor\fR
 .nf
 .RS 6n
 __init__(self, user_env: Tuple[str, ...], settings: Tuple[str, ...],
@@ -1210,7 +1227,9 @@ as member variables in the object.
 .sp
 The constructor matches the
 \fBopen\fR()
-function in the C sudo plugin API.
+function in the C
+\fBsudo\fR
+plugin API.
 .sp
 The function arguments are as follows:
 .TP 6n
@@ -1254,7 +1273,7 @@ The argument vector sudo was invoked with, including all command line options.
 .RE
 .PD
 .TP 6n
-\fBshow_version\fR
+\fIshow_version\fR
 .nf
 .RS 6n
 show_version(self, is_verbose: int) -> int
@@ -1262,10 +1281,11 @@ show_version(self, is_verbose: int) -> int
 .fi
 .RS 6n
 .sp
-Display the version. (Same as for all the other plugins.)
+Display the version.
+(Same as for all the other plugins.)
 .RE
 .TP 6n
-\fBcheck\fR
+\fIcheck\fR
 .br
 .nf
 .RS 6n
@@ -1306,7 +1326,7 @@ The environment the command will be run with.
 .RE
 .PD
 .SS "Approval plugin example"
-Sudo ships a Python Approval plugin example.
+Sudo ships with a Python Approval plugin example.
 To try it, register it by adding the following lines to
 \fI@sysconfdir@/sudo.conf\fR:
 .nf
@@ -1337,7 +1357,7 @@ Currently, only a single group plugin can be registered in
 .PP
 A group provider plugin may have the following member functions:
 .TP 6n
-\fBconstructor\fR
+\fIconstructor\fR
 .nf
 .RS 6n
 __init__(self, args: Tuple[str, ...], version: str)
@@ -1366,7 +1386,7 @@ The version of the Python Group Plugin API.
 .RE
 .PD
 .TP 6n
-\fBquery\fR
+\fIquery\fR
 .br
 .nf
 .RS 6n
@@ -1402,7 +1422,7 @@ is not present in the password database,
 will be
 \fRNULL\fR.
 .SS "Group plugin example"
-Sudo ships a Python group plugin example.
+Sudo ships with a Python group plugin example.
 To try it, register it in the
 \fIsudoers\fR
 file by adding the following lines:
@@ -1419,7 +1439,7 @@ The example plugin will tell
 \fBsudo\fR
 that the user
 \fItest\fR
-is part of the non-unix group
+is part of the non-Unix group
 \fImygroup\fR.
 If you add a rule that uses this group, it will affect the
 \fItest\fR
@@ -1444,16 +1464,18 @@ written in Python.
 A Python plugin can interact with the user using the
 \fBsudo.conv\fR()
 function which displays one or more messages described by the
-\fBsudo.ConvMessage\fR
+\fRsudo.ConvMessage\fR
 class.
 This is the Python equivalent of the
 \fBconversation\fR()
-function in the C sudo plugin API.
+function in the C
+\fBsudo\fR
+plugin API.
 A plugin should not attempt to read directly from the standard input or
 the user's tty (neither of which are guaranteed to exist).
 .PP
 The
-\fBsudo.ConvMessage\fR
+\fRsudo.ConvMessage\fR
 class specifies how the user interaction should occur:
 .nf
 .sp
@@ -1462,7 +1484,7 @@ sudo.ConvMessage(msg_type: int, msg: str, timeout: int)
 .RE
 .fi
 .PP
-\fBsudo.ConvMessage\fR
+\fRsudo.ConvMessage\fR
 member variables:
 .TP 6n
 \fImsg_type\fR
@@ -1474,7 +1496,7 @@ constants below.
 \fImsg\fR
 The message to display to the user.
 The caller must include a trailing newline in
-\fRmsg\fR
+\fImsg\fR
 if one is to be displayed.
 .TP 6n
 \fItimeout\fR
@@ -1493,25 +1515,25 @@ To specify the message type, the following constants are available:
 .PD 0
 .TP 3n
 \fB\(bu\fR
-sudo.CONV.PROMPT_ECHO_OFF
+\fRsudo.CONV.PROMPT_ECHO_OFF\fR
 .TP 3n
 \fB\(bu\fR
-sudo.CONV.PROMPT_ECHO_ON
+\fRsudo.CONV.PROMPT_ECHO_ON\fR
 .TP 3n
 \fB\(bu\fR
-sudo.CONV.ERROR_MSG
+\fRsudo.CONV.ERROR_MSG\fR
 .TP 3n
 \fB\(bu\fR
-sudo.CONV.INFO_MSG
+\fRsudo.CONV.INFO_MSG\fR
 .TP 3n
 \fB\(bu\fR
-sudo.CONV.PROMPT_MASK
+\fRsudo.CONV.PROMPT_MASK\fR
 .TP 3n
 \fB\(bu\fR
-sudo.CONV.PROMPT_ECHO_OK
+\fRsudo.CONV.PROMPT_ECHO_OK\fR
 .TP 3n
 \fB\(bu\fR
-sudo.CONV.PREFER_TTY
+\fRsudo.CONV.PREFER_TTY\fR
 .RE
 .PD
 .PP
@@ -1534,7 +1556,7 @@ The function arguments are as follows:
 .TP 6n
 \fImessage(s)\fR
 One of more messages (of type
-\fBsudo.ConvMessage\fR),
+\fRsudo.ConvMessage\fR),
 each describing a conversation.
 At least one message is required.
 .TP 6n
@@ -1554,11 +1576,11 @@ The
 \fBsudo.conv\fR()
 function can raise the following exceptions:
 .TP 6n
-\fBsudo.SudoException\fR
+\fRsudo.SudoException\fR
 If the conversation fails, for example when the conversation function is not
 available.
 .TP 6n
-\fBsudo.ConversationInterrupted\fR
+\fRsudo.ConversationInterrupted\fR
 If the conversation function returns an error, e.g., the timeout passed
 or the user interrupted the conversation by pressing control-C.
 .SS "Conversation example"
@@ -1618,7 +1640,7 @@ debug system.
 \fIEnabling debugging in sudo.conf\fR
 .PP
 To enable debug messages, add a
-\fRDebug\fR
+\fIDebug\fR
 line to
 sudo.conf(@mansectform@)
 with the program set to
@@ -1710,21 +1732,21 @@ l l l.
 .PP
 \fBsudo.conf name\fR	\fBPython constant\fR	\fBdescription\fR
 .PP
-crit	sudo.DEBUG.CRIT	only critical messages
+crit	\fRsudo.DEBUG.CRIT\fR	only critical messages
 .PP
-err	sudo.DEBUG.ERROR	
+err	\fRsudo.DEBUG.ERROR\fR	
 .PP
-warn	sudo.DEBUG.WARN	
+warn	\fRsudo.DEBUG.WARN\fR	
 .PP
-notice	sudo.DEBUG.NOTICE	
+notice	\fRsudo.DEBUG.NOTICE\fR	
 .PP
-diag	sudo.DEBUG.DIAG	
+diag	\fRsudo.DEBUG.DIAG\fR	
 .PP
-info	sudo.DEBUG.INFO	
+info	\fRsudo.DEBUG.INFO\fR	
 .PP
-trace	sudo.DEBUG.TRACE	
+trace	\fRsudo.DEBUG.TRACE\fR	
 .PP
-debug	sudo.DEBUG.DEBUG	very extreme verbose debugging
+debug	\fRsudo.DEBUG.DEBUG\fR	very extreme verbose debugging
 .TE
 .PP
 \fIUsing the logging module\fR
@@ -1737,11 +1759,11 @@ The log handler of sudo will map each Python log level of a message to
 the appropriate sudo debug level.
 The sudo debug system will only receive messages that are not filtered
 out by the Python loggers.
-For example, the log level of the python logger will be an additional filter
-for the log messages, and is usually very different from what level is set in sudo.conf
-for the sudo debug system.
+For example, the log level of the python logger will be an additional
+filter for the log messages, and is usually very different from
+what level is set in sudo.conf for the sudo debug system.
 .SS "Debug example"
-Sudo ships an example debug plugin by default.
+Sudo ships with an example debug plugin.
 To try it, register it by adding the following lines to
 \fI@sysconfdir@/sudo.conf\fR:
 .nf
@@ -1816,12 +1838,13 @@ This is how the plugin API accepts options and settings.
 .SH "PLUGIN API CHANGELOG (Python)"
 None yet
 .SH "LIMITATIONS"
-Only a maximum number of 8 python I/O plugins can be loaded at once.
+A maximum of 8 python I/O plugins can be loaded at once.
 If
 \fI@sysconfdir@/sudo.conf\fR
 contains more, those will be rejected with a warning message.
 .PP
-The Event API and the hook function API is currently not accessible for Python plugins.
+The Event API and the hook function API is currently not accessible
+for Python plugins.
 .SH "SEE ALSO"
 sudo.conf(@mansectform@),
 sudo_plugin(@mansectform@),
@@ -1849,7 +1872,7 @@ If you believe you have found a bug in
 you can submit a bug report at https://bugzilla.sudo.ws/
 .SH "SECURITY CONSIDERATIONS"
 All Python plugin handling is implemented inside the
-\fRpython_plugin.so\fR
+\fIpython_plugin.so\fR
 dynamic plugin.
 Therefore, if no Python plugin is registered in
 sudo.conf(@mansectform@)
@@ -1875,7 +1898,7 @@ accidentally importing such file would make it possible for any user
 However, during development of a plugin this might not be very convenient.
 The
 sudo.conf(@mansectform@)
-\fRdeveloper_mode\fR
+\fIdeveloper_mode\fR
 option can be used to disable it.
 For example:
 .RS 6n