From 4ae0323328f9cd569ac6c571a43dddcd4640c4ab Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Otto=20Kek=C3=A4l=C3=A4inen?= <otto@debian.org>
Date: Wed, 17 Jan 2024 21:10:48 -0800
Subject: [PATCH] Create man page for btop in Markdown

Create a man page in Markdown format so that it can be read online on
GitHub etc and it can be edited much more easily than raw troff/groff
files.

Compile it to proper man page format at build-time using 'lowdown' which
is available in all modern Linux distros and also Homebrew for Mac.
This commit does however not add 'lowdown' in any build dependencies or
in the CI, that needs to be done separately.
---
 .gitignore |  3 +++
 Makefile   | 12 +++++++++---
 manpage.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 69 insertions(+), 3 deletions(-)
 create mode 100644 manpage.md

diff --git a/.gitignore b/.gitignore
index 7e2ed8f73..08b0687da 100644
--- a/.gitignore
+++ b/.gitignore
@@ -46,6 +46,9 @@ stage/
 *.out
 *.app
 
+# Compiled man page
+btop.1
+
 build
 bin
 btop
diff --git a/Makefile b/Makefile
index ed808995a..db7dd92c0 100644
--- a/Makefile
+++ b/Makefile
@@ -222,7 +222,7 @@ endif
 
 #? Default Make
 .ONESHELL:
-all: | info rocm_smi info-quiet directories btop
+all: | info rocm_smi info-quiet directories btop # btop.1 (man page disabled from default build until CI has lowdown added)
 
 ifneq ($(QUIET),true)
 info:
@@ -243,7 +243,6 @@ info:
 	 @true
 endif
 
-
 info-quiet: | info rocm_smi
 	@printf "\n\033[1;92mBuilding btop++ \033[91m(\033[97mv$(BTOP_VERSION)\033[91m) \033[93m$(PLATFORM) \033[96m$(ARCH)\033[0m\n"
 
@@ -298,7 +297,9 @@ install:
 	@printf "\033[1;92mInstalling SVG icon to: \033[1;97m$(DESTDIR)$(PREFIX)/share/icons/hicolor/scalable/apps/btop.svg\n"
 	@mkdir -p $(DESTDIR)$(PREFIX)/share/icons/hicolor/scalable/apps
 	@cp -p Img/icon.svg $(DESTDIR)$(PREFIX)/share/icons/hicolor/scalable/apps/btop.svg
-
+	#@printf "\033[1;92mInstalling man page to: \033[1;97m$(DESTDIR)$(PREFIX)/share/man/man1/btop.1/\n"
+	#@mkdir -p $(DESTDIR)$(PREFIX)/share/man/man1
+	#@cp -p btop.1 $(DESTDIR)$(PREFIX)/share/man/man1/btop.1
 
 #? Set SUID bit for btop as $SU_USER in $SU_GROUP
 setuid:
@@ -319,6 +320,11 @@ uninstall:
 	@rm -rf $(DESTDIR)$(PREFIX)/share/icons/hicolor/48x48/apps/btop.png
 	@printf "\033[1;91mRemoving: \033[1;97m$(DESTDIR)$(PREFIX)/share/icons/hicolor/scalable/apps/btop.svg\033[0m\n"
 	@rm -rf $(DESTDIR)$(PREFIX)/share/icons/hicolor/scalable/apps/btop.svg
+	#@printf "\033[1;91mRemoving: \033[1;97m$(DESTDIR)$(PREFIX)/share/man/man1/btop.1\033[0m\n"
+	#@rm -rf $(DESTDIR)$(PREFIX)/share/man/man1/btop.1
+
+btop.1: manpage.md
+	lowdown -s -Tman -o $@ $<
 
 #? Pull in dependency info for *existing* .o files
 -include $(OBJECTS:.$(OBJEXT)=.$(DEPEXT))
diff --git a/manpage.md b/manpage.md
new file mode 100644
index 000000000..105a7c547
--- /dev/null
+++ b/manpage.md
@@ -0,0 +1,57 @@
+% btop(1) | User Commands
+%
+% "January  4 2024"
+
+# NAME
+
+btop - Resource monitor that shows usage and stats for processor, memory, disks, network, and processes.
+
+# SYNOPSIS
+
+**btop** [**-lc**] [**-t** | **+t**] [**-p** _id_] [**\-\-utf-force**]
+         [**\-\-debug**] [{**-h** | **\-\-help**} | {**-v** | **\-\-version**}]
+
+# DESCRIPTION
+
+**btop** is a program that shows usage and stats for processor, memory, disks, network, and processes.
+
+# OPTIONS
+
+The program follows the usual GNU command line syntax, with long options
+starting with two dashes ('-'). A summary of options is included below.
+
+**-lc**, **\-\-low-color**
+:   Disable truecolor, converts 24-bit colors to 256-color.
+
+**-t**, **\-\-tty_on**
+:   Force (ON) tty mode, max 16 colors and tty-friendly graph symbols.
+
+**+t**, **\-\-tty_off**
+:   Force (OFF) tty mode.
+
+**-p**, **\-\-preset _id_**
+:   Start with preset, integer value between 0-9.
+
+**\-\-utf-force**
+:   Force start even if no UTF-8 locale was detected.
+
+**\-\-debug**
+:   Start in DEBUG mode: shows microsecond timer for information collect and screen draw functions and sets loglevel to DEBUG.
+
+**-h**, **\-\-help**
+:   Show summary of options.
+
+**-v**, **\-\-version**
+:   Show version of program.
+
+# BUGS
+
+The upstream bug tracker can be found at https://github.com/aristocratos/btop/issues.
+
+# SEE ALSO
+
+**top**(1), **htop**(1)
+
+# AUTHOR
+
+**btop** was written by Jakob P. Liljenberg a.k.a. "Aristocratos".