docs: write man pages in markdown

The goal in rewriting to markdown is to allow access via github with
direct links to options and commands.

Move from scdoc to markdown.

Reorder alphabetically grout options.

Add necessary tool to build man pages from markdown.

Signed-off-by: Anthony Harivel <[email protected]>

.github/workflows/check.yml

@@ -32,7 +32,7 @@ jobs:
           set -xe
           sudo apt-get update -qy
           sudo apt-get install -qy --no-install-recommends \
-            make gcc ninja-build meson git scdoc libibverbs-dev \
+            make gcc ninja-build meson git go-md2man libibverbs-dev \
             libasan8 libcmocka-dev libedit-dev libarchive-dev \
             libevent-dev libsmartcols-dev libnuma-dev python3-pyelftools \
             socat tcpdump traceroute graphviz iproute2 iputils-ping ndisc6
@@ -61,7 +61,7 @@ jobs:
           dpkg --add-architecture arm64
           apt update -qy
           apt install -qy --no-install-recommends \
-            make gcc git meson scdoc python3-pyelftools ca-certificates pkg-config \
+            make gcc git meson go-md2man python3-pyelftools ca-certificates pkg-config \
             crossbuild-essential-arm64 libcmocka-dev:arm64 libedit-dev:arm64 \
             libevent-dev:arm64 libnuma-dev:arm64 libsmartcols-dev:arm64
       - uses: actions/checkout@v4

.github/workflows/publish.yml

@@ -29,7 +29,7 @@ jobs:
           set -xe
           apt-get update -qy
           NEEDRESTART_MODE=l apt-get install -qy --no-install-recommends \
-            git build-essential meson ninja-build pkgconf scdoc python3-pyelftools \
+            git build-essential meson ninja-build pkgconf go-md2man python3-pyelftools \
             libcmocka-dev libedit-dev libevent-dev libnuma-dev \
             libsmartcols-dev libarchive-dev libibverbs-dev \
             bash-completion devscripts debhelper
@@ -57,7 +57,8 @@ jobs:
           dnf --enablerepo=crb install -y --nodocs --setopt=install_weak_deps=0 \
             https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm
           dnf --enablerepo=crb install -y --nodocs --setopt=install_weak_deps=0 \
-            gcc git make meson ninja-build pkgconf scdoc python3-pyelftools \
+            gcc git make meson ninja-build pkgconf python3-pyelftools \
+            golang-github-cpuguy83-md2man \
             libcmocka-devel libedit-devel libevent-devel numactl-devel \
             libsmartcols-devel libarchive-devel rdma-core-devel \
             rpm-build systemd

README.md

@@ -235,15 +235,17 @@ image.
 ### Install build dependencies
 
 ```sh
-dnf install gcc git make meson ninja-build pkgconf scdoc python3-pyelftools \
+dnf install git gcc make meson ninja-build pkgconf \
+        python3-pyelftools golang-github-cpuguy83-md2man \
         libcmocka-devel libedit-devel libevent-devel numactl-devel \
         libsmartcols-devel libarchive-devel rdma-core-devel
 ```
 
 or
 
 ```sh
-apt install git gcc make meson ninja-build pkgconf scdoc python3-pyelftools \
+apt install git gcc make meson ninja-build pkgconf \
+        python3-pyelftools go-md2man \
         libcmocka-dev libedit-dev libevent-dev libnuma-dev \
         libsmartcols-dev libarchive-dev libibverbs-dev
 ```
@@ -314,5 +316,6 @@ Anyone can contribute to `grout`. See [`CONTRIBUTING.md`](/CONTRIBUTING.md).
 | cmocka | Build | Apache-2.0 | https://github.com/clibs/cmocka |
 | meson | Build | Apache-2.0 | https://github.com/mesonbuild/meson |
 | ninja | Build | Apache-2.0 | https://github.com/ninja-build/ninja |
+| go-md2man | Build | MIT | https://github.com/cpuguy83/go-md2man |
 | libasan | Dev | MIT+BSD | https://github.com/gcc-mirror/gcc/tree/master/libsanitizer |
 | clang-format | Dev | MIT+BSD | https://clang.llvm.org/docs/ClangFormat.html |

debian/control

@@ -8,6 +8,7 @@ Build-Depends:
  debhelper-compat (= 13),
  bash-completion,
  git,
+ go-md2man,
  libarchive-dev,
  libcmocka-dev,
  libedit-dev,
@@ -20,7 +21,6 @@ Build-Depends:
  patch,
  pkg-config,
  python3-pyelftools,
