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

Also reword a few awkward phrases.

2 files changed, 237 insertions, 193 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
diff --git a/docs/sudo_plugin_python.mdoc.in b/docs/sudo_plugin_python.mdoc.in
index 111bed672..e17e1d272 100644
--- a/docs/sudo_plugin_python.mdoc.in
+++ b/docs/sudo_plugin_python.mdoc.in
@@ -16,7 +16,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd June 6, 2022
+.Dd September 11, 2022
 .Dt SUDO_PLUGIN_PYTHON @mansectform@
 .Os Sudo @PACKAGE_VERSION@
 .Sh NAME
@@ -85,9 +85,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
-.Dq int
+.Vt int
 result code, as documented in
-.Xr sudo_plugin @mansectsu@ ,
+.Xr sudo_plugin @mansectform@ ,
 that indicates whether or not the method was successful.
 The Python sudo module defines the following constants to improve readability:
 .Bl -column "sudo.RC.USAGE_ERROR" "XXX" -offset 4n
@@ -100,12 +100,12 @@ The Python sudo module defines the following constants to improve readability:
 .El
 .Pp
 If a function returns
-.Em None
+.Dv None
 (for example, if it does not call return),
 it will be considered to have returned
 .Dv sudo.RC.OK .
-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
 .Dv sudo.RC.ERROR .
 If that is not acceptable, you must catch the exception and handle it yourself.
 .Pp
@@ -128,7 +128,7 @@ Running the Python interpreter and bridging between C and Python is
 handled by the
 .Nm sudo
 plugin
-.Li python_plugin.so .
+.Pa python_plugin.so .
 This shared object can be loaded like any other dynamic
 .Nm sudo
 plugin and should receive the path and the class name of the Python
@@ -187,8 +187,8 @@ Currently, only a single policy plugin may be specified in
 .Pp
 A policy plugin may have the following member functions:
 .Bl -tag -width 4n
-.It Sy constructor
-.Bd -literal
+.It Fa constructor
+.Bd -literal -compact
 __init__(self, user_env: Tuple[str, ...], settings: Tuple[str, ...],
     version: str, user_info: Tuple[str, ...],
     plugin_options: Tuple[str, ...])
@@ -200,7 +200,9 @@ as member variables in the object.
 .Pp
 The constructor matches the
 .Fn open
-function in the C sudo plugin API.
+function in the C
+.Nm sudo
+plugin API.
 .Pp
 The function arguments are as follows:
 .Bl -tag -width 4n
@@ -239,7 +241,7 @@ see the policy plugin
 .Fn open
 documentation in
 .Xr sudo_plugin @mansectform@ .
-.It Sy check_policy
+.It Fa check_policy
 .Bd -literal -compact
 check_policy(self, argv: Tuple[str, ...], env_add: Tuple[str, ...])
 .Ed
@@ -314,7 +316,7 @@ tuple of strings in
 .Dq key=value
 format.
 .El
-.It Sy init_session
+.It Fa init_session
 .Bd -literal -compact
 init_session(self, user_pwd: Tuple, user_env: Tuple[str, ...])
 .Ed
@@ -331,8 +333,9 @@ The function arguments are as follows:
 .Bl -tag -width 4n
 .It Fa user_pwd
 A tuple describing the user's passwd entry.
-Convertible to pwd.struct_passwd or
-.Em None
+Convertible to
+.Vt pwd.struct_passwd or
+.Dv None
 if the user is not present in the password database.
 .Pp
 Example conversion:
@@ -371,7 +374,7 @@ environment in
 If this is omitted, no changes will be made to
 .Fa user_env .
 .El
-.It Sy list
+.It Fa list
 .Bd -literal -compact
 list(self, argv: Tuple[str, ...], is_verbose: int, user: str)
 .Ed
@@ -382,7 +385,7 @@ The function arguments are as follows:
 .Bl -tag -width 4n
 .It Fa argv
 If not set to
-.Em None ,
+.Dv None ,
 an argument vector describing a command the user wishes to check
 against the policy.
 .It Fa is_verbose
@@ -390,16 +393,16 @@ Flag indicating whether to list in verbose mode or not.
 .It Fa user
 The name of a different user to list privileges for if the policy allows it.
 If
