Generate man pages using pandoc

Add nohang.manpage.md
Update Makefile: add reinstall-deb target

Makefile

@@ -15,7 +15,13 @@ MANDIR ?=  $(DATADIR)/man
 all:
 	@ echo "Use: make install, make install-openrc, make uninstall"
 
-base:
+manpages:
+	-pandoc docs/nohang.manpage.md -s -t man > man/nohang.8
+	-pandoc docs/oom-sort.manpage.md -s -t man > man/oom-sort.1
+	-pandoc docs/psi2log.manpage.md -s -t man > man/psi2log.1
+	-pandoc docs/psi-top.manpage.md -s -t man > man/psi-top.1
+
+base: manpages
 	install -d $(DESTDIR)$(SBINDIR)
 	install -m0755 src/nohang $(DESTDIR)$(SBINDIR)/nohang
 
@@ -86,6 +92,11 @@ daemon-reload:
 
 build_deb: base units
 
+reinstall-deb:
+	set -v
+	deb/build.sh
+	sudo apt install --reinstall ./deb/package.deb
+
 install: base units chcon daemon-reload
 
 openrc:

docs/nohang.manpage.md

@@ -0,0 +1,79 @@
+% nohang(8) | Linux System Administrator's Manual
+
+# NAME
+nohang - A sophisticated low memory handler
+
+# SYNOPSIS
+**nohang** [**OPTION**]...
+
+# DESCRIPTION
+nohang is a highly configurable daemon for Linux which is able to correctly prevent out of memory (OOM) and keep system responsiveness in low memory conditions.
+
+# REQUIREMENTS
+
+#### For basic usage:
+- Linux (>= 3.14, since MemAvailable appeared in /proc/meminfo)
+- Python (>= 3.3)
+
+#### To respond to PSI metrics (optional):
+- Linux (>= 4.20) with CONFIG_PSI=y
+
+#### To show GUI notifications (optional):
+- notification server (most of desktop environments use their own implementations)
+- libnotify (Arch Linux, Fedora, openSUSE) or libnotify-bin (Debian GNU/Linux, Ubuntu)
+- sudo if nohang started with UID=0.
+
+# OPTIONS
+
+#### -h, --help
+show this help message and exit
+
+#### -v, \-\-version
+show version of installed package and exit
+
+#### -m, \-\-memload
+consume memory until 40 MiB (MemAvailable + SwapFree) remain free, and terminate the process
+
+#### -c CONFIG, \-\-config CONFIG
+path to the config file. This should only be used with one of the following options:
+\-\-monitor, \-\-tasks, --check
+
+#### --check
+check and show the configuration and exit. This should only be used with -c/--config CONFIG option
+
+#### --monitor
+start monitoring. This should only be used with -c/--config CONFIG option
+
+#### --tasks
+show tasks state and exit. This should only be used with -c/--config CONFIG option
+
+# HOW TO CONFIGURE
+The program can be configured by editing the config file. The configuration includes the following sections:
+
+- Memory levels to respond to as an OOM threat
+- Response on PSI memory metrics
+- The frequency of checking the level of available memory (and CPU usage)
+- The prevention of killing innocent victims
+- Impact on the badness of processes via matching their names, cmdlines and UIDs with regular expressions
+- The execution of a specific command or sending any signal instead of sending the SIGTERM signal
+- GUI notifications:
+    - notifications of corrective actions taken
+    - low memory warnings
+- Verbosity
+- Misc
+
+Just read the description of the parameters and edit the values. Restart the daemon to apply the changes.
+
+# HOW TO TEST
+The safest way is to run **nohang --memload**. This causes memory consumption, and the process will exits before OOM occurs. Another way is to run **tail /dev/zero**. This causes fast memory comsumption and causes OOM at the end. If testing occurs while nohang is running, these processes should be terminated before OOM occurs.
+
+# LOGGING
+To view the latest entries in the log (for systemd users):
+
+$ **sudo journalctl -eu nohang.service**
+
+or
+
+$ **sudo journalctl -eu nohang-desktop.service**
+
+You can also enable **separate_log** in the config to logging in **/var/log/nohang/nohang.log**.

docs/oom-sort.manpage.md

@@ -0,0 +1,9 @@
+% oom-sort(1) | General Commands Manual
+
+# NAME
+
+oom-sort - sort processes by oom_score
+
+# SYNOPSIS
+
+**oom-sort** [**OPTION**]...

