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 a raw troff/groff
file.

Compile it to proper man page format at build-time using 'lowdown' if
it is available on the system, otherwise just issue a warning in yellow.

Tested to work both with:

    export VERBOSE=1
    make
    make install
    make uninstall

    cmake -B build
    cmake --build build --verbose

While Lowdown is easy to manually install in all modern Linux distros
and also Homebrew for Mac, this commit does not add 'lowdown' in any
build dependencies or in the CI, that needs to be done separately.

.gitignore

@@ -46,6 +46,9 @@ stage/
 *.out
 *.app
 
+# Compiled man page
+btop.1
+
 build
 bin
 btop

CMakeLists.txt

@@ -210,9 +210,24 @@ elseif(CMAKE_SYSTEM_NAME STREQUAL "OpenBSD")
   target_link_libraries(btop kvm::kvm)
 endif()
 
+
+# Check if lowdown is installed
+find_program(LOWDOWN_EXECUTABLE lowdown)
+
+if(LOWDOWN_EXECUTABLE)
+  # Custom target to compile Markdown to man page using lowdown
+  add_custom_target(btop.1 ALL
+      COMMAND lowdown -s -Tman -o btop.1 manpage.md
+      WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+  )
+  # Install the man page
+  install(FILES btop.1 DESTINATION "share/man/man1")
+else()
+  message(WARNING "Command 'lowdown' not found: skipping generating man page btop.1")
+endif()
+
 install(TARGETS btop RUNTIME)
 install(FILES "btop.desktop" DESTINATION "share/applications")
 install(FILES "Img/icon.png" DESTINATION "share/icons/hicolor/48x48/apps" RENAME "btop.png")
 install(FILES "Img/icon.svg" DESTINATION "share/icons/hicolor/scalable/apps" RENAME "btop.svg")
 install(DIRECTORY "themes" DESTINATION "share/btop")
-

Makefile

@@ -228,7 +228,7 @@ endif
 
 #? Default Make
 .ONESHELL:
-all: | info rocm_smi info-quiet directories config.h btop
+all: | info rocm_smi info-quiet directories btop.1 config.h btop
 
 ifneq ($(QUIET),true)
 info:
@@ -249,7 +249,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"
 
@@ -280,6 +279,15 @@ $(BUILDDIR)/config.h: $(SRCDIR)/config.h.in | directories
 	@$(VERBOSE) || printf 'sed -e "s|@GIT_COMMIT@|$(GIT_COMMIT)|" -e "s|@CONFIGURE_COMMAND@|$(CONFIGURE_COMMAND)|" -e "s|@COMPILER@|$(CXX)|" -e "s|@COMPILER_VERSION@|$(CXX_VERSION)|" $< | tee $@ > /dev/null\n'
 	@sed -e "s|@GIT_COMMIT@|$(GIT_COMMIT)|" -e "s|@CONFIGURE_COMMAND@|$(CONFIGURE_COMMAND)|" -e "s|@COMPILER@|$(CXX)|" -e "s|@COMPILER_VERSION@|$(CXX_VERSION)|" $< | tee $@ > /dev/null
 
+#? Man page
+btop.1: manpage.md | directories
+ifeq ($(shell command -v lowdown >/dev/null; echo $$?),0)
+	@printf "\n\033[1;92mGenerating man page $@\033[37m...\033[0m\n"
+	lowdown -s -Tman -o $@ $<
+else
+	@printf "\n\033[1;93mCommand 'lowdown' not found: skipping generating man page $@\033[0m\n"
+endif
+
 #? Clean only Objects
 clean:
 	@printf "\033[1;91mRemoving: \033[1;97mbuilt objects...\033[0m\n"
@@ -311,7 +319,11 @@ 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
-
+ifneq ($(wildcard btop.1),)
+	@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
+endif
 
 #? Set SUID bit for btop as $SU_USER in $SU_GROUP
 setuid:
@@ -321,17 +333,20 @@ setuid:
 	@printf "\033[1;92mSetting SUID bit\033[0m\n"
 	@chmod u+s $(DESTDIR)$(PREFIX)/bin/btop
 
+# With 'rm -v' user will see what files (if any) got removed
 uninstall:
 	@printf "\033[1;91mRemoving: \033[1;97m$(DESTDIR)$(PREFIX)/bin/btop\033[0m\n"
-	@rm -rf $(DESTDIR)$(PREFIX)/bin/btop
+	@rm -rfv $(DESTDIR)$(PREFIX)/bin/btop
 	@printf "\033[1;91mRemoving: \033[1;97m$(DESTDIR)$(PREFIX)/share/btop\033[0m\n"
-	@rm -rf $(DESTDIR)$(PREFIX)/share/btop
+	@rm -rfv $(DESTDIR)$(PREFIX)/share/btop
 	@printf "\033[1;91mRemoving: \033[1;97m$(DESTDIR)$(PREFIX)/share/applications/btop.desktop\033[0m\n"
-	@rm -rf $(DESTDIR)$(PREFIX)/share/applications/btop.desktop
+	@rm -rfv $(DESTDIR)$(PREFIX)/share/applications/btop.desktop
 	@printf "\033[1;91mRemoving: \033[1;97m$(DESTDIR)$(PREFIX)/share/icons/hicolor/48x48/apps/btop.png\033[0m\n"