-.Em None ,
+.Dv None ,
 the plugin should list the privileges of the invoking user.
 .El
-.It Sy validate
+.It Fa validate
 .Bd -literal -compact
 validate(self)
 .Ed
 .Pp
 For policy plugins that cache authentication credentials, this function is used to validate and cache the credentials (optional).
-.It Sy invalidate
+.It Fa invalidate
 .Bd -literal -compact
 invalidate(self, remove: int)
 .Ed
@@ -412,7 +415,7 @@ The function arguments are as follows:
 If this flag is set, the plugin may remove the credentials instead of simply
 invalidating them.
 .El
-.It Sy show_version
+.It Fa show_version
 .Bd -literal -compact
 show_version(self, is_verbose: int)
 .Ed
@@ -430,7 +433,7 @@ Currently this is 1 if
 .Ql sudo -V
 is run as the root user.
 .El
-.It Sy close
+.It Fa close
 .Bd -literal -compact
 close(self, exit_status: int, error: int)
 .Ed
@@ -439,7 +442,9 @@ Called when a command finishes executing.
 .Pp
 Works the same as the
 .Fn close
-function in the C sudo plugin API, except that it only gets called if
+function in the C
+.Nm sudo
+plugin API, except that it only gets called if
 .Nm sudo
 attempts to execute the command.
 .Pp
@@ -464,8 +469,10 @@ Plugin python_policy python_plugin.so \e
     ClassName=SudoPolicyPlugin
 .Ed
 .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
+.Pa @sysconfdir@/sudo.conf ,
+such as
 .Xr sudoers @mansectform@ .
 .Ss I/O plugin API
 I/O plugins must be registered in
@@ -480,7 +487,7 @@ Currently only 8 python I/O plugins can be loaded at once.
 .Pp
 An I/O plugin may have the following member functions:
 .Bl -tag -width 4n
-.It Sy constructor
+.It Fa constructor
 .Bd -literal -compact
 __init__(self, user_env: Tuple[str, ...], settings: Tuple[str, ...],
     version: str, user_info: Tuple[str, ...],
@@ -493,7 +500,9 @@ as member variables in the object.
 .Pp
 The constructor matches the
 .Fn open
-function in the C sudo plugin API.
+function in the C
+.Nm sudo
+plugin API.
 .Pp
 The function arguments are as follows:
 .Bl -tag -width 4n
@@ -532,7 +541,7 @@ see the I/O plugin
 .Fn open
 documentation in
 .Xr sudo_plugin @mansectform@ .
-.It Sy open
+.It Fa open
 .Bd -literal -compact
 open(self, argv: Tuple[str, ...],
     command_info: Tuple[str, ...]) -> int
@@ -542,11 +551,13 @@ Receives the command the user wishes to run.
 .Pp
 Works the same as the
 .Fn open
-function in the C sudo plugin API except that:
+function in the C
+.Nm sudo
+plugin API except that:
 .Pp
 .Bl -bullet -compact -offset 4n -width 1n
 .It
-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).
 .It
 Other arguments of the C API
@@ -583,7 +594,7 @@ constants.
 If the function returns
 .Dv sudo.RC.REJECT ,
 no I/O will be sent to the plugin.
-.It Sy log_ttyin , log_ttyout , log_stdin , log_stdout , log_stderr
+.It Fa log_ttyin , log_ttyout , log_stdin , log_stdout , log_stderr
 .Bd -literal -compact
 log_ttyin(self, buf: str) -> int
 log_ttyout(self, buf: str) -> int
@@ -609,8 +620,8 @@ constants.
 .Pp
 If
 .Dv sudo.RC.ERROR
-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.
 .Pp
@@ -622,7 +633,7 @@ If an output logging function rejects the data by returning
 .Dv sudo.RC.REJECT ,
 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.
-.It Sy change_winsize
+.It Fa change_winsize
 .Bd -literal -compact
 change_winsize(self, line: int, cols: int) -> int
 .Ed
@@ -635,7 +646,7 @@ The number of lines of the terminal.
 .It Fa cols
 The number of columns of the terminal.
 .El
-.It Sy log_suspend
+.It Fa log_suspend
 .Bd -literal -compact
 log_suspend(self, signo: int) -> int
 .Ed
