RFE: consider generating the man pages from Markdown

[pcmoore]

Consider using a document converter such as pandoc to generate the man pages from Markdown. Not only should this make it easier to create/edit the man pages, but it should make the documentation easier to read on GitHub.

[pcmoore]

Related #185.

[pcmoore]

Related: #195.

[oxr463]

#!/bin/sh
set -eu

for doc in man/man?/*.?; do
  pandoc "${doc}" --from man --to markdown > "${doc}.md";
done

sed -i 's|\\||g' man?/*.md

[oxr463]

Some of the pages failed to convert.

file doc/man/man?/*.md
doc/man/man1/scmp_sys_resolver.1.md:                    ReStructuredText file, ASCII text
doc/man/man3/seccomp_api_get.3.md:                      ReStructuredText file, ASCII text
doc/man/man3/seccomp_api_set.3.md:                      very short file (no magic)
doc/man/man3/seccomp_arch_add.3.md:                     ReStructuredText file, ASCII text
doc/man/man3/seccomp_arch_exist.3.md:                   very short file (no magic)
doc/man/man3/seccomp_arch_native.3.md:                  very short file (no magic)
doc/man/man3/seccomp_arch_remove.3.md:                  very short file (no magic)
doc/man/man3/seccomp_arch_resolve_name.3.md:            very short file (no magic)
doc/man/man3/seccomp_attr_get.3.md:                     very short file (no magic)
doc/man/man3/seccomp_attr_set.3.md:                     ReStructuredText file, ASCII text
doc/man/man3/seccomp_export_bpf.3.md:                   ReStructuredText file, ASCII text
doc/man/man3/seccomp_export_pfc.3.md:                   very short file (no magic)
doc/man/man3/seccomp_init.3.md:                         ReStructuredText file, ASCII text
doc/man/man3/seccomp_load.3.md:                         ReStructuredText file, ASCII text
doc/man/man3/seccomp_merge.3.md:                        ReStructuredText file, ASCII text
doc/man/man3/seccomp_notify_alloc.3.md:                 ReStructuredText file, ASCII text
doc/man/man3/seccomp_notify_fd.3.md:                    very short file (no magic)
doc/man/man3/seccomp_notify_free.3.md:                  very short file (no magic)
doc/man/man3/seccomp_notify_id_valid.3.md:              very short file (no magic)
doc/man/man3/seccomp_notify_receive.3.md:               very short file (no magic)
doc/man/man3/seccomp_notify_respond.3.md:               very short file (no magic)
doc/man/man3/seccomp_release.3.md:                      ReStructuredText file, ASCII text
doc/man/man3/seccomp_reset.3.md:                        very short file (no magic)
doc/man/man3/seccomp_rule_add.3.md:                     ReStructuredText file, ASCII text
doc/man/man3/seccomp_rule_add_array.3.md:               very short file (no magic)
doc/man/man3/seccomp_rule_add_exact.3.md:               very short file (no magic)
doc/man/man3/seccomp_rule_add_exact_array.3.md:         very short file (no magic)
doc/man/man3/seccomp_syscall_priority.3.md:             ReStructuredText file, ASCII text
doc/man/man3/seccomp_syscall_resolve_name.3.md:         ReStructuredText file, ASCII text
doc/man/man3/seccomp_syscall_resolve_name_arch.3.md:    very short file (no magic)
doc/man/man3/seccomp_syscall_resolve_name_rewrite.3.md: very short file (no magic)
doc/man/man3/seccomp_syscall_resolve_num_arch.3.md:     very short file (no magic)
doc/man/man3/seccomp_version.3.md:                      ReStructuredText file, ASCII text

Edit: looks like those files are empty.

[pcmoore]

Since it looks like we may have some help here, I'm moving this into the v2.6.0 milestone - thanks @oxr463!

[pcmoore]

In an effort to get v2.6.0 out sooner than later, I'm going to suggest we push this out to v2.7.0; if you have any concerns or objections please drop a comment.