Write man page #48

maltfield · 2022-12-08T00:46:36Z

This ticket will track the effort to write a manpage for the BusKill app that will be displayed when running man buskill on *nix systems.

This is a prerequisite to getting BusKill added to the official Debian repos in #31

Support for installing in apt (.deb) #31

The text was updated successfully, but these errors were encountered:

maltfield · 2022-12-08T00:51:05Z

The example given by @fmarier was this repo they hand-wrote for the pip-check-reqs package:

https://salsa.debian.org/debian/pip-check-reqs/-/blob/master/debian/pip-missing-reqs.1

The format it's written-in is called "Nroff"

https://en.wikipedia.org/wiki/Nroff

The GNU tool for parsing nroff files is "Groff"

maltfield · 2022-12-08T00:52:03Z

I poked around on a Debian system and found the man page for bzip2 in /usr/share/man/man1/

user@buskill:~$ zcat /usr/share/man/man1/bzip2.1.gz | head -n30
.TH bzip2 1
.SH NAME
bzip2, bunzip2 \- a block-sorting file compressor, v1.0.8
.br
bzcat \- decompresses files to stdout
.br
bzip2recover \- recovers data from damaged bzip2 files

.SH SYNOPSIS
.ll +8
.B bzip2
.RB [ " \-cdfkqstvzVL123456789 " ]
[
.I "filenames \&..."
]
.br
.B bzip2
.RB [ " \-h|\-\-help " ]
.ll -8
.br
.B bunzip2
.RB [ " \-fkvsVL " ]
[
.I "filenames \&..."
]
.br
.B bunzip2
.RB [ " \-h|\-\-help " ]
.br
.B bzcat
user@buskill:~$

I couldn't get it to be rendered using groff, but I found that if I use groffer then it magically opens the man page in evince (like a PDF)

user@buskill:~$ groffer /usr/share/man/man1/bzip2.1.gz
user@buskill:~$

woah, groffer has some awesome output modes!

	   groffer mode options

			   [--auto] [--default] [--default-modes mode1,mode2,...] [--dvi] [--groff] [--html] [--latin1]
			   [--mode display_mode] [--pdf] [--pdf2] [--ps] [--source] [--text] [--to-stdout] [--tty] [--utf8]
			   [--viewer prog] [--www] [--xhtml] [--x | --X]

Here's the 'text' mode

user@buskill:~$ groffer --text /usr/share/man/man1/bzip2.1.gz | head -n30
bzip2(1)                    General Commands Manual                   bzip2(1)



NAME
	   bzip2, bunzip2 - a block-sorting file compressor, v1.0.8
	   bzcat - decompresses files to stdout
	   bzip2recover - recovers data from damaged bzip2 files


SYNOPSIS
	   bzip2 [ -cdfkqstvzVL123456789 ] [ filenames ...  ]
	   bzip2 [ -h|--help ]
	   bunzip2 [ -fkvsVL ] [ filenames ...  ]
	   bunzip2 [ -h|--help ]
	   bzcat [ -s ] [ filenames ...  ]
	   bzcat [ -h|--help ]
	   bzip2recover filename


DESCRIPTION
	   bzip2  compresses  files  using  the Burrows-Wheeler block sorting text
	   compression algorithm, and Huffman coding.   Compression  is  generally
	   considerably   better   than   that   achieved   by  more  conventional
	   LZ77/LZ78-based compressors, and approaches the performance of the  PPM
	   family of statistical compressors.

	   The  command-line options are deliberately very similar to those of GNU
	   gzip, but they are not identical.

user@buskill:~$

Anyway, so this is pretty dope. But what's the best way to actually write a man page?

There's pandoc that converts between many different input & output formats (eg csv, epub, html, json, latex, markdown, mediawiki, man, odt, rst, etc) https://pandoc.org/MANUAL.html

(It also looks like Kramdown can convert markdown to roff)

This is probably not what I want, but I was able to convert my existing .rst documentation to the man page format. Here's the source

