Tidy up some of the automated formatting.upstream-master

doc/mkmd.sh also has some dependencies on the format of the man
pages, so make that work again.

Signed-off-by: Andrew G. Morgan <morgan@kernel.org>

3 files changed, 69 insertions, 41 deletions

diff --git a/doc/capability.conf.5 b/doc/capability.conf.5
index 15535f4..63f3230 100644
--- a/doc/capability.conf.5
+++ b/doc/capability.conf.5
@@ -12,74 +12,63 @@ The syntax for lines in this configuration file is:
 .P
 \fB<IAB><SPACE><WHO>\fR
 .P
-Where \fB<IAB>\fR refers to the text format for an inheritable IAB capability tuple, or the words \fBall\fR or \fBnone\fR\.
+Where \fB<IAB>\fR refers to the text format for an inheritable IAB
+capability tuple,
+.BR cap_iab (3)
+, or the words \fBall\fR or \fBnone\fR\.
 .P
-The reserved word \fBall\fR does \fInot\fR grant \fIall the inheritable capabilities\fR, but acts as a simple \fIpass\-through\fR for any prevailing IAB tuple capabilities\. The reserved word \fBnone\fR refers to an empty \fIInheritable\fR capability set (and by extension an empty \fIAmbient\fR vector)\.
+The reserved word \fBall\fR does \fInot\fR grant \fIall the
+inheritable capabilities\fR, but acts as a simple \fIpass\-through\fR
+for any prevailing IAB tuple capabilities\. The reserved word
+\fBnone\fR refers to an empty \fIInheritable\fR capability set (and by
+extension an empty \fIAmbient\fR vector)\.
 .P
-Here \fB<WHO>\fR refers to the space separated PAM username values that will be granted the specified \fIIAB\fR tuple\. A name prefixed with the character \fB@\fR refers to the locally defined \fB/etc/group\fR \fIetc\fR users listed under that group name\. An asterisk "\fB*\fR" can be used to denote all users\.
+Here \fB<WHO>\fR refers to the space separated PAM username values
+that will be granted the specified \fIIAB\fR tuple\. A name prefixed
+with the character \fB@\fR refers to the locally defined
+\fB/etc/group\fR \fIetc\fR users listed under that group name\. An
+asterisk "\fB*\fR" can be used to denote all users\.
 .P
-The parsing of the file chooses the first line that applies to the authenticating user, and attempts to apply that and only that\.
+The parsing of the file chooses the first line that applies to the
+authenticating user, and attempts to apply that and only that\.
 .P
 Examples of valid syntax are:
 .IP "" 4
 .nf
 # only root gets to keep what it had
-
 all                                root
 
-
 # this should fire for user beta only, who will have
-
 # cap_chown dropped from their bounding set\.
-
 !cap_chown                         beta
 
-
 # the next one should snag the members of the \'three\' group
-
 # granting them cap_setuid and cap_chown
-
 cap_setuid,cap_chown               @three
 
-
 # this would apply to beta and gamma, but beta is already
-
 # granted a lack of cap_chown above\. Further, if gamma is
-
 # in the \'three\' group, it would not reach this line\.
-
 cap_chown                          beta gamma
 
-
 # members of the \'one\' group are granted the cap_setuid Inheritable
-
 # capability, but cap_chown is dropped from their bounding set\.
-
 !cap_chown,cap_setuid              @one
 
-
 # user alpha gets an ambient capability (unless it is also
-
 # a member of the groups \'one\' or \'three\')\.
-
 ^cap_setuid                        alpha
 
-
 # user delta (if not a member of groups \'one\' and \'three\') will get
-
 # cap_chown and cap_setgid Ambient capabilities, but have cap_setuid
-
 # dropped from its bounding set\.
-
 ^cap_chown,^cap_setgid,!cap_setuid delta
 
-
 # any remaining members of group \'four\' will get the cap_setuid
-
 # Inheritable capability\.
-
 cap_setuid                         @four
 .fi
 .IP "" 0
 .SH "SEE ALSO"