- scdoc,
 Standards-Version: 4.7.0
 Rules-Requires-Root: no
 Homepage: https://github.com/DPDK/grout

docs/grcli.1.md

@@ -0,0 +1,57 @@
+GRCLI 1 @DATE@ "grout @VERSION@"
+================================
+
+# NAME
+
+**grcli** -- grout command line interface
+
+# DESCRIPTION
+
+Grout is a software router based on DPDK __rte_graph__.
+
+# SYNOPSIS
+
+**grcli**
+[**-e**]
+[**-f** _PATH_]
+[**-h**]
+[**-s** _PATH_]
+[**-V**]
+[**-x**]
+...
+
+# OPTIONS
+
+#### **-e**, **--err-exit**
+
+Abort on first error.
+
+#### **-f** _PATH_, **--file** _PATH_
+
+Read commands from _PATH_ instead of standard input.
+
+#### **-h**, **--help**
+
+Show this help message and exit.
+
+#### **-s** _PATH_, **--socket** _PATH_
+
+Path to the control plane API socket.
+
+Default: **GROUT_SOCK_PATH** from environment or _/run/grout.sock_.
+
+#### **-V**, **--version**
+
+Print version and exit.
+
+#### **-x**, **--trace-commands**
+
+Print executed commands.
+
+# SEE ALSO
+
+**grout**(8)
+
+# AUTHORS
+
+Created and maintained by Robin Jarry.

docs/grout.8.md

@@ -0,0 +1,130 @@
+GROUT 8 @DATE@ "grout @VERSION@"
+================================
+
+# NAME
+
+**grout** -- graph router daemon
+
+# DESCRIPTION
+
+Grout is a software router based on DPDK __rte_graph__.
+
+# SYNOPSIS
+
+**grout**
+[**-B** _SIZE_]
+[**-D** _PATH_]
+[**-h**]
+[**-L** _TYPE_:_LEVEL_]
+[**-M** _MODE_]
+[**-p**]
+[**-s** _PATH_]
+[**-t**]
+[**-T** _REGEXP_]
+[**-v**]
+[**-V**]
+[**-x**]
+
+# OPTIONS
+
+#### **-B**, **--trace-bufsz** _SIZE_
+
+Specify maximum size of allocated memory for trace output for each thread.
+Valid unit can be either B or K or M for Bytes, KBytes and MBytes respectively.
+For example:
+
+```
+--trace-bufsz 2M
+```
+
+By default, size of trace output file is 1MB and parameter must be
+specified once only.
+
+#### **-D**, **--trace-dir** _PATH_
+
+Specify trace directory for trace output. For example:
+
+```
+--trace-dir /tmp
+```
+
+By default, trace output will created at home directory and parameter must be
+specified once only.
+
+#### **-h**, **--help**
+
+Display usage help.
+
+#### **-L**, **--log-level** _TYPE_:_LEVEL_
+
+Specify log level for a specific component. For example:
+
+```
+--log-level lib.eal:debug
+```
+
+Can be specified multiple times.
+
+#### **-M**, **--trace-mode** _o_|_overwrite_|_d_|_discard_
+
+Specify the mode of update of trace output file. Either update on a file can be
+wrapped or discarded when file size reaches its maximum limit. For example:
+
+```
+--trace-mode discard
+```
+
+Default mode is _overwrite_ and parameter must be specified once only.
+
+#### **-p**, **--poll-mode**
+
+Disable automatic micro-sleep.
+
+#### **-s**, **--socket** _PATH_
+
+Path the control plane API socket.
+
+Default: **GROUT_SOCK_PATH** from environment or _/run/grout.sock_.
+
+#### **-t**, **--test-mode**
+
+Run in test mode (no huge pages).
+
+#### **-T**, **--trace** _REGEXP_
+
+Enable trace based on regular expression trace name. By default, the trace is
+disabled. User must specify this option to enable trace. For example:
+
+Global trace configuration for EAL only:
+
+```
+--trace eal
+```
+
+Global trace configuration for ALL the components:
+
+```
+--trace ".*"
+```
+
+Can be specified multiple times up to 32 times.
+
+#### **-v**, **--verbose**
+
+Increase verbosity. Can be specified multiple times.
+
+#### **-V**, **--version**
+
+Print version and exit.
+
+#### **-x**, **--trace-packets**
+
+Print all ingress/egress packets (for debugging purposes).
+
+# SEE ALSO
+
+**grcli**(1)
+
+# AUTHORS
+
+Created and maintained by Robin Jarry.