user@buskill:~$ pandoc sandbox/buskill-app/docs/software_usr/cli.rst -s -t man | head -n30
.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "BusKill App: Command-Line Interface" "" "" "" ""
.hy
.PP
This page will describe how to use the BusKill app in CLI mode.
.PP
To control BusKill via the CLI, use the same executable with arguments
(executing \f[C]buskill\f[R] without arguments opens it in GUI mode).
.SH Help
.PP
You can print a list of allowable arguments by passing the
\f[C]buskill\f[R] app \f[C]-h\f[R] or \f[C]--help\f[R]
.IP
.nf
\f[C]
user\[at]disp2781:\[ti]/Downloads/dist$ ./buskill.AppImage --help
\&...
usage: buskill [-h] [--version] [--list-triggers] [-v] [-t] [-T] [-a] [-U]

App for arming and configuring BusKill. For help, see https://docs.buskill.in

optional arguments:
  -h, --help         show this help message and exit
  --version          print version and exit.
  --list-triggers    List all available triggers.
  -v, --verbose      increase output verbosity
  -t , --trigger     Choose trigger to execute. See --list-triggers for all
					 possible values.
  -T, --run-trigger  Immediately execute the trigger on start
user@buskill:~$

And here's it rendered with man

user@buskill:~$ pandoc sandbox/buskill-app/docs/software_usr/cli.rst -s -t man | /usr/bin/man -l - | head -n30
BusKill App: Command-Line Interface()                                          BusKill App: Command-Line Interface()

	   This page will describe how to use the BusKill app in CLI mode.

	   To  control  BusKill via the CLI, use the same executable with arguments (executing buskill without arguments
	   opens it in GUI mode).

Help
	   You can print a list of allowable arguments by passing the buskill app -h or --help

			  user@disp2781:~/Downloads/dist$ ./buskill.AppImage --help
			  ...
			  usage: buskill [-h] [--version] [--list-triggers] [-v] [-t] [-T] [-a] [-U]

			  App for arming and configuring BusKill. For help, see https://docs.buskill.in

			  optional arguments:
				-h, --help         show this help message and exit
				--version          print version and exit.
				--list-triggers    List all available triggers.
				-v, --verbose      increase output verbosity
				-t , --trigger     Choose trigger to execute. See --list-triggers for all
								   possible values.
				-T, --run-trigger  Immediately execute the trigger on start
				-a, --arm          Arms BusKill
				-U, --upgrade      Download & upgrade latest version of BusKill
			  user@disp2781:~/Downloads/dist$

Arming
	   To arm BusKill, execute it with the -a or --arm argument
user@buskill:~$

fmarier · 2022-12-08T02:18:50Z

Sorry, I should have mentioned this too in my original note. There's a very easy way to render your man page (assuming it's called buskill.1):

man ./buskill.1

maltfield · 2022-12-08T02:24:07Z

Thanks :) I'm currently just trying to figure out the best-practice of:

Where to store the manpage in this repo
Whether to store it in this repo in [a] native-manpage's groff format or [b] reStructuredText like the rest of this project's documentation (and convert to groff format at build-time) or [c] some other pythonic best-practice for dynamically producing the manpage at build time

maltfield · 2022-12-09T17:19:19Z

I spent some time looking at other projects to see how they build and where they store their man pages