-pam_cap(8)
+.BR pam_cap (8),
+.BR cap_iab (3).
diff --git a/doc/mkmd.sh b/doc/mkmd.sh
index ce8baa2..c65c8d5 100755
--- a/doc/mkmd.sh
+++ b/doc/mkmd.sh
@@ -29,7 +29,7 @@ index="${outdir}/index.md"
 function do_page () {
     m="$1"
     base="${m%.*}"
-    sect="${m#*.}"
+    sect="${m##*.}"
     output="${base}-${sect}.md"
 
     echo "converting ${m}" 1>&2
@@ -43,7 +43,7 @@ function do_page () {
 	return
     fi
 
-    pandoc -f man -t markdown < "${m}" | sed 's/\*\*\([^*]\+\)\*\*(\([138]\+\))/[\1(\2)](\1-\2.md)/g' > "${outdir}/${base}-${sect}.md"
+    pandoc -f man -t markdown < "${m}" | sed 's/\*\*\([^*]\+\)\*\*(\([1358]\+\))/[\1(\2)](\1-\2.md)/g' > "${outdir}/${base}-${sect}.md"
     echo "* [${base}(${sect})](${base}-${sect}.md)" >> "${index}"
 }
 
@@ -62,7 +62,7 @@ cat >> "${index}" <<EOF
 EOF
 
 # Assumes the m's are listed alphabetically.
-for n in 1 3 8 ; do
+for n in 1 3 5 8 ; do
 	cat >> "${index}" <<EOF
 
 ### Section ${n}
diff --git a/doc/pam_cap.8 b/doc/pam_cap.8
index 93c1a71..b2a6813 100644
--- a/doc/pam_cap.8
+++ b/doc/pam_cap.8
@@ -6,11 +6,24 @@
 .SH "SYNOPSIS"
 [service\-name] \fBauth\fR control\-flag \fBpam_cap\fR [options]
 .SH "DESCRIPTION"
-The \fBpam_so\fR module can be used to specify \fIInheritable\fR capabilities to process trees rooted in the PAM application\. The module also supports blocking \fIBounding\fR vector capabilities and adding \fIAmbient\fR vector capabilities\.
+The \fBpam_so\fR module can be used to specify \fIInheritable\fR
+capabilities to process trees rooted in the PAM application\. The
+module also supports blocking \fIBounding\fR vector capabilities and
+adding \fIAmbient\fR vector capabilities\.
 .P
-For general PAM apps to work correctly, the application must be run with at least \fBCAP_SETPCAP\fR raised in its \fIPermitted\fR capability flag\. Many PAM applications run as \fIroot\fR, which has all of the bits in the \fIBounding\fR set raised, so this requirement is typically met\. To grant an \fIAmbient\fR vector capability, the corresponding Permitted bit must be available to the application too\.
+For general PAM apps to work correctly, the application must be run
+with at least \fBCAP_SETPCAP\fR raised in its \fIPermitted\fR
+capability flag\. Many PAM applications run as \fIroot\fR, which has
+all of the bits in the \fIBounding\fR set raised, so this requirement
+is typically met\. To grant an \fIAmbient\fR vector capability, the
+corresponding Permitted bit must be available to the application too\.
 .P
-The \fBpam_so\fR module is a Linux\-PAM \fIauth\fR module\. It provides functionality to back \fBpam_sm_authenticate()\fR and \fBpam_sm_setcred()\fR\. It is the latter that actually modifies the inheritable 3\-tuple of capability vectors: the configured \fIIAB\fR\. In a typical application configuration you might have a line like this:
+The \fBpam_so\fR module is a Linux\-PAM \fIauth\fR module\. It
+provides functionality to back \fBpam_sm_authenticate()\fR and
+\fBpam_sm_setcred()\fR\. It is the latter that actually modifies the
+inheritable 3\-tuple of capability vectors: the configured
+\fIIAB\fR\. In a typical application configuration you might have a
+line like this:
 .IP "" 4
 .nf
 auth    optional    pam_cap\.so
@@ -21,15 +34,41 @@ The module arguments are:
 .IP "\[ci]" 4
 \fBdebug\fR: While supported, this is a no\-op at present\.
 .IP "\[ci]" 4
-\fBconfig=\fR\fI/path/to/file\fR: Override the default config for the module\. The unspecified default value for this file is \fB/etc/security/capability\.conf\fR\. Note, \fBconfig=/dev/null\fR is a valid value\. See \fBdefault=\fR below for situations in which this might be appropriate\.
+\fBconfig=\fR\fI/path/to/file\fR: Override the default config for the
+module\. The unspecified default value for this file is
+\fB/etc/security/capability\.conf\fR\. Note, \fBconfig=/dev/null\fR is
+a valid value\. See \fBdefault=\fR below for situations in which this
+might be appropriate\.
 .IP "\[ci]" 4
-\fBkeepcaps\fR: This is as much as the \fBpam_cap\.so\fR module can do to help an application support use of the \fIAmbient\fR capability vector\. The application support for the \fIAmbient\fR set is poor at the present time\.
+\fBkeepcaps\fR: This is as much as the \fBpam_cap\.so\fR module can do
+to help an application support use of the \fIAmbient\fR capability
+vector\. The application support for the \fIAmbient\fR set is poor at
+the present time\.
 .IP "\[ci]" 4
-\fBautoauth\fR: This argument causes the \fBpam_cap\.so\fR module to return \fBPAM_SUCCESS\fR if the \fBPAM_USER\fR being authenticated exists\. The absence of this argument will cause \fBpam_cap\.so\fR to only return \fBPAM_SUCCESS\fR if the \fBPAM_USER\fR is covered by a specific rule in the prevailing config file\.
+\fBautoauth\fR: This argument causes the \fBpam_cap\.so\fR module to
+return \fBPAM_SUCCESS\fR if the \fBPAM_USER\fR being authenticated
+exists\. The absence of this argument will cause \fBpam_cap\.so\fR to
+only return \fBPAM_SUCCESS\fR if the \fBPAM_USER\fR is covered by a
+specific rule in the prevailing config file\.
 .IP "\[ci]" 4
-\fBdefault=\fR\fIIAB\fR: This argument is ignored if the prevailing configuration file contains a "\fB*\fR" rule\. If there is no such rule, the \fIIAB\fR 3\-tuple is inserted at the end of the config file and applies to all \fBPAM_USER\fRs not covered by an earlier rule\. Note, if you want all \fBPAM_USER\fRs to be covered by this default rule, you can supply the module argument \fBconfig=/dev/null\fR\.
+\fBdefault=\fR\fIIAB\fR: This argument is ignored if the prevailing
+configuration file contains a "\fB*\fR" rule\. If there is no such
+rule, the \fIIAB\fR 3\-tuple is inserted at the end of the config file
+and applies to all \fBPAM_USER\fRs not covered by an earlier
+rule\. Note, if you want all \fBPAM_USER\fRs to be covered by this
+default rule, you can supply the module argument
+\fBconfig=/dev/null\fR\.
 .IP "\[ci]" 4
-\fBdefer\fR: This argument arranges for the \fIIAB\fR capabilities granted to a user to be added sufficiently late in the Linux\-PAM authentication stack that they stick\. That is, \fIafter\fR the application does its \fBsetuid(UID)\fR call\. As such, in conjunction with the \fBkeepcaps\fR module argument, such compliant applications can support granting \fIAmbient\fR vector capabilities with \fBpam_cap\.so\fR\.
+\fBdefer\fR: This argument arranges for the \fIIAB\fR capabilities
+granted to a user to be added sufficiently late in the Linux\-PAM
+authentication stack that they stick\. That is, \fIafter\fR the
+application does its \fBsetuid(UID)\fR call\. As such, in conjunction
+with the \fBkeepcaps\fR module argument, such compliant applications
+can support granting \fIAmbient\fR vector capabilities with
+\fBpam_cap\.so\fR\.
+
 .IP "" 0
 .SH "SEE ALSO"
-pam\.conf(5), capability\.conf(5), pam(8)
+.BR pam.conf (5),
+.BR capability.conf (5),
+.BR pam (8).