docs/psi-top.manpage.md

@@ -0,0 +1,9 @@
+% psi-top(1) | General Commands Manual
+
+# NAME
+
+psi-top
+
+# SYNOPSIS
+
+**psi-top** [**OPTION**]...

docs/psi2log.manpage.md

@@ -0,0 +1,9 @@
+% psi2log(1) | General Commands Manual
+
+# NAME
+
+psi2log \- PSI metrics monitor and logger
+
+# SYNOPSIS
+
+**psi2log** [**OPTION**]...

man/nohang.8

@@ -1,109 +1,115 @@
-.TH nohang 8
+.\" Automatically generated by Pandoc 1.17.2
-
+.\"
+.TH "nohang" "8" "" "" "Linux System Administrator\[aq]s Manual"
+.hy
 .SH NAME
-
+.PP
 nohang \- A sophisticated low memory handler
-
 .SH SYNOPSIS
-.B nohang
+.PP
-.RB [ OPTION ]...
+\f[B]nohang\f[] [\f[B]OPTION\f[]]...
-
 .SH DESCRIPTION
-
+.PP
-Nohang is a highly configurable daemon for Linux which is able to correctly prevent out of memory (OOM) and keep system responsiveness in low memory conditions.
+nohang is a highly configurable daemon for Linux which is able to
-
+correctly prevent out of memory (OOM) and keep system responsiveness in
+low memory conditions.
 .SH REQUIREMENTS
-
+.SS For basic usage:
-.B For basic usage:
+.IP \[bu] 2
-
+Linux (>= 3.14, since MemAvailable appeared in /proc/meminfo)
-    - Linux 3.14+ (since MemAvailable appeared in /proc/meminfo)
+.IP \[bu] 2
-
+Python (>= 3.3)
-    - Python 3.3+ (not tested with previous)
+.SS To respond to PSI metrics (optional):
-
+.IP \[bu] 2
-.B To show GUI notifications:
+Linux (>= 4.20) with CONFIG_PSI=y
-
+.SS To show GUI notifications (optional):
-    - Notification server (most of desktop environments use their own implementations)
+.IP \[bu] 2
-
+notification server (most of desktop environments use their own
-    - libnotify (Fedora, Arch Linux) or libnotify-bin (Debian GNU/Linux, Ubuntu)
+implementations)
-
+.IP \[bu] 2
-    - sudo if nohang started with UID=0
+libnotify (Arch Linux, Fedora, openSUSE) or libnotify\-bin (Debian
-
+GNU/Linux, Ubuntu)
-.B To use PSI:
+.IP \[bu] 2
-
+sudo if nohang started with UID=0.
-    - It needs Linux 4.20+ with CONFIG_PSI=y.
-
 .SH OPTIONS
-
+.SS \-h, \-\-help
-  -h, --help            show this help message and exit
+.PP
-
+show this help message and exit
-  -v, --version         show version of installed package and exit
+.SS \-v, \-\-version
-
+.PP
-  -m, --memload         consume memory until 40 MiB (MemAvailable + SwapFree)
+show version of installed package and exit
-                        remain free, and terminate the process
+.SS \-m, \-\-memload
-
+.PP
-  -c CONFIG, --config CONFIG
+consume memory until 40 MiB (MemAvailable + SwapFree) remain free, and
-                        path to the config file. This should only be used
+terminate the process
-                        with one of the following options:
+.SS \-c CONFIG, \-\-config CONFIG
-                        --monitor, --tasks, --check
+.PP
-
+path to the config file.
-  --check               check and show the configuration and exit. This should
+This should only be used with one of the following options: \-\-monitor,
-                        only be used with -c/--config CONFIG option
+\-\-tasks, \-\-check
-
+.SS \-\-check
-  --monitor             start monitoring. This should only be used with
+.PP
-                        -c/--config CONFIG option
+check and show the configuration and exit.
-
+This should only be used with \-c/\-\-config CONFIG option
-  --tasks               show tasks state and exit. This should only be used
+.SS \-\-monitor
-                        with -c/--config CONFIG option
+.PP
-
+start monitoring.
+This should only be used with \-c/\-\-config CONFIG option
+.SS \-\-tasks
+.PP
+show tasks state and exit.
+This should only be used with \-c/\-\-config CONFIG option
 .SH HOW TO CONFIGURE
-
+.PP
 The program can be configured by editing the config file.