ansible: appears to be generated dynamically with some jinja2 FileSystemLoader? https://github.com/ansible/ansible/blob/2cbfd1e350cbe1ca195d33306b5a9628667ddda8/hacking/build_library/build_ansible/command_plugins/generate_man.py
cryptsetup has it in '/man/cryptsetup.8.adoc' https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/man/cryptsetup.8.adoc
flatpak: looks like the man pages are stored in 'doc/' under some .xml format named DocBook and then somehow converted to manpage format by ${AM_V_GEN} ${XSLTPROC} https://github.com/flatpak/flatpak/tree/main/doc
1. looks like this is XSTL Processor https://developer.mozilla.org/en-US/docs/Web/API/XSLTProcessor
kdenvlive has a groff-type file at data/man/kdenlive.1. At the top, a comment says the file was generated by kdemangen.pl https://github.com/KDE/kdenlive/blob/master/data/man/kdenlive.1
1. https://github.com/KDE/kde-dev-scripts/blob/master/kdemangen.pl
2. they used-to have a file named '/man/kdenlive.1', but it no longer exists https://github.com/KDE/kdenlive/blob/da670ef2418d0894fad0ef22b6908d69d7c19409/man/kdenlive.1
3. apparently it was moved to data/man/kdenlive.1 in 2014 KDE/kdenlive@5a7add2
nmap has a manpage in 'docs/nmap.1' with comments at the top indicating it was generated by "DocBook XSL Stylesheets v1.79.1" https://github.com/nmap/nmap/blob/master/docs/nmap.1
rclone has a file named 'rclone.1' in the root of its repo, which has a comment at the top indicating it was autogenerated by pandoc https://raw.githubusercontent.com/rclone/rclone/master/rclone.1
1. this is done in the Makefile https://github.com/rclone/rclone/blob/ce168ecac214c1d729cff0ce776e33b8ef978e13/Makefile#L123
2. it looks like the source is MANUAL.md https://raw.githubusercontent.com/rclone/rclone/master/MANUAL.md
VLC stores their manpage in 'docs/vlc.1' and at first-glance it does not appear to be autogenerated by some other tool https://github.com/videolan/vlc/blob/master/doc/vlc.1
zim has this script that does the bare-miniumum and just tells the user to go to their website, pulling the info dynamically from the github README.md and the python 'zim' class https://github.com/zim-desktop-wiki/zim-desktop-wiki/blob/1ccaffc181671a71b6d66cbe99ae14688db1fc6c/makeman.py
1. curiously, that differes from the actual man zim page that I have on my system

maltfield · 2022-12-09T17:23:43Z

I think the best short-term solution is to manually write our own man page in a .rst file somewhere in our docs/ directory. That way:

We can include the man page in our sphinx documentation, similar to how we do with LICENSE
We can use pandoc to spit-out the man-page in groff format, while keeping all this project's docs in rst format

A couple things I'm not currently going to do, but things we should consider long-term:

We could probably autogenerate sections of the man page directly from our sourcecode, such as the arguments section. But I'll skip that for now..
We should automatically produce/update a buskill.1 file in groff-format that lives in this repo as part of the CI pipeline

Note: the file "extension" .1 is used because it's the manpage for the general "user". Here's the different types of manpages (excerpt taken from man man)

       1   Executable programs or shell commands
       2   System calls (functions provided by the kernel)
       3   Library calls (functions within program libraries)
       4   Special files (usually found in /dev)
       5   File formats and conventions, e.g. /etc/passwd
       6   Games
       7   Miscellaneous (including macro packages and conventions),  e.g.  man(7),
           groff(7)
       8   System administration commands (usually only for root)
       9   Kernel routines [Non standard]

maltfield · 2022-12-09T22:40:59Z

Here's some examples of some .rst (source files written in reStructuredText) that are used to generate manpages in groff-format

maltfield · 2022-12-09T23:18:38Z

See also https://en.wikipedia.org/wiki/Comparison_of_documentation_generators

I guess the most common method of auto-generating manpages from the sample of other FOSS projects above was to use Doxygen

maltfield · 2022-12-10T01:23:53Z

See also:

maltfield · 2022-12-10T01:39:19Z

I created a new branch named manpage where this work is taking place:

Unfortunately, if I use `pandoc` to convert this new manpage.rst file to groff-format for `man`, it doesn't render correctly in `man` because it's missing the Title Heading (.TH). See Also: * #48 * https://tex.stackexchange.com/questions/668065/missing-th-section-when-converting-rst-file-to-groff-format-in-pandoc-restr * https://stackoverflow.com/questions/74749734/missing-th-section-when-converting-rst-file-to-groff-format-in-pandoc-restr

fmarier · 2022-12-10T03:01:58Z

This is some pretty in-depth research! It would almost be worth putting into a blog post so that it doesn't disappear into the issue tracker :)

maltfield · 2022-12-12T18:24:23Z

I managed to fix the issue where pandoc spat-out the groff file without the .TH section by merely adding the -s = --standalone to its execution. Now I get the desired start/end on the first-line, but it's still missing the short description in the middle for some reason.

user@buskill:~$ head -n10 sandbox/buskill-app/docs/software_usr/manpage.rst
.. _manpage:

============
 buskill(1)
============

-------------------------------------------------------------------------
Lock or shutdown if your device is stolen (for use with laptop kill cord)
-------------------------------------------------------------------------

user@buskill:~$ 
...
user@buskill:~$ pandoc -s sandbox/buskill-app/docs/software_usr/manpage.rst -t man | groffer --text | head -n10
buskill(1)                                                          buskill(1)



SYNOPSIS
              buskill --trigger soft-shutdown --arm

DESCRIPTION
       buskill  is  a cross-platform CLI and GUI app that can lock or shutdown
       your computer when a USB hotplug removal event occurs.
user@buskill:~$

See also https://stackoverflow.com/questions/74776173/how-to-set-all-arguments-of-the-title-line-in-manpage-written-in-restructuredtex

maltfield · 2022-12-13T00:33:01Z

From the pandoc manual, I found that you could ouput the "template" for the man output as follows

https://pandoc.org/MANUAL.html#templates

user@buskill:~$ pandoc -D man
$if(has-tables)$
.\"t
$endif$
$if(pandoc-version)$
.\" Automatically generated by Pandoc $pandoc-version$
.\"
$endif$
$if(adjusting)$
.ad $adjusting$
$endif$
.TH "$title/nowrap$" "$section/nowrap$" "$date/nowrap$" "$footer/nowrap$" "$header/nowrap$"
$if(hyphenate)$
.hy
$else$
.nh
$endif$
$for(header-includes)$
$header-includes$
$endfor$
$for(include-before)$
$include-before$
$endfor$
$body$
$for(include-after)$
$include-after$
$endfor$
$if(author)$
.SH AUTHORS
$for(author)$$author$$sep$; $endfor$.
$endif$
user@buskill:~$

* #48 * https://stackoverflow.com/a/74778925/1174102

maltfield · 2022-12-13T01:46:33Z

To add all the variable to populate the manpage template via pandoc, I had to specify some variables directly on the command-line when doing the conversion between the .rst file to the groff file.

So I hacked-up a simple script to wrap this command:

https://github.com/BusKill/buskill-app/blob/5efab6ae82d472115109111278dfa5c9c6164df3/docs/buildManpage.sh

maltfield · 2022-12-13T01:50:19Z

I've merged the manpage branch into dev, so it's now possible to create this project's manpage with the following commands

git clone https://github.com/BusKill/buskill-app.git
cd buskill-app
git checkout dev
docs/buildManpage.sh
man ./docs/buskill.1

I've confirmed this to be working on Debian 11. Here's an example execution

user@disp8329:~$ cat /etc/issue
Debian GNU/Linux 11 \n \l

user@disp8329:~$ git clone https://github.com/BusKill/buskill-app.git
Cloning into 'buskill-app'...
remote: Enumerating objects: 6422, done.
remote: Counting objects: 100% (647/647), done.
remote: Compressing objects: 100% (147/147), done.
remote: Total 6422 (delta 494), reused 635 (delta 487), pack-reused 5775
Receiving objects: 100% (6422/6422), 214.32 MiB | 2.36 MiB/s, done.
Resolving deltas: 100% (3655/3655), done.
user@disp8329:~$ 
user@disp8329:~$ cd buskill-app
user@disp8329:~/buskill-app$ 
user@disp8329:~/buskill-app$ git checkout dev
Branch 'dev' set up to track remote branch 'dev' from 'origin'.
Switched to a new branch 'dev'
user@disp8329:~/buskill-app$ 

