[DSE-Dev] Bug#1118766: avc_open.3: Some remarks and a patch with editorial changes for this man page
Bjarni Ingi Gislason
bjarniig at simnet.is
Sat Oct 25 03:00:04 BST 2025
Package: libselinux1-dev
Version: 3.9-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?
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=0 -ww -z ":
an.tmac:<stdin>:15: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split the argument.
an.tmac:<stdin>:17: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split the argument.
an.tmac:<stdin>:19: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split the argument.
troff:<stdin>:26: warning: trailing space in the line
* 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: forky/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.16.12+deb14+1-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 libselinux1-dev depends on:
ii libpcre2-dev 10.46-1
ii libselinux1 3.9-2
ii libsepol-dev 3.9-2
libselinux1-dev recommends no packages.
libselinux1-dev suggests no packages.
-- no debconf information
-------------- next part --------------
Input file is avc_open.3
Output from "mandoc -T lint avc_open.3": (shortened list)
1 avc_open.3:23:97: STYLE: input text line longer than 80 bytes:
1 avc_open.3:26:100: STYLE: input text line longer than 80 bytes:
1 avc_open.3:26:100: STYLE: whitespace at end of input line
1 avc_open.3:34:155: STYLE: input text line longer than 80 bytes:
1 avc_open.3:39:176: STYLE: input text line longer than 80 bytes:
1 avc_open.3:50:160: STYLE: input text line longer than 80 bytes:
1 avc_open.3:53:103: STYLE: input text line longer than 80 bytes:
1 avc_open.3:55:92: STYLE: input text line longer than 80 bytes:
1 avc_open.3:6:89: STYLE: input text line longer than 80 bytes:
1 avc_open.3:78:114: STYLE: input text line longer than 80 bytes:
1 avc_open.3:82:133: STYLE: input text line longer than 80 bytes:
1 avc_open.3:85:84: STYLE: input text line longer than 80 bytes:
Find most trailing spaces with:
grep -n -e ' $' -e ' \\f.$' -e ' \\"' <man page>
-.-.
Output from
test-nroff -mandoc -t -ww -z avc_open.3: (shortened list)
3 Use macro '.B' for one argument or split the argument.
3 .BI is for at least 2 arguments, got 1
1 line(s) with a trailing space
Find most trailing spaces with:
grep -n -e ' $' -e ' \\f.$' -e ' \\"' <man page>
-.-.
Remove space characters (whitespace) at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
Number of lines affected is
1
-.-.
Use the correct macro for the font change of a single argument or
split the argument into two.
15:.BI "void avc_destroy(void);"
17:.BI "int avc_reset(void);"
19:.BI "void avc_cleanup(void);"
-.-.
Split lines longer than 80 characters (fill completly
an A4 sized page line on a terminal)
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.
[List of affected lines removed.]
Line 6, length 89
avc_open, avc_destroy, avc_reset, avc_cleanup \- userspace SELinux AVC setup and teardown
Line 23, length 97
initializes the userspace AVC and must be called before any other AVC operation can be performed.
Line 26, length 100
destroys the userspace AVC, freeing all internal memory structures. After this call has been made,
Line 34, length 155
flushes the userspace AVC, causing it to forget any cached access decisions. The userspace AVC normally calls this function automatically when needed, see
Line 39, length 176
attempts to free unused memory within the userspace AVC, but does not flush any cached access decisions. Under normal operation, calling this function should not be necessary.
Line 50, length 160
This option forces the userspace AVC into enforcing mode if the option value is non-NULL; permissive mode otherwise. The system enforcing mode will be ignored.
Line 53, length 103
Linux kernel version 2.6.37 supports the SELinux kernel status page, enabling userspace applications to
Line 55, length 92
SELinux status state in read-only mode to avoid system calls during the cache hit code path.
Line 78, length 114
the AVC will default to the netlink fallback mechanism, which opens a netlink socket for receiving status updates.
Line 82, length 133
events will have the same results as for the status page implementation, but all status update checks will now require a system call.
Line 85, length 84
Functions with a return value return zero on success. On error, \-1 is returned and
Longest line is number 39 with 176 characters
-.-.
Remove quotes when there is a printable
but no space character between them
and the quotes are not for emphasis (markup),
for example as an argument to a macro.
avc_open.3:4:.TH "avc_open" "3" "12 Jun 2008" "" "SELinux API documentation"
avc_open.3:5:.SH "NAME"
avc_open.3:8:.SH "SYNOPSIS"
avc_open.3:21:.SH "DESCRIPTION"
avc_open.3:40:.SH "OPTIONS"
avc_open.3:89:.SH "AUTHOR"
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=0 -ww -z ":
an.tmac:<stdin>:15: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split the argument.
an.tmac:<stdin>:17: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split the argument.
an.tmac:<stdin>:19: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split the argument.
troff:<stdin>:26: warning: trailing space in the line
-.-
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
-.-
-------------- next part --------------
--- avc_open.3 2025-10-25 01:47:19.432170070 +0000
+++ avc_open.3.new 2025-10-25 01:54:03.250941676 +0000
@@ -12,18 +12,18 @@ avc_open, avc_destroy, avc_reset, avc_cl
.sp
.BI "int avc_open(const struct selinux_opt *" options ", unsigned " nopt ");"
.sp
-.BI "void avc_destroy(void);"
+.B "void avc_destroy(void);"
.sp
-.BI "int avc_reset(void);"
+.B "int avc_reset(void);"
.sp
-.BI "void avc_cleanup(void);"
+.B "void avc_cleanup(void);"
.
.SH "DESCRIPTION"
.BR avc_open ()
initializes the userspace AVC and must be called before any other AVC operation can be performed.
.BR avc_destroy ()
-destroys the userspace AVC, freeing all internal memory structures. After this call has been made,
+destroys the userspace AVC, freeing all internal memory structures. After this call has been made,
.BR avc_open ()
must be called again before any AVC operations can be performed.
.BR avc_destroy ()
-------------- next part --------------
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
-.-
For general input conventions consult the man page "nroff(7)" (item
"Input conventions") or the Texinfo manual about the same item.
-.-
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)
-.-
More information about the SELinux-devel
mailing list