-	@rm -rf $(DESTDIR)$(PREFIX)/share/icons/hicolor/48x48/apps/btop.png
+	@rm -rfv $(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
+	@rm -rfv $(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 -rfv $(DESTDIR)$(PREFIX)/share/man/man1/btop.1
 
 #? Pull in dependency info for *existing* .o files
 -include $(OBJECTS:.$(OBJEXT)=.$(DEPEXT))

README.md

@@ -106,7 +106,7 @@ If you want to help out, test for bugs/fix bugs or just try out the branches:
 **macOS / OSX**
 ```bash
 # Install and use Homebrew or MacPorts package managers for easy dependency installation
-brew install coreutils make gcc@11
+brew install coreutils make gcc@11 lowdown
 git clone https://github.com/aristocratos/btop.git
 cd btop
 git checkout OSX
@@ -115,7 +115,7 @@ gmake
 
 **FreeBSD**
 ```bash
-sudo pkg install gmake gcc11 coreutils git
+sudo pkg install gmake gcc11 coreutils git lowdown
 git clone https://github.com/aristocratos/btop.git
 cd btop
 git checkout freebsd
@@ -395,7 +395,7 @@ If you have an AMD GPU `rocm_smi_lib` is required, which may or may not be packa
 1. **Install dependencies (example for Ubuntu 21.04 Hirsute)**
 
    ```bash
-   sudo apt install coreutils sed git build-essential gcc-11 g++-11
+   sudo apt install coreutils sed git build-essential gcc-11 g++-11 lowdown
    ```
 
 2. **Clone repository**
@@ -486,12 +486,12 @@ If you have an AMD GPU `rocm_smi_lib` is required, which may or may not be packa
 
 1. **Install build dependencies**
 
-   Requires Clang / GCC, CMake, Ninja and Git
+   Requires Clang / GCC, CMake, Ninja, Lowdown and Git
 
    For example, with Debian Bookworm:
 
    ```bash
-   sudo apt install cmake git g++ ninja-build
+   sudo apt install cmake git g++ ninja-build lowdown
    ```
 
 2. **Clone the repository**
@@ -569,7 +569,7 @@ If you have an AMD GPU `rocm_smi_lib` is required, which may or may not be packa
 1. **Install dependencies (example for Homebrew)**
 
    ```bash
-   brew install coreutils make gcc@12
+   brew install coreutils make gcc@12 lowdown
    ```
 
 2. **Clone repository**
@@ -655,11 +655,11 @@ If you have an AMD GPU `rocm_smi_lib` is required, which may or may not be packa
 
 1. **Install build dependencies**
 
-   Requires Clang, CMake, Ninja and Git
+   Requires Clang, CMake, Ninja, Lowdown and Git
 
    ```bash
    brew update --quiet
-   brew install cmake git llvm ninja
+   brew install cmake git llvm ninja lowdown
    ```
 
 2. **Clone the repository**
@@ -736,7 +736,7 @@ If you have an AMD GPU `rocm_smi_lib` is required, which may or may not be packa
 1. **Install dependencies**
 
    ```bash
-   sudo pkg install gmake gcc11 coreutils git
+   sudo pkg install gmake gcc11 coreutils git lowdown
    ```
 
 2. **Clone repository**
@@ -823,18 +823,18 @@ If you have an AMD GPU `rocm_smi_lib` is required, which may or may not be packa
 
 1. **Install build dependencies**
 
-   Requires Clang / GCC, CMake, Ninja and Git
+   Requires Clang / GCC, CMake, Ninja, Lowdown and Git
 
    _**Note:** LLVM's libc++ shipped with FreeBSD 13 is too old and cannot compile btop._
 
 	FreeBSD 14 and later:
    ```bash
-   pkg install cmake ninja
+   pkg install cmake ninja lowdown
    ```
 
 	FreeBSD 13:
    ```bash
-   pkg install cmake gcc13 ninja
+   pkg install cmake gcc13 ninja lowdown
    ```
 
 2. **Clone the repository**
@@ -917,7 +917,7 @@ If you have an AMD GPU `rocm_smi_lib` is required, which may or may not be packa
 1. **Install dependencies**
 
    ```bash
-   pkg_add gmake gcc%11 g++%11 coreutils git
+   pkg_add gmake gcc%11 g++%11 coreutils git lowdown
    ```
 
 2. **Clone repository**
@@ -1004,12 +1004,12 @@ If you have an AMD GPU `rocm_smi_lib` is required, which may or may not be packa
 
 1. **Install build dependencies**
 
-   Requires GCC, CMake, Ninja and Git
+   Requires GCC, CMake, Ninja, Lowdown and Git
 
    _**Note:** LLVM's libc++ shipped with OpenBSD 7.4 is too old and cannot compile btop._
 
    ```bash
-   pkg_add cmake g++%11 git ninja
+   pkg_add cmake g++%11 git ninja lowdown
    ```
 
 2. **Clone the repository**

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".