From ed68589af16dde7e7c4e1e01f01b0969d2eb0565 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Otto=20Kek=C3=A4l=C3=A4inen?= 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 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 | 3 +++ CMakeLists.txt | 17 ++++++++++++++- Makefile | 31 ++++++++++++++++++++------- README.md | 30 +++++++++++++------------- manpage.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 114 insertions(+), 24 deletions(-) create mode 100644 manpage.md diff --git a/.gitignore b/.gitignore index c31e456..3a2cae2 100644 --- a/.gitignore +++ b/.gitignore @@ -46,6 +46,9 @@ stage/ *.out *.app +# Compiled man page +btop.1 + build bin btop diff --git a/CMakeLists.txt b/CMakeLists.txt index 01b3708..9a4dbec 100644 --- a/CMakeLists.txt +++ b/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") - diff --git a/Makefile b/Makefile index 03aea89..e489164 100644 --- a/Makefile +++ b/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)) diff --git a/README.md b/README.md index 5e01373..fdd4c31 100644 --- a/README.md +++ b/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** diff --git a/manpage.md b/manpage.md new file mode 100644 index 0000000..105a7c5 --- /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".