[DSE-Dev] Bug#1094886: init_selinuxmnt.3: Some remarks and a patch with editorial changes for this man page

[Bjarni Ingi Gislason]

Package: libselinux1-dev
Version: 3.7-3+b1
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 "groff -e ' $' -e '\\~$' <file>" to find obvious 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?


an.tmac:<stdin>:1: style: .TH missing fourth argument; consider package/project name and version (e.g., "groff 1.23.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.10-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.44-5
ii  libselinux1   3.7-3+b1
ii  libsepol-dev  3.7-1

libselinux1-dev recommends no packages.

libselinux1-dev suggests no packages.

-- no debconf information
-------------- next part --------------
Input file is init_selinuxmnt.3

Output from "mandoc -T lint  init_selinuxmnt.3": (shortened list)


-.-.

Output from "test-groff -mandoc -t -ww -z init_selinuxmnt.3": (shortened list)

      2 	Use macro '.B' for one argument or split argument.
      2 .BI is for at least 2 arguments, got 1

-.-.

Use the correct macro for the font change of a single argument or
split the argument into two.

6:.BI "static void init_selinuxmnt(void);"
8:.BI "static void fini_selinuxmnt(void);"

-.-.
 
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.

1:.TH "init_selinuxmnt" "3" "21 Nov 2009" "" "SELinux API documentation"
2:.SH "NAME"
5:.SH "SYNOPSIS"
10:.BI "void set_selinuxmnt(const char *" mnt ");"
12:.SH "DESCRIPTION"
27:.SH "AUTHOR"

-.-.

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

an.tmac:<stdin>:1: style: .TH missing fourth argument; consider package/project name and version (e.g., "groff 1.23.0")
an.tmac:<stdin>:6: misuse, warning: .BI is for at least 2 arguments, got 1
	Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:8: misuse, warning: .BI is for at least 2 arguments, got 1
	Use macro '.B' for one argument or split argument.
-------------- next part --------------
--- init_selinuxmnt.3	2025-02-01 00:14:06.201597507 +0000
+++ init_selinuxmnt.3.new	2025-02-01 00:18:50.511942750 +0000
@@ -1,15 +1,15 @@
-.TH "init_selinuxmnt" "3" "21 Nov 2009" "" "SELinux API documentation"
-.SH "NAME"
+.TH init_selinuxmnt 3 "21 Nov 2009" "" "SELinux API documentation"
+.SH NAME
 init_selinuxmnt \- initialize the global variable selinux_mnt
 .
-.SH "SYNOPSIS"
-.BI "static void init_selinuxmnt(void);"
+.SH SYNOPSIS
+.B "static void init_selinuxmnt(void);"
 .sp
-.BI "static void fini_selinuxmnt(void);"
+.B "static void fini_selinuxmnt(void);"
 .sp
-.BI "void set_selinuxmnt(const char *" mnt ");"
+.BI "void set_selinuxmnt(const char *" mnt );
 .
-.SH "DESCRIPTION"
+.SH DESCRIPTION
 .BR init_selinuxmnt ()
 initializes the global variable
 .I selinux_mnt
@@ -24,7 +24,7 @@ that stores the selinuxfs mountpoint.
 changes the selinuxfs mountpoint to
 .IR mnt .
 .
-.SH "AUTHOR"
+.SH AUTHOR
 This manual page has been written by Guido Trentalancia <guido at trentalancia.com>
 .
 .SH "SEE ALSO"
-------------- 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>

  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.

  Not beginning each input sentence on a new line.
Line length 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 -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 -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)

-.-