@@ -648,7 +659,7 @@ The number of the signal that caused the command to be suspended or
 .Dv SIGCONT
 if the command was resumed.
 .El
-.It Sy show_version
+.It Fa show_version
 .Bd -literal -compact
 show_version(self, is_verbose: int)
 .Ed
@@ -665,15 +676,17 @@ Currently this is 1 if
 .Ql sudo -V
 is run as the root user.
 .El
-.It Sy close
+.It Fa close
 .Bd -literal -compact
 close(self, exit_status: int, error: int) -> None
 .Ed
-Called when a command execution finished.
+Called when a command finishes execution.
 .Pp
 Works the same as the
 .Fn close
-function in the C sudo plugin API, except that it only gets called if
+function in the C
+.Nm sudo
+plugin API, except that it only gets called if
 .Nm sudo
 attempts to execute the command.
 .Pp
@@ -689,7 +702,7 @@ system call, otherwise 0.
 .El
 .El
 .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
 .Pa @sysconfdir@/sudo.conf :
 .Bd -literal -offset 4n
@@ -708,9 +721,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):
 .Bl -tag -width 4n
-.It Sy constructor
+.It Fa constructor
 .Bd -literal -compact
 __init__(self, user_env: Tuple[str, ...], settings: Tuple[str, ...],
     version: str, user_info: Tuple[str, ...], plugin_options: Tuple[str, ...])
@@ -721,7 +734,9 @@ as member variables in the object.
 .Pp
 The constructor matches the
 .Fn open
-function in the C sudo plugin API.
+function in the C
+.Nm sudo
+plugin API.
 .Pp
 The function arguments are as follows:
 .Bl -tag -width 4n
@@ -749,7 +764,7 @@ This is a tuple of strings, usually (but not necessarily) in
 .Dq key=value
 format.
 .El
-.It Sy open
+.It Fa open
 .Bd -literal -compact
 open(self, submit_optind: int,
     submit_argv: Tuple[str, ...]) -> int
@@ -764,7 +779,7 @@ that corresponds to the first entry that is not a command line option.
 .It Fa submit_argv
 The argument vector sudo was invoked with, including all command line options.
 .El
-.It Sy close
+.It Fa close
 .Bd -literal -compact
 close(self, status_type: int, status: int) -> None
 .Ed
@@ -775,7 +790,9 @@ The function arguments are as follows:
 .Bl -tag -width 4n
 .It Fa status_type
 The type of status being passed.
-One of the sudo.EXIT_REASON.* constants.
+One of the
+.Dv sudo.EXIT_REASON.*
+constants.
 .It Fa status
 Depending on the value of
 .Fa status_type ,
@@ -783,16 +800,16 @@ this value is either
 ignored, the command's exit status as returned by the
 .Xr wait 2
 system call, the value of
-.Li errno
+.Va errno
 set by the
 .Xr execve 2
 system call, or the value of
-.Li errno
+.Va errno
 resulting from an error in the
 .Nm sudo
 front-end.
 .El
-.It Sy show_version
+.It Fa show_version
 .Bd -literal -compact
 show_version(self, is_verbose: int) -> int
 .Ed
@@ -810,7 +827,7 @@ Currently this is 1 if
 .Ql sudo -V
 is run as the root user.
 .El
-.It Sy accept
+.It Fa accept
 .Bd -literal -compact
 accept(self, plugin_name: str, plugin_type: int, command_info: Tuple[str, ...],
        run_argv: Tuple[str, ...], run_envp: Tuple[str, ...]) -> int
@@ -863,7 +880,7 @@ Argument vector describing a command that will be run.
 .It run_envp
 The environment the command will be run with.
 .El
-.It Sy reject
+.It Fa reject
 .Bd -literal -compact
 reject(self, plugin_name: str, plugin_type: int, audit_msg: str,
        command_info: Tuple[str, ...]) -> int
@@ -892,15 +909,14 @@ front-end.
 .It 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
-.Em None
-.
+.Dv None .
 .It command_info
 A vector of information describing the rejected command.
 See the
 .Xr sudo_plugin @mansectform@
 manual for possible values.
 .El
-.It Sy error
+.It Fa error
 .Bd -literal -compact
 error(self, plugin_name: str, plugin_type: int, audit_msg: str,
       command_info: Tuple[str, ...]) -> int
