doc: add manual pages

README.md

@@ -2,29 +2,28 @@
 
 ### A small tool that clears cookies (and more)
 
-Websites can store unwanted data using all sorts of methods: besides
+Websites can store unwanted data using all sorts of methods: besides the usual
-the usual cookies, there are also the local and session storage, the
+cookies, there are also the local and session storage, the IndexedDB API and
-IndexedDB API and more caches as well.
+more caches as well.
 
 bisc will try to go through each of them and remove all information from
 websites that are not explicitly allowed (ie. a whitelist of domains).
-It was created for qutebrowser, but it actually supports the storage
+It was created for qutebrowser, but it actually supports the storage format
-format used by Chromium-based browsers, which (sadly) means almost
+used by Chromium-based browsers, which (sadly) means almost every one nowadays.
-every one nowadays.
 
 ## Installation
 
-bisc is a Haskell program available on [Hackage][hackage] and can
+bisc is a Haskell program available on [Hackage][hackage] and can be installed
-be installed with one of the Haskell package managers. For
+with one of the Haskell package managers. For example, with
-example, with [cabal-install][cabal] you would do
+[cabal-install][cabal] you would do
 ```
 cabal install bisc
 ```
 and similarly for [stack][stack].
 
-Alternatively, if you are using Nix or NixOS, bisc is available
+Alternatively, if you are using Nix or NixOS, bisc is available under the
-under the attribute `haskellPackages.bisc`. It should also be in
+attribute `haskellPackages.bisc`. It should also be in the Nix binary cache so
-the Nix binary cache so you don't have to build from source.
+you don't have to build from source.
 
 Finally, statically compiled binaries can be found in the
 [releases](/git/rnhmjoj/bisc/releases).
@@ -35,9 +34,8 @@ Finally, statically compiled binaries can be found in the
 
 ## Configuration
 
