Skip to content

Commit 3bfa048

Browse files
stevegrubbstevegrubb
committed
Add manpage formatting check
The manpage formatter warnings were not covered by make check, so broken manual page markup could be merged without the test suite reporting it. Running the new checker also exposed long SYNOPSIS prototypes that groff could not adjust cleanly. The docs Makefile now installs check-manpages.sh as an Automake test, which makes the formatter validation run from the top-level make check target. The affected SYNOPSIS blocks were rewritten as no-fill multi-line prototypes so the formatter does not try to justify overlong function declarations.
1 parent 9e54d91 commit 3bfa048

6 files changed

Lines changed: 122 additions & 8 deletions

‎docs/Makefile.am‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,8 @@
2424
CONFIG_CLEAN_FILES = *.rej *.orig
2525

2626
EXTRA_DIST = $(man_MANS)
27+
dist_check_SCRIPTS = check-manpages.sh
28+
TESTS = check-manpages.sh
2729

2830
man_MANS = audit_add_rule_data.3 audit_add_watch.3 auditctl.8 auditd.8 \
2931
auditd.conf.5 auditd-plugins.5 \

‎docs/audit_log_acct_message.3‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,20 @@
22
.SH NAME
33
audit_log_acct_message \- log a user account message
44
.SH SYNOPSIS
5+
.nf
56
.B #include <libaudit.h>
6-
.sp
7-
.BI "int audit_log_acct_message(int" audit_fd, int" type, const char *" pgname, const char *" op, const char *" name, unsigned int" id, const char *" host, const char *" addr, const char *" tty, int" result);"
7+
.PP
8+
.BI "int audit_log_acct_message(int " audit_fd ,
9+
.BI " int " type ,
10+
.BI " const char *" pgname ,
11+
.BI " const char *" op ,
12+
.BI " const char *" name ,
13+
.BI " unsigned int " id ,
14+
.BI " const char *" host ,
15+
.BI " const char *" addr ,
16+
.BI " const char *" tty ,
17+
.BI " int " result ");"
18+
.fi
819

920
.SH DESCRIPTION
1021
This function will log a message to the audit system using a predefined message format. It should be used for all account manipulation operations. The function

‎docs/audit_log_semanage_message.3‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,26 @@
22
.SH NAME
33
audit_log_semanage_message \- log a semanage message
44
.SH SYNOPSIS
5+
.nf
56
.B #include <libaudit.h>
6-
.sp
7-
.BI "int audit_log_semanage_message(int" audit_fd, int" type, .B const char *" pgname, const char *" op, const char *" name, unsigned int" id, .B const char *" new_seuser, const char *" new_role, const char *" new_range, .B const char *" old_seuser, const char *" old_role, const char *" old_range, .B const char *" host, const char *" addr, const char *" tty, int" result);"
7+
.PP
8+
.BI "int audit_log_semanage_message(int " audit_fd ,
9+
.BI " int " type ,
10+
.BI " const char *" pgname ,
11+
.BI " const char *" op ,
12+
.BI " const char *" name ,
13+
.BI " unsigned int " id ,
14+
.BI " const char *" new_seuser ,
15+
.BI " const char *" new_role ,
16+
.BI " const char *" new_range ,
17+
.BI " const char *" old_seuser ,
18+
.BI " const char *" old_role ,
19+
.BI " const char *" old_range ,
20+
.BI " const char *" host ,
21+
.BI " const char *" addr ,
22+
.BI " const char *" tty ,
23+
.BI " int " result ");"
24+
.fi
825

926
.SH DESCRIPTION
1027

‎docs/audit_log_user_comm_message.3‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,18 @@
22
.SH NAME
33
audit_log_user_comm_message \- log a user message from a console app
44
.SH SYNOPSIS
5+
.nf
56
.B #include <libaudit.h>
6-
.sp
7-
.BI "int audit_log_user_comm_message(int" audit_fd, int" type, const char *" message, const char *" comm, const char *" hostname, const char *" addr, const char *" tty, int" result);"
7+
.PP
8+
.BI "int audit_log_user_comm_message(int " audit_fd ,
9+
.BI " int " type ,
10+
.BI " const char *" message ,
11+
.BI " const char *" comm ,
12+
.BI " const char *" hostname ,
13+
.BI " const char *" addr ,
14+
.BI " const char *" tty ,
15+
.BI " int " result ");"
16+
.fi
817

918
.SH DESCRIPTION
1019
This function will log a message to the audit system using a predefined message format. This function should be used by all non-ELF console apps that do not manipulate accounts, groups, or need to log execution of a script. An example would be a Python script recording an event. The function parameters are as follows:

‎docs/ausearch_add_timestamp_item_ex.3‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,16 @@
22
.SH NAME
33
ausearch_add_timestamp_item_ex \- build up search rule
44
.SH "SYNOPSIS"
5+
.nf
56
.B #include <auparse.h>
6-
.sp
7-
.BI "int ausearch_add_timestamp_item_ex(auparse_state_t *" au, const char *" op, time_t" sec, unsigned" milli, unsigned" serial, ausearch_rule_t" how);"
7+
.PP
8+
.BI "int ausearch_add_timestamp_item_ex(auparse_state_t *" au ,
9+
.BI " const char *" op ,
10+
.BI " time_t " sec ,
11+
.BI " unsigned " milli ,
12+
.BI " unsigned " serial ,
13+
.BI " ausearch_rule_t " how ");"
14+
.fi
815

916
.SH "DESCRIPTION"
1017

‎docs/check-manpages.sh‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
#!/bin/sh
2+
#
3+
# Check every manual page source in this directory with groff warnings enabled.
4+
# man exits successfully for formatter warnings, so stderr is treated as a
5+
# test failure.
6+
7+
set -u
8+
9+
: "${MAN:=man}"
10+
: "${srcdir:=.}"
11+
12+
if test "$srcdir" = "."; then
13+
case "$0" in
14+
*/*)
15+
srcdir=${0%/*}
16+
;;
17+
esac
18+
fi
19+
20+
if ! command -v "$MAN" >/dev/null 2>&1; then
21+
echo "SKIP: man command not found"
22+
exit 77
23+
fi
24+
25+
if command -v locale >/dev/null 2>&1; then
26+
if ! LC_ALL=C.UTF-8 locale charmap >/dev/null 2>&1; then
27+
echo "SKIP: C.UTF-8 locale not available"
28+
exit 77
29+
fi
30+
fi
31+
32+
if ! "$MAN" --help 2>&1 | grep -- "--warnings" >/dev/null 2>&1; then
33+
echo "SKIP: man command does not support --warnings"
34+
exit 77
35+
fi
36+
37+
failed=0
38+
found=0
39+
40+
for page in "$srcdir"/*.[0-9]; do
41+
test -e "$page" || continue
42+
found=1
43+
44+
output=$(
45+
LC_ALL=C.UTF-8 MANROFFSEQ='' MANWIDTH=80 \
46+
"$MAN" --warnings -E UTF-8 -l -Tutf8 -Z "$page" \
47+
2>&1 >/dev/null
48+
)
49+
status=$?
50+
51+
if test $status -ne 0 || test -n "$output"; then
52+
failed=1
53+
echo "$page:"
54+
if test -n "$output"; then
55+
printf '%s\n' "$output"
56+
fi
57+
if test $status -ne 0; then
58+
echo "man exited with status $status"
59+
fi
60+
fi
61+
done
62+
63+
if test $found -eq 0; then
64+
echo "No manual pages found"
65+
exit 1
66+
fi
67+
68+
exit $failed

0 commit comments

Comments
 (0)