-
+The configuration includes the following sections:
-.B The configuration includes the following sections:
+.IP \[bu] 2
-
+Memory levels to respond to as an OOM threat
-    - Memory levels to respond to as an OOM threat
+.IP \[bu] 2
-
+Response on PSI memory metrics
-    - Response on PSI memory metrics
+.IP \[bu] 2
-
+The frequency of checking the level of available memory (and CPU usage)
-    - The frequency of checking the level of available memory (and CPU usage)
+.IP \[bu] 2
-
+The prevention of killing innocent victims
-    - The prevention of killing innocent victims
+.IP \[bu] 2
-
+Impact on the badness of processes via matching their names, cmdlines
-    - Impact on the badness of processes via matching their names, cmdlines and UIDs with regular expressions
+and UIDs with regular expressions
-
+.IP \[bu] 2
-    - The execution of a specific command or sending any signal instead of sending the SIGTERM signal
+The execution of a specific command or sending any signal instead of
-
+sending the SIGTERM signal
-    - GUI notifications:
+.IP \[bu] 2
-        - notifications of corrective actions taken
+GUI notifications:
-        - low memory warnings
+.RS 2
-
+.IP \[bu] 2
-    - Verbosity
+notifications of corrective actions taken
-
+.IP \[bu] 2
-    - Misc
+low memory warnings
-
+.RE
+.IP \[bu] 2
+Verbosity
+.IP \[bu] 2
+Misc
+.PP
 Just read the description of the parameters and edit the values.
-
+Restart the daemon to apply the changes.
-Please restart nohang to apply the changes.
-
-Default path to the config after installing is /etc/nohang/nohang.conf.
-
 .SH HOW TO TEST
-
+.PP
-- The safest way is to run `nohang --memload`. This causes memory consumption, and the process will exits before OOM occurs.
+The safest way is to run \f[B]nohang \-\-memload\f[].
-- Another way is to run `tail /dev/zero`. This causes fast memory comsumption and causes OOM at the end.
+This causes memory consumption, and the process will exits before OOM
-
+occurs.
-If testing occurs while nohang is running, these processes should be terminated before OOM occurs.
+Another way is to run \f[B]tail /dev/zero\f[].
-
+This causes fast memory comsumption and causes OOM at the end.
+If testing occurs while nohang is running, these processes should be
+terminated before OOM occurs.
 .SH LOGGING
-
+.PP
 To view the latest entries in the log (for systemd users):
-
+.PP
-$ sudo journalctl -eu nohang
+$ \f[B]sudo journalctl \-eu nohang.service\f[]
-
+.PP
-See also man journalctl.
+or
-
+.PP
-You can also enable separate_log in the config to logging in /var/log/nohang/nohang.log.
+$ \f[B]sudo journalctl \-eu nohang\-desktop.service\f[]
-
+.PP
-.SH SEE ALSO
+You can also enable \f[B]separate_log\f[] in the config to logging in
-
+\f[B]/var/log/nohang/nohang.log\f[].
-https://github.com/hakavlad/nohang

man/oom-sort.1

@@ -1,5 +1,10 @@
-.TH oom-sort 1
+.\" Automatically generated by Pandoc 1.17.2
-
+.\"
+.TH "oom\-sort" "1" "" "" "General Commands Manual"
+.hy
 .SH NAME
-
+.PP
-oom-sort \- sort processes by oom_score
+oom\-sort \- sort processes by oom_score
+.SH SYNOPSIS
+.PP
+\f[B]oom\-sort\f[] [\f[B]OPTION\f[]]...

man/psi-top.1

@@ -1,5 +1,10 @@
-.TH psi-top 1
+.\" Automatically generated by Pandoc 1.17.2
-
+.\"
+.TH "psi\-top" "1" "" "" "General Commands Manual"
+.hy
 .SH NAME
-
+.PP
-psi-top \- psi-top
+psi\-top
+.SH SYNOPSIS
+.PP
+\f[B]psi\-top\f[] [\f[B]OPTION\f[]]...

man/psi2log.1

@@ -1,5 +1,10 @@
-.TH psi2log 1
+.\" Automatically generated by Pandoc 1.17.2
-
+.\"
+.TH "psi2log" "1" "" "" "General Commands Manual"
+.hy
 .SH NAME
-
+.PP
 psi2log \- PSI metrics monitor and logger
+.SH SYNOPSIS
+.PP
+\f[B]psi2log\f[] [\f[B]OPTION\f[]]...