user@disp8329:~/buskill-app$ docs/buildManpage.sh
++ which sudo
+ SUDO=/usr/bin/sudo
+ pwd
/home/user/buskill-app
+ env
SHELL=/bin/bash
QT_ACCESSIBILITY=1
COLORTERM=truecolor
GNOME_DESKTOP_SESSION_ID=c1
VMTYPE=AppVM
SSH_AUTH_SOCK=/tmp/ssh-DIoDTrHdLrT1/agent.973
QREXEC_AGENT_PID=11203
SSH_AGENT_PID=1039
XDG_SEAT=seat0
PWD=/home/user/buskill-app
LOGNAME=user
XDG_SESSION_TYPE=x11
GPG_AGENT_INFO=/run/user/1000/gnupg/S.gpg-agent:0:1
QREXEC_REQUESTED_TARGET_TYPE=
WINDOWPATH=7
HOME=/home/user
LANG=en_US.UTF-8
_JAVA_AWT_WM_NONREPARENTING=1
LS_COLORS=rs=0:di=01;34:ln=01;36:mh=00:pi=40;33:so=01;35:do=01;35:bd=40;33;01:cd=40;33;01:or=40;31;01:mi=00:su=37;41:sg=30;43:ca=30;41:tw=30;42:ow=34;42:st=37;44:ex=01;32:*.tar=01;31:*.tgz=01;31:*.arc=01;31:*.arj=01;31:*.taz=01;31:*.lha=01;31:*.lz4=01;31:*.lzh=01;31:*.lzma=01;31:*.tlz=01;31:*.txz=01;31:*.tzo=01;31:*.t7z=01;31:*.zip=01;31:*.z=01;31:*.dz=01;31:*.gz=01;31:*.lrz=01;31:*.lz=01;31:*.lzo=01;31:*.xz=01;31:*.zst=01;31:*.tzst=01;31:*.bz2=01;31:*.bz=01;31:*.tbz=01;31:*.tbz2=01;31:*.tz=01;31:*.deb=01;31:*.rpm=01;31:*.jar=01;31:*.war=01;31:*.ear=01;31:*.sar=01;31:*.rar=01;31:*.alz=01;31:*.ace=01;31:*.zoo=01;31:*.cpio=01;31:*.7z=01;31:*.rz=01;31:*.cab=01;31:*.wim=01;31:*.swm=01;31:*.dwm=01;31:*.esd=01;31:*.jpg=01;35:*.jpeg=01;35:*.mjpg=01;35:*.mjpeg=01;35:*.gif=01;35:*.bmp=01;35:*.pbm=01;35:*.pgm=01;35:*.ppm=01;35:*.tga=01;35:*.xbm=01;35:*.xpm=01;35:*.tif=01;35:*.tiff=01;35:*.png=01;35:*.svg=01;35:*.svgz=01;35:*.mng=01;35:*.pcx=01;35:*.mov=01;35:*.mpg=01;35:*.mpeg=01;35:*.m2v=01;35:*.mkv=01;35:*.webm=01;35:*.webp=01;35:*.ogm=01;35:*.mp4=01;35:*.m4v=01;35:*.mp4v=01;35:*.vob=01;35:*.qt=01;35:*.nuv=01;35:*.wmv=01;35:*.asf=01;35:*.rm=01;35:*.rmvb=01;35:*.flc=01;35:*.avi=01;35:*.fli=01;35:*.flv=01;35:*.gl=01;35:*.dl=01;35:*.xcf=01;35:*.xwd=01;35:*.yuv=01;35:*.cgm=01;35:*.emf=01;35:*.ogv=01;35:*.ogx=01;35:*.aac=00;36:*.au=00;36:*.flac=00;36:*.m4a=00;36:*.mid=00;36:*.midi=00;36:*.mka=00;36:*.mp3=00;36:*.mpc=00;36:*.ogg=00;36:*.ra=00;36:*.wav=00;36:*.oga=00;36:*.opus=00;36:*.spx=00;36:*.xspf=00;36:
VTE_VERSION=6203
QREXEC_SERVICE_FULL_NAME=qubes.StartApp+qubes-run-terminal
GNOME_TERMINAL_SCREEN=/org/gnome/Terminal/screen/bc59e1c6_55c1_45cc_944a_8f241d4c3635
QREXEC_SERVICE_ARGUMENT=qubes-run-terminal
UPDTYPE=NonUpdateableVM
XDG_SESSION_CLASS=user
TERM=xterm-256color
QUBES_ENV_SOURCED=1
QREXEC_REMOTE_DOMAIN=dom0
USER=user
GNOME_TERMINAL_SERVICE=:1.22
DISPLAY=:0
SHLVL=3
XDG_VTNR=7
XDG_SESSION_ID=c1
XDG_RUNTIME_DIR=/run/user/1000
XDG_DATA_DIRS=/home/user/.local/share/flatpak/exports/share:/var/lib/flatpak/exports/share:/usr/local/share:/usr/share
PATH=/usr/local/bin:/usr/bin:/bin:/usr/local/games:/usr/games
DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus
QT_X11_NO_MITSHM=1
OLDPWD=/home/user
_=/usr/bin/env
+ ls -lah
total 172K
drwxr-xr-x  8 user user 4.0K Dec 12 19:52 .
drwx------ 17 user user 4.0K Dec 12 19:50 ..
drwxr-xr-x  7 user user 4.0K Dec 12 19:52 build
-rw-r--r--  1 user user  957 Dec 12 19:52 CHANGELOG
drwxr-xr-x 13 user user 4.0K Dec 12 19:59 docs
drwxr-xr-x  8 user user 4.0K Dec 12 19:59 .git
drwxr-xr-x  4 user user 4.0K Dec 12 19:52 .github
-rw-r--r--  1 user user   40 Dec 12 19:52 .gitignore
-rw-r--r--  1 user user  86K Dec 12 19:52 KEYS
-rw-r--r--  1 user user  35K Dec 12 19:52 LICENSE
-rw-r--r--  1 user user 4.2K Dec 12 19:52 README.md
drwxr-xr-x  5 user user 4.0K Dec 12 19:52 src
drwxr-xr-x  3 user user 4.0K Dec 12 19:52 updates
++ git log -1 --pretty=%ct
+ export SOURCE_DATE_EPOCH=1670896703
+ SOURCE_DATE_EPOCH=1670896703
++ date '+%b %Y' --date=@1670896703
+ DATE='Dec 2022'
+ HEADER='Laptop Kill Cord'
++ pwd
++ basename docs/buildManpage.sh
+ '[' '!' -e /home/user/buskill-app/docs/buildManpage.sh ']'
+ /usr/bin/sudo apt-get update
Hit:1 https://deb.debian.org/debian bullseye InRelease                               
Hit:2 https://deb.qubes-os.org/r4.1/vm bullseye InRelease                            
Get:3 https://deb.debian.org/debian-security bullseye-security InRelease [48.4 kB]
Get:4 https://deb.debian.org/debian-security bullseye-security/main amd64 Packages [210 kB]
Get:5 https://deb.debian.org/debian-security bullseye-security/main Translation-en [136 kB]
Fetched 394 kB in 2s (232 kB/s)     
Reading package lists... Done
+ /usr/bin/sudo apt-get -y install pandoc
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following packages were automatically installed and are no longer required:
  ethtool libbotan-2-17 libtspi1 linux-image-5.10.0-10-amd64
  linux-image-5.10.0-13-amd64 linux-image-5.10.0-14-amd64
  linux-image-5.10.0-15-amd64 linux-image-5.10.0-16-amd64
  linux-image-5.10.0-17-amd64 net-tools sse3-support
