sudo.8: Some remarks and a patch with editorial changes for this man page

--sneDCHmpScD4ug0z
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

Package: sudo
Version: 1.9.16p2-2
Severity: minor
Tags: patch

   * What led up to the situation?

     Checking for defects with a new version

test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z < "man page"

  [Use 

grep -n -e ' $' -e '\\~$' -e ' \\f.$' -e ' \\"' <file>

  to find (most) trailing spaces.]

  ["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).

  [The fate of "test-nroff" was decided in groff bug #55941.]

   * What was the outcome of this action?

troff:<stdin>:328: warning: start index (-1) of substring out of range, set to 0

   * What outcome did you expect instead?

     No output (no warnings).

-.-

  General remarks and further material, if a diff-file exist, are in the
attachments.


-- System Information:
Debian Release: trixie/sid
  APT prefers testing
  APT policy: (500, 'testing')
Architecture: amd64 (x86_64)

Kernel: Linux 6.12.27-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1), LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)

Versions of packages sudo depends on:
ii  init-system-helpers  1.68
ii  libapparmor1         4.1.0-1
ii  libaudit1            1:4.0.2-2+b2
ii  libc6                2.41-7
ii  libpam-modules       1.7.0-3
ii  libpam0g             1.7.0-3
ii  libselinux1          3.8.1-1
ii  libssl3t64           3.5.0-1
ii  zlib1g               1:1.3.dfsg+really1.3.1-1+b1

sudo recommends no packages.

sudo suggests no packages.

-- Configuration Files:
/etc/sudoers [Errno 13] Permission denied: '/etc/sudoers'
/etc/sudoers.d/README [Errno 13] Permission denied: '/etc/sudoers.d/README'

-- no debconf information

--sneDCHmpScD4ug0z
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="chk_man.err.sudo.8"

Input file is sudo.8

Output from "mandoc -T lint  sudo.8": (shortened list)

      1 operating system explicitly specified
      1 referenced manual not found

-.-.

Output from
test-nroff -mandoc -t -ww -z sudo.8: (shortened list)

      1 start index (-1) of substring out of range, set to 0

-.-.

Wrong distance (not two spaces) between sentences in the input file.

  Separate the sentences and subordinate clauses; each begins on a new
line.  See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").

  The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.

Remember coding: Only one command ("sentence") on each (logical) line.

E-mail: Easier to quote exactly the relevant lines.

Generally: Easier to edit the sentence.

Patches: Less unaffected text.

Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.

  The amount of space between sentences in the output can then be
controlled with the ".ss" request.

Mark a final abbreviation point as such by suffixing it with "\&".

Some sentences (etc.) do not begin on a new line.

Split (sometimes) lines after a punctuation mark; before a conjunction.

  Lines with only one (or two) space(s) between sentences could be split,
so latter sentences begin on a new line.

Use

#!/usr/bin/sh

sed -e '/^\./n' \
-e 's/\([[:alpha:]]\)\.  */\1.\n/g' $1

to split lines after a sentence period.
Check result with the difference between the formatted outputs.
See also the attachment "general.bugs"

1173:checks "." and "" (both denoting current directory) last when

-.-.

Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
Add "\:" to split the string for the output, "\<newline>" in the source.  

Line 1461, length 131

.It Li effective uid is not 0, is sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges?

Line 1510, length 93

.It Li The Do "no new privileges" Dc "flag is set, which prevents sudo from running as root."

Longest line is number 1461 with 131 characters

-.-.

Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".

[List of affected lines removed.]

-.-


Only one space character is after a possible end of sentence
(after a punctuation, that can end a sentence).

sudo.8:1566:.An Todd C. Miller

-.-.

Use "\-" instead of "-" in web addresses.

1619:https://github.com/sudo-project/sudo/issues.
1622:https://www.sudo.ws/mailman/listinfo/sudo-workers (public)
1632:see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or

-.-.

Put a (long) web address on a new output line to reduce the posibility of
splitting the address between two output lines.
Or inhibit hyphenation with "\%" in front of the name.


