Add generated manpage socranop-permissions(7)

[ndim]

This is about the generation of the man page socranop-permissions(7) from PERMISSIONS.md by running pandoc, separated from the doc updates in https://github.com/socratools/socranop/pull/49.

The discussion from https://github.com/socratools/socranop/pull/49#discussion_r671775584 and following is still applicable.

[ndim]

The lastest force-push to 42cfff019e8151289a68dade45d2abb1f3acf013 only solves the merge conflict. The other issues remain - so far.

[ndim]

So I just tried the following two actions to normalize the pandoc output:

• Using sed /PATTERN/d, remove the versioned "Automatically generated by Pandoc" line.
• Using sed 's|\\-|-|g', change all generated hyphens from the \- to -. - is what Pandoc 2.9.x generates, but the Pandoc 2.5 from Github's Ubuntu VMs generate \-.

The remaining differences are the following:

+ diff -u socranop/data/man/socranop-permissions.7 socranop/data/man/socranop-permissions.7.2531.new
--- socranop/data/man/socranop-permissions.7    2021-07-21 23:10:00.585750491 +0000
+++ socranop/data/man/socranop-permissions.7.2531.new   2021-07-21 23:12:11.919737539 +0000
@@ -14,15 +14,15 @@
 .SH DESCRIPTION
 .PP
 The \f[C]socranop-session-service\f[R] D-Bus service and the
-\f[C]socranop-ctl --dbus\f[R] CLI skipping the D-Bus service change the
-mixer audio routing by opening and writing to the device special file
-corresponding to the mixer.
+\f[C]socranop-ctl --dbus\f[R] CLI skipping the D-Bus service change
+the mixer audio routing by opening and writing to the device special
+file corresponding to the mixer.
 .PP
 By default, the device special file cannot be written by unpriviledged
-users and since the \f[C]socranop-session-service\f[R] D-Bus service and
-the \f[C]socranop-ctl --dbus\f[R] CLI run as an unpriviledged user, the
-device special files\[cq]s permission must be opened up to allow write
-access to \f[C]socranop-session-service\f[R].
+users and since the \f[C]socranop-session-service\f[R] D-Bus service
+and the \f[C]socranop-ctl --dbus\f[R] CLI run as an unpriviledged
+user, the device special files\[cq]s permission must be opened up to
+allow write access to \f[C]socranop-session-service\f[R].
 .PP
 A new device special file is created every time the mixer device is
 connected to the host, so changing the device file\[cq]s permissions by
@@ -82,18 +82,18 @@
 .SH FILES
 .SS Linux/udev
 .TP
-/dev/bus/usb/NNN/MMM
+.B /dev/bus/usb/NNN/MMM
 The USB device file
 .TP
-/etc/udev/rules.d/
+.B /etc/udev/rules.d/
 This is where the local system\[cq]s administrator write their udev rule
 files.
 .TP
-/usr/lib/udev/rules.d/
+.B /usr/lib/udev/rules.d/
 This is where operating system packages typically install their udev
 rule files.
 .TP
-/usr/local/lib/udev/rules.d/
+.B /usr/local/lib/udev/rules.d/
 This is where installations to /usr/local packages typically install
 their udev rule files.
 .SH BUGS

The first hunk is about \- and - having a different length, and thus resulting in different line wraps. I cannot see how we could normalize that without implementing the whole conversion from markdown to man inside our git repo so that we execute the very same code from start to finish regardless of what system we are being run on.

The second hunk is about making the definition terms in the definition lists bold or not. We could special-case a substitution for that, but it would not be clean either.

In summary, I would say that all these problems expose the problem of running this generation on both developer machines and on infrastructure machines, and then expecting a bit-by-bit identical result at all times from both toolchains. Or rather, adding generated files to a git repository creates headaches if the code doing the file generation is not part of that same git repository.

I would propose to leave the pre-commit hook for local generation, so that locally modifying PERMISSIONS.md always updates socranop-permissions(7) before doing a git commit, but to not add a github workflow item repeating the same thing but running different code.