Use 'sudo apt autoremove' to remove them.
The following additional packages will be installed:
  libcmark-gfm-extensions0 libcmark-gfm0 pandoc-data
Suggested packages:
  texlive-xetex texlive-luatex pandoc-citeproc context wkhtmltopdf ghc nodejs php
  python r-base-core libjs-mathjax node-katex citation-style-language-styles
The following NEW packages will be installed:
  libcmark-gfm-extensions0 libcmark-gfm0 pandoc pandoc-data
0 upgraded, 4 newly installed, 0 to remove and 17 not upgraded.
Need to get 19.0 MB of archives.
After this operation, 157 MB of additional disk space will be used.
Get:1 https://deb.debian.org/debian bullseye/main amd64 libcmark-gfm0 amd64 0.29.0.gfm.0-6 [117 kB]
Get:2 https://deb.debian.org/debian bullseye/main amd64 libcmark-gfm-extensions0 amd64 0.29.0.gfm.0-6 [46.1 kB]
Get:3 https://deb.debian.org/debian bullseye/main amd64 pandoc-data all 2.9.2.1-1 [376 kB]
Get:4 https://deb.debian.org/debian bullseye/main amd64 pandoc amd64 2.9.2.1-1+b1 [18.5 MB]
Fetched 19.0 MB in 5s (4,013 kB/s) 
Selecting previously unselected package libcmark-gfm0:amd64.
(Reading database ... 405423 files and directories currently installed.)
Preparing to unpack .../libcmark-gfm0_0.29.0.gfm.0-6_amd64.deb ...
Unpacking libcmark-gfm0:amd64 (0.29.0.gfm.0-6) ...
Selecting previously unselected package libcmark-gfm-extensions0:amd64.
Preparing to unpack .../libcmark-gfm-extensions0_0.29.0.gfm.0-6_amd64.deb ...
Unpacking libcmark-gfm-extensions0:amd64 (0.29.0.gfm.0-6) ...
Selecting previously unselected package pandoc-data.
Preparing to unpack .../pandoc-data_2.9.2.1-1_all.deb ...
Unpacking pandoc-data (2.9.2.1-1) ...
Selecting previously unselected package pandoc.
Preparing to unpack .../pandoc_2.9.2.1-1+b1_amd64.deb ...
Unpacking pandoc (2.9.2.1-1+b1) ...
Setting up libcmark-gfm0:amd64 (0.29.0.gfm.0-6) ...
Setting up pandoc-data (2.9.2.1-1) ...
Setting up libcmark-gfm-extensions0:amd64 (0.29.0.gfm.0-6) ...
Setting up pandoc (2.9.2.1-1+b1) ...
Processing triggers for man-db (2.9.4-2) ...
Processing triggers for libc-bin (2.31-13+deb11u4) ...
Scanning processes...                                                                 
Scanning linux images...                                                              