@@ -926,8 +942,7 @@ front-end.
 .It audit_msg
 An optional string describing the plugin error.
 If the plugin did not provide a description, it will be
-.Em None
-.
+.Dv None .
 .It command_info
 A vector of information describing the command.
 See the
@@ -936,7 +951,7 @@ manual for possible values.
 .El
 .El
 .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
 .Pa @sysconfdir@/sudo.conf :
 .Bd -literal -offset 4n
@@ -959,7 +974,7 @@ Currently only 8 python approval plugins can be loaded at once.
 .Pp
 An approval plugin may have the following member functions:
 .Bl -tag -width 4n
-.It Sy constructor
+.It Fa constructor
 .Bd -literal -compact
 __init__(self, user_env: Tuple[str, ...], settings: Tuple[str, ...],
     version: str, user_info: Tuple[str, ...], plugin_options: Tuple[str, ...],
@@ -972,7 +987,9 @@ as member variables in the object.
 .Pp
 The constructor matches the
 .Fn open
-function in the C sudo plugin API.
+function in the C
+.Nm sudo
+plugin API.
 .Pp
 The function arguments are as follows:
 .Bl -tag -width 4n
@@ -1006,13 +1023,14 @@ that corresponds to the first entry that is not a command line option.
 .It Fa submit_argv
 The argument vector sudo was invoked with, including all command line options.
 .El
-.It Sy show_version
+.It Fa show_version
 .Bd -literal -compact
 show_version(self, is_verbose: int) -> int
 .Ed
 .Pp
-Display the version. (Same as for all the other plugins.)
-.It Sy check
+Display the version.
+(Same as for all the other plugins.)
+.It Fa check
 .Bd -literal -compact
 check(self, command_info: Tuple[str, ...], run_argv: Tuple[str, ...],
       run_env: Tuple[str, ...]) -> int
@@ -1042,7 +1060,7 @@ The environment the command will be run with.
 .El
 .El
 .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
 .Pa @sysconfdir@/sudo.conf :
 .Bd -literal -offset 4n
@@ -1067,7 +1085,7 @@ Currently, only a single group plugin can be registered in
 .Pp
 A group provider plugin may have the following member functions:
 .Bl -tag -width 4n
-.It Sy constructor
+.It Fa constructor
 .Bd -literal -compact
 __init__(self, args: Tuple[str, ...], version: str)
 .Ed
@@ -1088,7 +1106,7 @@ format).
 .It Fa version
 The version of the Python Group Plugin API.
 .El
-.It Sy query
+.It Fa query
 .Bd -literal -compact
 query(self, user: str, group: str, user_pwd: Tuple)
 .Ed
@@ -1118,7 +1136,7 @@ will be
 .Dv NULL .
 .El
 .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
 .Em sudoers
 file by adding the following lines:
@@ -1132,7 +1150,7 @@ The example plugin will tell
 .Nm sudo
 that the user
 .Em test
-is part of the non-unix group
+is part of the non-Unix group
 .Em mygroup .
 If you add a rule that uses this group, it will affect the
 .Em test
@@ -1154,22 +1172,24 @@ written in Python.
 A Python plugin can interact with the user using the
 .Fn sudo.conv
 function which displays one or more messages described by the
-.Sy sudo.ConvMessage
+.Dv sudo.ConvMessage
 class.
 This is the Python equivalent of the
 .Fn conversation
-function in the C sudo plugin API.
+function in the C
+.Nm sudo
+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
-.Sy sudo.ConvMessage
+.Dv sudo.ConvMessage
 class specifies how the user interaction should occur:
 .Bd -literal -offset 4n
 sudo.ConvMessage(msg_type: int, msg: str, timeout: int)
 .Ed
 .Pp
-.Sy sudo.ConvMessage
+.Dv sudo.ConvMessage
 member variables:
 .Bl -tag -width 4n
 .It Fa msg_type
@@ -1180,7 +1200,7 @@ constants below.
 .It Fa msg
 The message to display to the user.
 The caller must include a trailing newline in
-.Li msg
+.Fa msg
 if one is to be displayed.
 .It Fa timeout
 Optional.
@@ -1197,19 +1217,19 @@ To specify the message type, the following constants are available:
 .Pp
 .Bl -bullet -compact -offset 4n -width 1n
 .It