1559:distribution (https://www.sudo.ws/about/history/) for a brief
1571:distribution (https://www.sudo.ws/about/contributors/) for an
1618:https://bugzilla.sudo.ws/, or open an issue at
1619:https://github.com/sudo-project/sudo/issues.
1622:https://www.sudo.ws/mailman/listinfo/sudo-workers (public)
1629:the key found at https://www.sudo.ws/dist/PGPKEYS.
1632:see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
1643:or https://www.sudo.ws/about/license/ for complete details.

-.-.

Add "\&" after an ellipsis, when it does not end a sentence.

59:.Op Ar command Op Ar arg ...
82:.Op Ar command Op Ar arg ...

-.-.

Output from "test-groff  -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=0 -ww -z ":

troff:<stdin>:328: warning: start index (-1) of substring out of range, set to 0

-.-.

Additionally:

Change '-' to '\-' for an option with two dashes in the output.

Generally:

Split (sometimes) lines after a punctuation mark; before a conjunction.

--sneDCHmpScD4ug0z
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="sudo.8.diff"

--- sudo.8	2025-05-18 01:04:52.661296389 +0000
+++ sudo.8.new	2025-05-18 02:00:59.988610004 +0000
@@ -188,7 +188,7 @@ input and output may be logged as well.
 .Pp
 The options are as follows:
 .Bl -tag -width Ds
-.It Fl A , -askpass
+.It Fl A , \-askpass
 Normally, if
 .Nm
 requires a password, it will read it from the user's terminal.
@@ -215,7 +215,7 @@ If no askpass program is available,
 .Nm
 will exit with an error.
 .if \n(BA \{\
-.It Fl a Ar type , Fl -auth-type Ns = Ns Ar type
+.It Fl a Ar type , Fl \-auth-type Ns = Ns Ar type
 Use the specified
 .Bx
 authentication
@@ -231,10 +231,10 @@ This option is only available on systems
 .Bx
 authentication.
 .\}
-.It Fl B , -bell
+.It Fl B , \-bell
 Ring the bell as part of the password prompt when a terminal is present.
 This option has no effect if an askpass program is used.
-.It Fl b , -background
+.It Fl b , \-background
 Run the given
 .Ar command
 in the background.
@@ -244,7 +244,7 @@ processes started by
 Most interactive
 .Ar command Ns s
 will fail to work properly in background mode.
-.It Fl C Ar num , Fl -close-from Ns = Ns Ar num
+.It Fl C Ar num , Fl \-close-from Ns = Ns Ar num
 Close all file descriptors greater than or equal to
 .Ar num
 before executing a
@@ -264,7 +264,7 @@ option when the administrator has enable
 .Em closefrom_override
 option.
 .if \n(LC \{\
-.It Fl c Ar class , Fl -login-class Ns = Ns Ar class
+.It Fl c Ar class , Fl \-login-class Ns = Ns Ar class
 Run the
 .Ar command
 with resource limits and scheduling priority of the specified login
@@ -296,7 +296,7 @@ This option is only available on systems
 .Bx
 login classes.
 .\}
-.It Fl D Ar directory , Fl -chdir Ns = Ns Ar directory
+.It Fl D Ar directory , Fl \-chdir Ns = Ns Ar directory
 Run the
 .Ar command
 in the specified
@@ -304,19 +304,19 @@ in the specified
 instead of the current working directory.
 The security policy may return an error if the user does not have
 permission to specify the working directory.
-.It Fl E , -preserve-env
+.It Fl E , \-preserve-env
 Indicates to the security policy that the user wishes to
 preserve their existing environment variables.
 The security policy may return an error if the user does not have
 permission to preserve the environment.
-.It Fl -preserve-env=list
+.It Fl \-preserve-env=list
 Indicates to the security policy that the user wishes to add the
 comma-separated list of environment variables to those preserved
 from the user's environment.
 The security policy may return an error if the user does not have
 permission to preserve the environment.
 This option may be specified multiple times.
-.It Fl e , -edit
+.It Fl e , \-edit
 Edit one or more
 .Ar file Ns s
 instead of running a
@@ -325,7 +325,7 @@ In lieu of a path name, the string "sudo
 the security policy.
 If the user is authorized by the policy, the following steps are
 taken:
-.Bl -enum -offset 4
+.Bl -enum -offset 4m
 .It
 Temporary copies are made of the files to be edited with the owner
 set to the invoking user.
@@ -383,7 +383,7 @@ If, for some reason,
 is unable to update a file with its edited version, the user will
 receive a warning and the edited copy will remain in a temporary
 file.
-.It Fl g Ar group , Fl -group Ns = Ns Ar group
+.It Fl g Ar group , Fl \-group Ns = Ns Ar group
 Run the
 .Ar command
 with the primary group set to
@@ -420,15 +420,15 @@ the
 option as long as the
 .Fl P
 option is not in use.
-.It Fl H , -set-home
+.It Fl H , \-set-home
 Request that the security policy set the
 .Ev HOME
 environment variable to the home directory specified by the target
 user's password database entry.
 Depending on the policy, this may be the default behavior.
-.It Fl h , -help
+.It Fl h , \-help
 Display a short help message to the standard output and exit.
-.It Fl h Ar host , Fl -host Ns = Ns Ar host
+.It Fl h Ar host , Fl \-host Ns = Ns Ar host
 Run the
 .Ar command
 on the specified
@@ -442,7 +442,7 @@ plugin does not currently support runnin
 This may also be used in conjunction with the
 .Fl l
 option to list a user's privileges for the remote host.
-.It Fl i , -login
+.It Fl i , \-login
 Run the shell specified by the target user's password database entry
 as a login shell.
 This means that login-specific resource files such as
@@ -492,7 +492,7 @@ option affects the environment in which
 is run when the
 .Em sudoers
 policy is in use.
-.It Fl K , -remove-timestamp
+.It Fl K  \-remove-timestamp
 Similar to the
 .Fl k
 option, except that it removes every cached credential for the user,
@@ -508,7 +508,7 @@ option in conjunction with a
 or other option.
 This option does not require a password.
 Not all security policies support credential caching.
-.It Fl k , -reset-timestamp
+.It Fl k , \-reset-timestamp
 When used without a
 .Ar command ,
 invalidates the user's cached credentials for the current session.
@@ -548,7 +548,7 @@ will prompt for a password (if one is re
 policy) and will not update the user's cached credentials.
 .Pp
 Not all security policies support credential caching.
-.It Fl l , Fl -list
+.It Fl l , Fl \-list
 If no
 .Ar command
 is specified, list the privileges for the invoking user (or the
@@ -581,7 +581,7 @@ If a
 is specified but not allowed by the policy,
 .Nm
 will exit with a status value of 1.
-.It Fl N , -no-update
+.It Fl N , \-no-update
 Do not update the user's cached credentials, even if the user successfully
 authenticates.
 Unlike the
@@ -594,14 +594,14 @@ sudo -Nnv
 .Ed
 .Pp
 Not all security policies support credential caching.
-.It Fl n , -non-interactive
+.It Fl n , \-non-interactive
 Avoid prompting the user for input of any kind.
 If a password is required for the
 .Ar command
 to run,
 .Nm
 will display an error message and exit.
-.It Fl P , -preserve-groups
+.It Fl P , \-preserve-groups
 Preserve the invoking user's group vector unaltered.
 By default, the
 .Em sudoers
@@ -609,7 +609,7 @@ policy will initialize the group vector
 target user is a member of.
 The real and effective group-IDs, however, are still set to match
 the target user.
-.It Fl p Ar prompt , Fl -prompt Ns = Ns Ar prompt
+.It Fl p Ar prompt , Fl \-prompt Ns = Ns Ar prompt
 Use a custom password prompt with optional escape sequences.
 The following percent
 .Pq Ql %
@@ -659,7 +659,7 @@ specified by a PAM module unless the
 .Em passprompt_override
 flag is disabled in
 .Em sudoers .
-.It Fl R Ar directory , Fl -chroot Ns = Ns Ar directory
+.It Fl R Ar directory , Fl \-chroot Ns = Ns Ar directory
 Change to the specified root
 .Ar directory
 (see
@@ -669,16 +669,16 @@ before running the
 The security policy may return an error if the user does not have
 permission to specify the root directory.
 .if \n(SL \{\
-.It Fl r Ar role , Fl -role Ns = Ns Ar role
+.It Fl r Ar role , Fl \-role Ns = Ns Ar role
 Run the
 .Ar command
 with an SELinux security context that includes the specified
 .Ar role .
 .\}
-.It Fl S , -stdin
+.It Fl S , \-stdin
 Write the prompt to the standard error and read the password from the
 standard input instead of using the terminal device.
-.It Fl s , -shell
+.It Fl s , \-shell
 Run the shell specified by the
 .Ev SHELL
 environment variable if it is set or the shell specified by the
@@ -706,7 +706,7 @@ Most shells behave differently when a
 is specified as compared to an interactive session; consult the shell's manual
 for details.
 .if \n(SL \{\
-.It Fl t Ar type , Fl -type Ns = Ns Ar type
+.It Fl t Ar type , Fl \-type Ns = Ns Ar type
 Run the
 .Ar command
 with an SELinux security context that includes the specified
@@ -715,7 +715,7 @@ If no
 .Ar type
 is specified, the default type is derived from the role.
 .\}
-.It Fl U Ar user , Fl -other-user Ns = Ns Ar user
+.It Fl U Ar user , Fl \-other-user Ns = Ns Ar user
 Used in conjunction with the
 .Fl l
 option to list the privileges for
@@ -735,7 +735,7 @@ or the ability to run any
 as root or
 .Ar user
 on the current host.
-.It Fl T Ar timeout , Fl -command-timeout Ns = Ns Ar timeout
+.It Fl T Ar timeout , Fl \-command-timeout Ns = Ns Ar timeout
 Used to set a timeout for the
 .Ar command .
 If the timeout expires before the
@@ -747,7 +747,7 @@ The security policy may restrict the use
 The
 .Em sudoers
 policy requires that user-specified timeouts be explicitly enabled.
-.It Fl u Ar user , Fl -user Ns = Ns Ar user
+.It Fl u Ar user , Fl \-user Ns = Ns Ar user
 Run the
 .Ar command
 as a user other than the default target user (usually
@@ -775,7 +775,7 @@ policy allows UIDs that are not in the p
 .Em targetpw
 option is not set.
 Other security policies may not support this.
-.It Fl V , -version
+.It Fl V , \-version
 Print the
 .Nm
 version string as well as the version string of any configured plugins.
@@ -785,7 +785,7 @@ option will display the options passed t
 .Nm
 was built; plugins may display additional information such as
 default options.
-.It Fl v , -validate
+.It Fl v , \-validate
 Update the user's cached credentials, authenticating the user
 if necessary.
 For the

--sneDCHmpScD4ug0z
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="general.bugs"

  Any program (person), that produces man pages, should check the output
for defects by using (both groff and nroff)

[gn]roff -mandoc -t -ww -b -z -K utf8 <man page>

  To find trailing space use

grep -n -e ' $' -e ' \\f.$' -e ' \\"' <man page>

  The same goes for man pages that are used as an input.

  For a style guide use

  mandoc -T lint

-.-

  Any "autogenerator" should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.

  It should also check its input files for too long (> 80) lines.

  This is just a simple quality control measure.

  The "autogenerator" may have to be corrected to get a better man page,
the source file may, and any additional file may.

  Common defects:

  Not removing trailing spaces (in in- and output).
  The reason for these trailing spaces should be found and eliminated.

  "git" has a "tool" to point out whitespace,
see for example "git-apply(1)" and git-config(1)")

  Not beginning each input sentence on a new line.
Line length and patch size should thus be reduced.

  The script "reportbug" uses 'quoted-printable' encoding when a line is
longer than 1024 characters in an 'ascii' file.

  See man-pages(7), item "semantic newline".

-.-

The difference between the formatted output of the original and patched file
can be seen with:

  nroff -mandoc <file1> > <out1>
  nroff -mandoc <file2> > <out2>
  diff -d -u <out1> <out2>

and for groff, using

\"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - \"

instead of 'nroff -mandoc'

  Add the option '-t', if the file contains a table.

  Read the output from 'diff -d -u ...' with 'less -R' or similar.

-.-.

  If 'man' (man-db) is used to check the manual for warnings,
the following must be set:

  The option "-warnings=w"

  The environmental variable:

export MAN_KEEP_STDERR=yes (or any non-empty value)

  or

  (produce only warnings):

export MANROFFOPT="-ww -b -z"

export MAN_KEEP_STDERR=yes (or any non-empty value)

-.-

--sneDCHmpScD4ug0z
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: inline

____________________________________________________________
sudo-workers mailing list <[email protected]>
For list information, options, or to unsubscribe, visit:
https://www.sudo.ws/mailman/listinfo/sudo-workers

--sneDCHmpScD4ug0z--