No services need to be restarted.

No containers need to be restarted.

No user sessions are running outdated binaries.
++ which pandoc
+ PANDOC=/usr/bin/pandoc
+ /usr/bin/pandoc -s -t man --variable 'header=Laptop Kill Cord' --variable 'date=Dec 2022' --variable footer= docs/software_usr/manpage.rst -o docs/buskill.1
+ exit 0
user@disp8329:~/buskill-app$ 

user@disp8329:~/buskill-app$ man docs/buskill.1 
user@disp8329:~/buskill-app$

maltfield · 2022-12-13T02:01:40Z

@fmarier can you please confirm if this man page meet's Debian's needs?

.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "buskill" "1" "Dec 2022" "" "Laptop Kill Cord"
.hy
.SH NAME
.PP
buskill - Lock or shutdown if your device is stolen (for use with laptop
kill cord)
.SH SYNOPSIS
.PP
buskill [options]
.SH DESCRIPTION
.PP
buskill is a cross-platform CLI and GUI app that can lock or shutdown
your computer when a USB hotplug removal event occurs.
.PP
It\[aq]s designed to work with the BusKill laptop kill cord, which is a
hardware dead man switch that tethers a user to their computer via a USB
cable with an integrated magnetic breakaway.
If the cable is disconnected (eg by a snatch-and-run thief stealing the
user\[aq]s machine), then this software can trigger the computer to lock
or shutdown -- thus protecting encrypted files (eg bitcoin private keys)
or current login sessions (eg online banking) from theft.
.SH OPTIONS
.IP
.nf
\f[C]
-h, --help         show this help message and exit
--version          print version and exit.
--list-triggers    List all available triggers.
-v, --verbose      increase output verbosity
-t , --trigger     Choose trigger to execute. See --list-triggers for all
                   possible values.
