diff --git a/README.md b/README.md index 28bbe3c..ee54931 100644 --- a/README.md +++ b/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 -the usual cookies, there are also the local and session storage, the -IndexedDB API and more caches as well. +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. 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. +It was created for qutebrowser, but it actually supports the storage format +used by Chromium-based browsers, which (sadly) means almost every one nowadays. ## Installation -bisc is a Haskell program available on [Hackage][hackage] and can -be installed with one of the Haskell package managers. For -example, with [cabal-install][cabal] you would do +bisc is a Haskell program available on [Hackage][hackage] and can be installed +with one of the Haskell package managers. For example, with +[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 -under the attribute `haskellPackages.bisc`. It should also be in -the Nix binary cache so you don't have to build from source. +Alternatively, if you are using Nix or NixOS, bisc is available under the +attribute `haskellPackages.bisc`. It should also be in the Nix binary cache so +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`. -It allows to change the paths of the QtWebEngine/Chromium -directory and the whitelist file. +The bisc configuration file is `$XDG_CONFIG_HOME/bisc/bisc.conf`. It allows to +change the paths of the QtWebEngine/Chromium 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 -allowed cookies, one per line. +- Create an empty whitelist file and write the domains of the allowed cookies, + 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 diff --git a/bisc.cabal b/bisc.cabal index ab285d8..2a1b0e9 100644 --- a/bisc.cabal +++ b/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 diff --git a/default.nix b/default.nix index 90b6bde..0aa0192 100644 --- a/default.nix +++ b/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"; }); diff --git a/man/bisc.1 b/man/bisc.1 new file mode 100644 index 0000000..ad775bb --- /dev/null +++ b/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. diff --git a/man/bisc.conf.5 b/man/bisc.conf.5 new file mode 100644 index 0000000..e7a5b29 --- /dev/null +++ b/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.