Create man page for btop in Markdown #724
Conversation
|
@aristocratos Hi! Could you consider merging this? If there is one manpage in the repo it will be much easier for others to contribute and enrich it as there is a file to target. |
|
@ottok Will take a look at it later today and add some automation to build if Otherwise looks good 👍 |
|
I am happy to polish this myself, just give pointers on what changes you
want to have so it is mergeable.
|
|
@ottok And a note in the README.md that |
|
Without Lowdown CI passes:
Make and CMake output this and builds pass despite the intentional warning:
|
|
@aristocratos Please give advice on how to get Snapcraft build dependencies defined correctly. Other than that this PR is ready. When Lowdown is present CMake will output:
And regular Make:
|
|
@ottok Not sure why the snap build is completely failing, since with your current Makefile and cmake changes the missing lowdown should be ignored. @kz6fittycent Do you know what the issue with the snap build is? |
|
@ottok Oh right, should also add a note in the README.md about |
Please read the second commit and message: I did add lowdown to Snap build but for some reason it does not install it. README.md updated now. |
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.
Building the man page is optional and happens automatically if command 'lowdown' is present on the system. Add it to all possible GitHub CI files so man page conversion will be tested and fully used. Unfortunately 'lowdown' cannot be added to the musl jobs the program is available only starting from Alpine v3.15, while the musl Docker images run Alpine v3.14 (and haven't been updated in 2+ years). Also, the Snap build used Ubuntu 20.04 "Focal" which equally is too old to include Lowdown, which is available only from Ubuntu 22.04 "Jammy" onward: https://packages.ubuntu.com/search?suite=all&searchon=names&keywords=lowdown
|
Ok, I figured out that the Snap build actually runs on Ubuntu 20.04 which is too old to include Lowdown: https://packages.ubuntu.com/search?suite=all&searchon=names&keywords=lowdown Added comment there now instead. This should be ready to be merged now. |
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.
This was split out from #715.
I am aware that several man pages for btop already exists. We just need one merged upstream first so that the various authors can start to target that one and same file with improvements.
Some say btop is 'too small' or simple to have a man page. There is no such thing as too small - all Unix/Linux commands must have a man page. The gap between reading a man page online or offline is significant to the effort of having a live system and running
btop --helpso see the current help in lack of a man page. If the command is small, then the man page is small and easy to maintain. Smallness/simplicity is not an excuse to not have a man page.