-T, --run-trigger  Immediately execute the trigger on start
-a, --arm          Arms BusKill
\f[R]
.fi
.SH EXAMPLES
.PP
\f[B]buskill --list-triggers\f[R] : Display all possible triggers, then
exits.
.PP
\f[B]buskill --trigger lock-screen --arm\f[R] : Arm the buskill app with
the \[aq]lock-screen\[aq] trigger so that a USB hotplug removal event
will lock the device\[aq]s screen
.PP
\f[B]buskill --trigger soft-shutdown --arm\f[R] : Arm the buskill app
with the \[aq]soft-shutdown\[aq] trigger so that a USB hotplug removal
event will cause the device to shutdown
.SH SEE ALSO
.PP
This manpage is limited in scope.
The BusKill project\[aq]s main documentation (complete with images and
videos) is available at docs.buskill.in (https://docs.buskill.in)
.IP \[bu] 2
Full Documentation (https://docs.buskill.in)
.IP \[bu] 2
Official BusKill Project Website (https://buskill.in)
.SH AUTHORS
Michael Altfield (<[email protected]>) and The BusKill Team
(<https://buskill.in/contact>).

fmarier · 2022-12-13T06:42:34Z

@maltfield That looks good to me.

I filed #50 for a few nits, but even without it would be good.

maltfield · 2022-12-13T21:34:25Z

Merged PR #50. Thank you!

I'm marking this ticket as complete, and now #31 is unblocked.

fmarier · 2022-12-20T17:47:25Z

Just to add to your list of manpage resources, here's a very good guide I had forgotten about: https://liw.fi/manpages/

maltfield self-assigned this Dec 8, 2022

maltfield added the documentation Improvements or additions to documentation label Dec 8, 2022

maltfield added a commit that referenced this issue Dec 13, 2022

finished first draft of manpage

5efab6a

* #48 * https://stackoverflow.com/a/74778925/1174102

maltfield closed this as completed Dec 13, 2022

maltfield mentioned this issue Dec 13, 2022

Support for installing in apt (.deb) #31

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Write man page #48

Write man page #48

maltfield commented Dec 8, 2022

maltfield commented Dec 8, 2022

maltfield commented Dec 8, 2022 •

edited

Loading

fmarier commented Dec 8, 2022

maltfield commented Dec 8, 2022

maltfield commented Dec 9, 2022 •

edited

Loading

maltfield commented Dec 9, 2022 •

edited

Loading

maltfield commented Dec 9, 2022

maltfield commented Dec 9, 2022 •

edited

Loading

maltfield commented Dec 10, 2022 •

edited

Loading

maltfield commented Dec 10, 2022 •

edited

Loading

fmarier commented Dec 10, 2022

maltfield commented Dec 12, 2022 •

edited

Loading

maltfield commented Dec 13, 2022 •

edited

Loading

maltfield commented Dec 13, 2022

maltfield commented Dec 13, 2022 •

edited

Loading

maltfield commented Dec 13, 2022 •

edited

Loading

fmarier commented Dec 13, 2022

maltfield commented Dec 13, 2022 •

edited

Loading

fmarier commented Dec 20, 2022

Write man page #48

Write man page #48

Comments

maltfield commented Dec 8, 2022

maltfield commented Dec 8, 2022

maltfield commented Dec 8, 2022 • edited Loading

fmarier commented Dec 8, 2022

maltfield commented Dec 8, 2022

maltfield commented Dec 9, 2022 • edited Loading

maltfield commented Dec 9, 2022 • edited Loading

maltfield commented Dec 9, 2022

maltfield commented Dec 9, 2022 • edited Loading

maltfield commented Dec 10, 2022 • edited Loading

maltfield commented Dec 10, 2022 • edited Loading

fmarier commented Dec 10, 2022

maltfield commented Dec 12, 2022 • edited Loading

maltfield commented Dec 13, 2022 • edited Loading

maltfield commented Dec 13, 2022

maltfield commented Dec 13, 2022 • edited Loading

maltfield commented Dec 13, 2022 • edited Loading

fmarier commented Dec 13, 2022

maltfield commented Dec 13, 2022 • edited Loading

fmarier commented Dec 20, 2022

maltfield commented Dec 8, 2022 •

edited

Loading

maltfield commented Dec 9, 2022 •

edited

Loading

maltfield commented Dec 9, 2022 •

edited

Loading

maltfield commented Dec 9, 2022 •

edited

Loading

maltfield commented Dec 10, 2022 •

edited

Loading

maltfield commented Dec 10, 2022 •

edited

Loading

maltfield commented Dec 12, 2022 •

edited

Loading

maltfield commented Dec 13, 2022 •

edited

Loading

maltfield commented Dec 13, 2022 •

edited

Loading

maltfield commented Dec 13, 2022 •

edited

Loading

maltfield commented Dec 13, 2022 •

edited

Loading