-sudo.CONV.PROMPT_ECHO_OFF
+.Dv sudo.CONV.PROMPT_ECHO_OFF
 .It
-sudo.CONV.PROMPT_ECHO_ON
+.Dv sudo.CONV.PROMPT_ECHO_ON
 .It
-sudo.CONV.ERROR_MSG
+.Dv sudo.CONV.ERROR_MSG
 .It
-sudo.CONV.INFO_MSG
+.Dv sudo.CONV.INFO_MSG
 .It
-sudo.CONV.PROMPT_MASK
+.Dv sudo.CONV.PROMPT_MASK
 .It
-sudo.CONV.PROMPT_ECHO_OK
+.Dv sudo.CONV.PROMPT_ECHO_OK
 .It
-sudo.CONV.PREFER_TTY
+.Dv sudo.CONV.PREFER_TTY
 .El
 .Pp
 See the
@@ -1228,7 +1248,7 @@ The function arguments are as follows:
 .Bl -tag -width 4n
 .It Fa message(s)
 One of more messages (of type
-.Sy sudo.ConvMessage ) ,
+.Dv sudo.ConvMessage ) ,
 each describing a conversation.
 At least one message is required.
 .It Fa on_suspend
@@ -1247,10 +1267,10 @@ The
 .Fn sudo.conv
 function can raise the following exceptions:
 .Bl -tag -width 4n
-.It Sy sudo.SudoException
+.It Dv sudo.SudoException
 If the conversation fails, for example when the conversation function is not
 available.
-.It Sy sudo.ConversationInterrupted
+.It Dv sudo.ConversationInterrupted
 If the conversation function returns an error, e.g., the timeout passed
 or the user interrupted the conversation by pressing control-C.
 .El
@@ -1305,7 +1325,7 @@ debug system.
 .Em Enabling debugging in sudo.conf
 .Pp
 To enable debug messages, add a
-.Li Debug
+.Em Debug
 line to
 .Xr sudo.conf @mansectform@
 with the program set to
@@ -1380,14 +1400,14 @@ one or more messages to log
 .Em Available log levels:
 .Bl -column "name in sudo.conf" "Python constant" "only critical messages"
 .It Sy sudo.conf name Ta Sy Python constant Ta Sy description
-.It crit Ta sudo.DEBUG.CRIT Ta only critical messages
-.It err Ta sudo.DEBUG.ERROR Ta
-.It warn Ta sudo.DEBUG.WARN Ta
-.It notice Ta sudo.DEBUG.NOTICE Ta
-.It diag Ta sudo.DEBUG.DIAG Ta
-.It info Ta sudo.DEBUG.INFO Ta
-.It trace Ta sudo.DEBUG.TRACE Ta
-.It debug Ta sudo.DEBUG.DEBUG Ta very extreme verbose debugging
+.It crit Ta Dv sudo.DEBUG.CRIT Ta only critical messages
+.It err Ta Dv sudo.DEBUG.ERROR Ta
+.It warn Ta Dv sudo.DEBUG.WARN Ta
+.It notice Ta Dv sudo.DEBUG.NOTICE Ta
+.It diag Ta Dv sudo.DEBUG.DIAG Ta
+.It info Ta Dv sudo.DEBUG.INFO Ta
+.It trace Ta Dv sudo.DEBUG.TRACE Ta
+.It debug Ta Dv sudo.DEBUG.DEBUG Ta very extreme verbose debugging
 .El
 .Pp
 .Em Using the logging module
@@ -1400,11 +1420,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
 .Pa @sysconfdir@/sudo.conf :
 .Bd -literal -offset 4n
@@ -1470,12 +1490,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
 .Pa @sysconfdir@/sudo.conf
 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
 .Xr sudo.conf @mansectform@ ,
 .Xr sudo_plugin @mansectform@ ,
@@ -1502,7 +1523,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
-.Li python_plugin.so
+.Pa python_plugin.so
 dynamic plugin.
 Therefore, if no Python plugin is registered in
 .Xr sudo.conf @mansectform@
@@ -1528,7 +1549,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
 .Xr sudo.conf @mansectform@
-.Li developer_mode
+.Em developer_mode
 option can be used to disable it.
 For example:
 .Dl Set developer_mode true