-The bisc configuration file is `$XDG_CONFIG_HOME/bisc/bisc.conf`.
+The bisc configuration file is `$XDG_CONFIG_HOME/bisc/bisc.conf`.  It allows to
-It allows to change the paths of the QtWebEngine/Chromium
+change the paths of the QtWebEngine/Chromium directory and the whitelist file.
-directory and the whitelist file.
 The default settings are:
 ```
 whitelist-path = "$(XDG_CONFIG_HOME)/qutebrowser/whitelists/cookies"
@@ -49,16 +47,16 @@ using the `--config` command line option.
 
 ## Usage
 
-Create an empty whitelist file and write the domains of the
+- Create an empty whitelist file and write the domains of the allowed cookies,
-allowed cookies, one per line.
+  one per line.
 Eg.
 ```
 .example.com
 example.com
 ```
 
-Run `bisc` to delete all non-whitelisted data from qutebrowser.
+- Run `bisc --dry-run` to see what would be deleted without actually doing it.
-Run `bisc --dry-run` to see what would be deleted without actually doing it.
+- Run `bisc` to delete all non-whitelisted data from qutebrowser.
 
 Note that running bisc while the browser is open is not safe: this means it
 could possibly **corrupt** the databases. Hoever, corruption in the sqllite

bisc.cabal

@@ -22,7 +22,7 @@ maintainer:          rnhmjoj@inventati.org
 copyright:           Copyright (C) 2021 Michele Guerini Rocco
 category:            Utility
 build-type:          Simple
-extra-source-files:  README.md
+extra-source-files:  README.md, man/bisc.1 man/bisc.conf.5
 cabal-version:       >=1.10
 
 source-repository head

default.nix

@@ -32,6 +32,7 @@ let
       $out/bin/bisc --zsh-completion-script  "$out/bin/bisc" > bisc.zsh
 
       installShellCompletion bisc.{bash,fish,zsh}
+      installManPage man/*.[0-9]
     '';
     postFixup = optionalString static "rm -r $out/nix-support";
   });

man/bisc.1

@@ -0,0 +1,70 @@
+.TH bisc 1 "Semptember 7, 2021" "bisc 0.4.0" "User Commands"
+
+.SH NAME
+bisc - a small tool that clears cookies (and more)
+
+.SH SYNOPSIS
+.B bisc
+.RI [ option ]
+
+.SH DESCRIPTION
+.PP
+Websites can store unwanted data using all sorts of methods: besides the usual
+cookies, there are also the local and session storage, the IndexedDB API and
+more caches as well.
+.PP
+Bisc will try to go through each of them and remove all information from
+websites that are not explicitly allowed (ie. a whitelist of domains).
+It was created for qutebrowser, but it actually supports the storage format
+used by Chromium-based browsers, which (sadly) means almost every one nowadays.
+
+.SH USAGE
+.IP \(bu 2
+Create an empty whitelist file (see the FILES section) and write the domains of
+the allowed cookies, one per line. For example:
+.IP
+.nf
+\fC
+\&.example.com
+example.com
+\fR
+.fi
+.IP \(bu 2
+Run \fCbisc --dry-run\fR to see what would be deleted without actually
+doing it.
+.IP \(bu 2
+Run \fCbisc\fR to delete all non-whitelisted data from qutebrowser.
+
+.SH OPTIONS
+.TP
+.BR -c ","\ --config\  FILE
+Use FILE as the configuration file.
+.TP
+.BR -n ","\ --dry-run
+Don't actually remove anything, just show what would be done.
+.TP
+.BR -h ","\ --help
+Show the program information and help screen.
+
+.SH FILES
+.TP
+.I $XDG_CONFIG_HOME/bisc/bisc.conf
+Bisc configuration
+.TP
+.I $XDG_CONFIG_HOME/qutebrowser/whitelists/cookies
+Domain whitelist
+.TP
+.I $XDG_DATA_HOME/qutebrowser/webengine
+Chromium/QtWebEngine state directory
+.PP
+Note: when the variable $XDG_CONFIG_HOME or $XDG_DATA_HOME is not set,
+$HOME/.config and $HOME/.local/share respectively, will be used instead.
+
+.SH SEE ALSO
+\fBbisc.conf\fR(5) for the bisc configuration file
+
+.SH AUTHORS
+Copyright © 2021 Michele Guerini Rocco.
+.TP 0
+Released under the GPL, version 3 or greater.
+This software carries no warranty of any kind.

man/bisc.conf.5

@@ -0,0 +1,49 @@
+.TH bisc.conf 5 "Semptember 7, 2021" "bisc 0.4.0"
+
+.SH NAME
+bisc.conf - bisc configuration file
+
+.SH SYNOPSIS
+
+The bisc configuration file, found at the following locations, unless specified
+via the \fC-c\fR command line option:
+.IP \(bu 3
+$XDG_CONFIG_HOME/bisc/bisc.conf,
+.IP \(bu 3
+$HOME/.config/bisc/bisc.conf (when $XDG_CONFIG_HOME is not set)
+
+.SH DESCRIPTION
+.PP
+The bisc.conf file allows to change the default location of a couple of files
+used by bisc.
+
+.SH OPTIONS
+
+.TP 4
+.BR "webengine-path"  "  (default " "$(XDG_DATA_HOME)/qutebrowser/webengine")
+The location of the Chromium/QtWebEngine state directory.
+.TP 4
+.BR "whitelist-path"  "  (default " "$(XDG_CONFIG_HOME)/qutebrowser/whitelists/cookies")
+The location of the domain whitelist.
+
+.SH EXAMPLE
+
+This is an example configuration:
+.IP
+.nf
+\fC
+# This is a comment
+whitelist-path = "/home/alice/docs/cookie-whitelist"
+# You can also access environment variables:
+webengine-path = "$(HOME)/.local/qutebrowser/webengine"
+\fR
+.fi
+
+.SH SEE ALSO
+\fBbisc\fR(1) for the bisc command
+
+.SH AUTHORS
+Copyright © 2021 Michele Guerini Rocco.
+.TP 0
+Released under the GPL, version 3 or greater.
+This software carries no warranty of any kind.