man: create man page with asciidoctor instead of help2man

Support building man pages for cross builds.

Include more information, like 'Exit status' and 'Check IDs'.

.github/workflows/main.yml

@@ -48,7 +48,7 @@ jobs:
     - name: install dependencies
       run: |
         sudo apt-get update -q
-        sudo apt-get install -y uthash-dev libconfuse-dev autoconf-archive bison byacc flex valgrind help2man bats
+        sudo apt-get install -y uthash-dev libconfuse-dev autoconf-archive bison byacc flex valgrind asciidoctor bats
     # Install libcheck from source.  Ubuntu is on version 0.10.0, and ck_assert_ptr_null and
     # ck_assert_ptr_nonnull were added in 0.11.0
     - name: checkout check

configure.ac

@@ -66,13 +66,13 @@ AC_ARG_ENABLE([gcov],
 
 AM_CONDITIONAL([COND_GCOV],[ test "x$enable_gcov" "=" "xyes" ])
 
-AC_CHECK_PROGS([HELP2MAN], [help2man])
-if ! test -z "$HELP2MAN"
+AC_CHECK_PROGS([ASCIIDOCTOR], [asciidoctor])
+if ! test -z "$ASCIIDOCTOR"
 then
 AC_SUBST(MANPAGES, selint.1)
-HAVE_HELP2MAN=true
+HAVE_ASCIIDOCTOR=true
 fi
-AM_CONDITIONAL([HAVE_HELP2MAN], [test "x$HAVE_HELP2MAN" "=" "xtrue"])
+AM_CONDITIONAL([HAVE_ASCIIDOCTOR], [test "x$HAVE_ASCIIDOCTOR" "=" "xtrue"])
 
 AX_VALGRIND_DFLT([drd], [off])
 AX_VALGRIND_DFLT([helgrind], [off])

man/Makefile.am

@@ -12,15 +12,15 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-SOURCES=selint.h2m
+SOURCES=selint.adoc
 
-if HAVE_HELP2MAN
+if HAVE_ASCIIDOCTOR
 man1_MANS=$(MANPAGES)
 EXTRA_DIST=$(man1_MANS) $(SOURCES)
 CLEANFILES=$(MANPAGES)
 
-selint.1: ../src/main.c $(SOURCES)
-	$(HELP2MAN) -n "Perform static source code analysis on SELinux policy source files" -N -i selint.h2m -o $@ ../src/selint
+selint.1: $(SOURCES)
+	$(ASCIIDOCTOR) --failure-level INFO --warnings --verbose --backend manpage $^ --out-file $@
 else
 EXTRA_DIST=$(SOURCES)
 endif

man/selint.adoc

@@ -0,0 +1,298 @@
+= selint(1)
+:doctype: manpage
+:release-version: 1.4.0
+:manmanual: SELint Manual
+:mansource: SELint {release-version}
+
+== Name
+
+SELint - Perform static source code analysis on SELinux policy source files
+
+
+== Synopsis
+
+*selint* [_OPTION_]... _FILE_...
+
+
+== Options
+
+*-c, --config*=_CONFIGFILE_::
+  Override default config with config specified on command line.
+  See CONFIGURATION section for config file syntax.
+
+*--color*=_COLOR_OPTION_::
+  Configure color output.
+  Options are _on_, _off_ and _auto_ (the default).
+
+*--context*=_CONTEXT_PATH_::
+  Recursively scan CONTEXT_PATH to find additional te and if files to parse, but not scan.
+  SELint will assume the scanned policy files are intended to be compiled together with the context files.
+  Implies _-s_.
+
+*--debug-parser*::
+  Enable debug output for the internal policy parser.
+  Very noisy, useful to debug parsing failures.
+
+*-d, --disable*=_CHECKID_::
+  Disable check with the given ID.
+
+*-e, --enable*=_CHECKID_::
+  Enable check with the given ID.
+
+*-E, --only-enabled*::
+  Only run checks that are explicitly enabled with the _--enable_ option.
+
+*--full-path*::
+  Print full path for files.
+
+*-F, --fail*::
+  Exit with a non-zero value if any issue was found.
+
+*-h, --help*::
+  Display the menu.
+
+*-l, --level*=_LEVEL_::
+  Only list errors with a severity level at or greater than LEVEL.
+  Options are _C_ (convention), _S_ (style), _W_ (warning), _E_ (error), _F_ (fatal error).
+
+*--scan-hidden-dirs*::
+  Scan hidden directories.
+  By default hidden directories (like '.git') are skipped in recursive mode.
+
+*-s, --source*::
+  Run in "source mode" to scan a policy source repository that is designed to compile into a full system policy.
+
+*-S, --summary*::
+  Display a summary of issues found after running the analysis.
+
+*--summary-only*::
+  Only display a summary of issues found after running the analysis.
+  Do not show the individual findings.
+  Implies _-S_.
+
+*-r, --recursive*::
+  Scan recursively and check all SELinux policy files found.
+
+*-v, --verbose*::
+  Enable verbose output.
+
+*-V, --version*::
+  Show version information and exit.
+
+
+== Exit Status
+
+*0*::
+  Success.
+  Source policy files were successfully scanned.
+
+*70*::
+  Failure.
+  Failed to parse or scan source policy files or issues were found while using the _--fail_ option.
+
+
+== Configuration
+
+A global configuration is specified at the install prefix supplied to ./configure (typically /usr/local/etc).
+This path can be overridden on the command line using the _-c_ option.
+
+Options specified on the command line override options from the config file.
+
+Lines staring with a pound (_#_) are ignored as comments.
+Values are assigned to configuration keys via the equal sign (_=_).
+See the global config file for more details on config file syntax.
+
+
+== Severity Levels
+
+SELint messages are assocatied with a severity level, indicating the significance of the issue.
+Available levels are listed below in increasing order of significance.
+
+=== X (extra)
+Miscellaneous checks, mainly for policy introspection +
+These must be explicitly enabled with their individual identifier.
+
+=== C (convention)
+A violation of common style conventions
+
+=== S (style)
+Stylistic "code smell" that may be associated with unintended behavior
+
+=== W (warning)
+Non standard policy that may result in issues such as run time errors or security issues
+
+=== E (error)
+Important issues that may result in errors at compile time or run time
+
+=== F (fatal error)
+Error that prevents further processing
+
+
+== SELint Exceptions
+
+To eliminate one or more checks on one line, add a comment containing a string in any of the following formats:
+
+* `selint-disable:E-003`
+* `selint-disable: E-003`
+* `selint-disable:E-003,E-004`
+* `selint-disable: E-003, E-004`
+
+This is currently only supported in te and if files.
+
+
+== Output
+
+SELint outputs messages in the following format:
+
+ [filename]:[lineno]: ([SEVERITY LEVEL]): [MESSAGE] ([ISSUE ID])
+
+For example:
+
+ example.te:127: (E) Interface from module not in optional_policy block (E-001)
+
+
+== Check IDs
+
+The following checks may be performed:
+
+=== X-001
+Unused interface or template declaration
+
+=== X-002
+AV rule with excluded source or target (can affect policy binary size)
+
+
+=== C-001
+Violation of refpolicy te file ordering conventions
+
+=== C-004
+Interface does not have documentation comment
+
+=== C-005
+Permissions in av rule or class declaration not ordered
+
+=== C-006
+Declarations in require block not ordered
+
+=== C-007
+Redundant type specification instead of self keyword
+
+=== C-008
+Conditional expression identifier from foreign module
+
+
+=== S-001
+Require block used instead of interface call
+
+=== S-002
+File context file labels with type not declared in module
+
+=== S-003
+Unnecessary semicolon
+
+=== S-004
+Template call from an interface
+
+=== S-005
+Declaration in interface
+
+=== S-006
+Bare module statement
+
+=== S-007
+Call to gen_context omits mls component
+
+=== S-008
+Unquoted gen_require block
+
+=== S-009
+Permission macro suffix does not match class name
+
+=== S-010
+Permission macro usage suggested
+
+
+=== W-001
+Type or attribute referenced without explicit declaration
+
+=== W-002
+Type, attribute or role used but not listed in require block in interface
+
+=== W-003
+Unused type, attribute or role listed in require block
+
+=== W-004
+Potentially unescaped regex character in file contexts paths
+
+=== W-005
+Interface call from module not in optional_policy block
+
+=== W-006
+Interface call with empty argument
+
+=== W-007
+Unquoted space in argument of interface call
+
+=== W-008
+Allow rule with complement or wildcard permission
+
+=== W-009
+Module name does not match file name
+
+=== W-010
+Call to unknown interface
+
+=== W-011
+Declaration in require block not defined in own module
+
+=== W-012
+Conditional expression contains unknown identifier
+
+=== W-013
+Incorrect usage of audit_access permission
+
+
+=== E-002
+Bad file context format
+
+=== E-003
+Nonexistent user listed in fc file
+
+=== E-004
+Nonexistent role listed in fc file
+
+=== E-005
+Nonexistent type listed in fc file
+
+=== E-006
+Declaration and interface with same name
+
+=== E-007
+Usage of unknown permission or permission macro
+
+=== E-008
+Usage of unknown class
+
+=== E-009
+Empty optional or require macro block
+
+=== E-010
+Usage of unknown simple m4 macro or stray word
+
+
+=== F-001
+Policy syntax error prevents further processing
+
+=== F-002
+Internal error in SELint
+
+
+== Reporting Bugs
+
+Report bugs at https://github.com/SELinuxProject/selint/issues
+
+
+== Copyright
+
+Copyright \(C) 2019-present The SELint Contributors. +
+Free use of this software is granted under the terms of the Apache License Version 2.0.

selint.spec

@@ -13,7 +13,7 @@ License: ASL 2.0
 %forgemeta
 Source0: %{forgesource}
 
-BuildRequires: autoconf autoconf-archive automake bison check check-devel flex gcc help2man libconfuse libconfuse-devel uthash-devel
+BuildRequires: autoconf autoconf-archive automake bison check check-devel flex gcc asciidoctor libconfuse libconfuse-devel uthash-devel
 # pkgconfig
 Requires: libconfuse
 %if 0%{?fedora} || 0%{?rhel} >= 8