nvim: Add vim-scimark plugin

.dotter/global.toml

@@ -4,7 +4,7 @@
 #       a development environment based on git and nvim.
 
 [base]
-depends = ["shell", "vcs", "nvim", "scripts", "ssh", "terminal", "bootstrap"]
+depends = ["shell", "git", "nvim", "scripts", "ssh", "terminal", "bootstrap"]
 
 [bootstrap.files]
 "bootstrap/dotlink.sh" = "~/.config/sh/alias.d/dotlink.sh"
@@ -13,13 +13,9 @@ depends = ["shell", "vcs", "nvim", "scripts", "ssh", "terminal", "bootstrap"]
 "sh/README.md" = { target = "~/NOWHERE", type = "symbolic", if = "false" }
 sh = "~"
 
-[vcs.files]
+[git.files]
-"vcs/README.md" = { target = "~/NOWHERE", type = "symbolic", if = "false" }
+"git/README.md" = { target = "~/NOWHERE", type = "symbolic", if = "false" }
-"vcs/git/config" = "~/.config"
+git = "~"
-"vcs/jj/config" = "~/.config"
-"vcs/gitignore/config" = "~/.config"
-"vcs/gitignore/local" = "~/.local"
-vcs = "~"
 
 [nvim.files]
 "nvim/.config/nvim/spell/de.utf-8.add.spl" = { target = "~/.config/nvim/spell/de.utf-8.add.spl", type = "symbolic" }
@@ -71,14 +67,8 @@ social = "~"
 
 [writing.files]
 "writing/README.md" = { target = "~/NOWHERE", type = "symbolic", if = "false" }
-"writing/jrnl/config" = "~/.config"
+"writing/.config/papis/papistui.yaml" = { target = "~/.config/papis/papistui.yaml", type = "symbolic" }
-"writing/papis/config/papis/papistui.yaml" = { target = "~/.config/papis/papistui.yaml", type = "symbolic" }
+"writing/.config/sioyek/prefs_user.config" = { target = "~/.config/sioyek/prefs_user.config", type = "template", prepend = "# TEMPLATED BY DOTTER\n" }
-"writing/papis/config" = "~/.config"
-"writing/sioyek/config/sioyek/prefs_user.config" = { target = "~/.config/sioyek/prefs_user.config", type = "template", prepend = "# TEMPLATED BY DOTTER\n" }
-"writing/sioyek/config" = "~/.config"
-"writing/zathura/config" = "~/.config"
-"writing/zk/config" = "~/.config"
-"writing/pandoc/local" = "~/.local"
 writing = "~"
 
 # WORKSTATION: A desktop machine, with wayland environment and display attached.

git/README.md

@@ -1,17 +1,15 @@
-# Version control software module
+# Git module
 
 [git](https://git-scm.com/) - a distributed version control system
-[jujutsu](https://martinvonz.github.io/jj/latest/) - a change-based version control system
 
 ## What's in this module
 
 [[_TOC_]]
 
-## Global vcs settings
+## Global git settings
 
-This are probably the first things that need to be customized, since it points to a different identity for each git user.
+This is probably the first thing that needs to be customized, since it points to a different identity for each git user.
 I sign all my commits by default, so take out the corresponding lines if you don't, or exchange it with your gpg key.
-Similarly for jujutsu, change the identity and remove the lines concerning gpg signing if you don't use it.
 
 Git will rewrite any remotes using http(s) to use the ssh notation for pushes to github and gitlab so that, even if you set up the repository using an https url you can utilize your usual ssh key for pushing.
 

nvim/.config/nvim/lazy-lock.json

@@ -48,11 +48,9 @@
   "mdeval.nvim": { "branch": "master", "commit": "2c32e2f3e7d8f222e7a4724989f218d036e1081d" },
   "mini.nvim": { "branch": "main", "commit": "19e1584124cda35388d4fdb911eab7124014e541" },
   "molten-nvim": { "branch": "main", "commit": "eb6d0fe33e14989b0f1fbe25d9732889ee57bd1a" },
-  "neo-tree.nvim": { "branch": "main", "commit": "8c75e8a2949cd6cd35525799200a8d34471ee9eb" },
   "neogen": { "branch": "main", "commit": "dc50715c009f89b8111197fd2f282f6042daa7ea" },
   "neotest": { "branch": "master", "commit": "32ff2ac21135a372a42b38ae131e531e64833bd3" },
   "neotest-python": { "branch": "master", "commit": "e5bff6dcf3cb33e6dfb97722e142961099c6021e" },
-  "nui.nvim": { "branch": "main", "commit": "a0fd35fcbb4cb479366f1dc5f20145fd718a3733" },
   "nvim-FeMaco.lua": { "branch": "main", "commit": "96bbf843595dbe865838b3f2484b73557f34700c" },
   "nvim-cmp": { "branch": "main", "commit": "ae644feb7b67bf1ce4260c231d1d4300b19c6f30" },
   "nvim-colorizer.lua": { "branch": "master", "commit": "194ec600488f7c7229668d0e80bd197f3a2b84ff" },
@@ -62,6 +60,7 @@
   "nvim-nio": { "branch": "master", "commit": "a428f309119086dc78dd4b19306d2d67be884eee" },
   "nvim-surround": { "branch": "main", "commit": "ec2dc7671067e0086cdf29c2f5df2dd909d5f71f" },
   "nvim-toggleterm.lua": { "branch": "main", "commit": "48be57eaba817f038d61bbf64d2c597f578c0827" },
+  "nvim-tree.lua": { "branch": "master", "commit": "ad0b95dee55955817af635fa121f6e2486b10583" },
   "nvim-treesitter": { "branch": "master", "commit": "f197a15b0d1e8d555263af20add51450e5aaa1f0" },
   "nvim-treesitter-context": { "branch": "master", "commit": "0f3332788e0bd37716fbd25f39120dcfd557c90f" },
   "nvim-treesitter-endwise": { "branch": "master", "commit": "8b34305ffc28bd75a22f5a0a9928ee726a85c9a6" },
@@ -89,6 +88,7 @@
   "vifm.vim": { "branch": "master", "commit": "a8130c37d144b51d84bee19f0532abcd3583383f" },
   "vim-criticmarkup": { "branch": "master", "commit": "d15dc134eb177a170c79f6377f81eb02a9d20b02" },
   "vim-numbertoggle": { "branch": "main", "commit": "df9b1fe616507340718716204ba7f434125bdf7a" },
+  "vim-scimark": { "branch": "master", "commit": "9b66a88fa4bb87b8baab3c4aecc43b985b32e7fd" },
   "vim-spellsync": { "branch": "master", "commit": "3d6dd50de9c4d953cc16638112a6ae196df41463" },
   "wezterm.nvim": { "branch": "main", "commit": "f73bba23ab4becd146fa2d0a3a16a84b987eeaca" },
   "which-key.nvim": { "branch": "main", "commit": "6c1584eb76b55629702716995cca4ae2798a9cca" },

nvim/.config/nvim/lua/plugins/data_analysis.lua

@@ -1,4 +1,13 @@
 return {
+	-- md tables to scim
+	{
+		"mipmip/vim-scimark",
+		lazy = false,
+		config = function()
+			vim.g.scimCommand = "/usr/bin/sc-im"
+		end,
+		ft = { "quarto", "markdown", "vimwiki" },
+	},
 	{
 		"jmbuhr/otter.nvim",
 		config = function()

nvim/.config/nvim/lua/plugins/lsp.lua

@@ -35,7 +35,7 @@ local servers = {
 	taplo = {},
 	texlab = {},
 	tinymist = {},
-	ts_ls = {},
+	tsserver = {},
 	yamlls = {},
 }
 

nvim/.config/nvim/lua/plugins/pickers.lua

@@ -15,20 +15,13 @@ return {
 		event = { "BufEnter" },
 	}, -- integrate file manager
 	{
-		"nvim-neo-tree/neo-tree.nvim",
+		"nvim-tree/nvim-tree.lua", -- integrate file tree
-		dependencies = {
+		config = true,
-			"MunifTanjim/nui.nvim",
+		dependencies = { "nvim-tree/nvim-web-devicons", config = true },
-			"nvim-lua/plenary.nvim",
+		cmd = "NvimTreeToggle",
-			{ "nvim-tree/nvim-web-devicons", optional = true },
-		},
-		cmd = "Neotree",
-		opts = {
-			source_selector = { winbar = true },
-		},
 		keys = {
-			{ "<leader>se", "<cmd>Neotree toggle left<cr>", desc = "filetree", silent = true },
+			{ "<leader>se", "<cmd>NvimTreeToggle<cr>", desc = "filetree", silent = true },
 		},
-		lazy = false
 	},
 	{ "MagicDuck/grug-far.nvim", lazy = false, opts = {} },
 	-- fuzzy matching picker

nvim/.config/nvim/lua/plugins/prose.lua

@@ -69,24 +69,14 @@ local prose_plugs = {
 		main = "render-markdown",
 		opts = {
 			file_types = { unpack(md_like) },
-			render_modes = { "n", "c", "i" },
 			code = {
 				sign = false,
 				width = "block",
 				right_pad = 1,
 			},
-			checkbox = {
-				custom = {
-					todo = { raw = "[-]", rendered = "󰡖 ", highlight = "RenderMarkdownTodo" },
-					removed = { raw = "[_]", rendered = "󱋭 ", highlight = "RenderMarkdownTodo" },
-				},
-			},
 		},
 		name = "render-markdown", -- Only needed if you have another plugin named markdown.nvim
-		dependencies = {
+		dependencies = { "nvim-treesitter/nvim-treesitter", "nvim-tree/nvim-web-devicons" }, -- if you prefer nvim-web-devicons
-			"nvim-treesitter/nvim-treesitter",
-			"nvim-tree/nvim-web-devicons",
-		},
 		ft = md_like,
 		cmd = "RenderMarkdown",
 		keys = {

vcs/jj/config/jj/config.toml

@@ -1,12 +0,0 @@
-[user]
-email = "marty.oehme@gmail.com"
-name = "Marty Oehme"
-
-[signing]
-sign-all = false
-backend = "gpg"
-key = "73BA40D5AFAF49C9"
-
-[ui]
-default-command = "log"
-diff-editor = ["nvim", "-c", "DiffEditor $left $right $output"]

vcs/jj/config/sh/alias.d/jj.sh

@@ -1,30 +0,0 @@
-#!/usr/bin/env sh
-
-if ! exist jj; then
-    return 1
-fi
-
-alias j='jj' # necessary for a thing as easy to type?
-if exist lazyjj; then
-    alias lj="lazyjj"
-fi
-alias js="jj status"
-
-alias jd="jj describe"
-alias jn="jj new"
-alias jc="jj commit"
-
-alias jl='jj log'
-alias jlo='jj log --summary'
-alias jloo='jj log --patch'
-alias jo="jj op log"
-
-alias jss="jj squash"
-alias jsi="jj squash --interactive"
-
-alias je="jj edit"
-alias jee="jj next --edit"
-
-alias jun="jj undo"
-
-alias jp="jj git push"

writing/.config/pubs/pubsrc

@@ -0,0 +1,166 @@
+
+[main]
+
+# Where the pubs repository files (bibtex, metadata, notes) are located
+pubsdir = ~/documents/library
+
+# Where the documents files are located (default: $(pubsdir)/doc/)
+docsdir = ~/documents/library/doc
+
+# Specify if a document should be copied or moved in the docdir, or only
+# linked when adding a publication.
+doc_add = copy
+
+# the command to use when opening document files
+open_cmd = open
+
+# which editor to use when editing bibtex files.
+# if using a graphical editor, use the --wait or --block option, i.e.:
+# "atom --wait"
+# "kate --block"
+# If set to an empty string (default) pubs uses the value of the environment
+# variable $EDITOR.
+edit_cmd = ""
+
+# Which default extension to use when creating a note file.
+note_extension = md
+
+# How many authors to display when displaying a citation. If there are more
+# authors, only the first author is diplayed followed by 'et al.'.
+max_authors = 3
+
+# If true debug mode is on which means exceptions are not catched and
+# the full python stack is printed.
+debug = False
+
+# If true the citekey is normalized using the 'citekey_format' on adding new publications.
+normalize_citekey = False
+
+# String specifying how to format the citekey. All strings of
+# the form '{substitution:modifier}' and '{substitution}' will
+# be substituted with their appropriate values. The following
+# substitutions are used:
+#    author_last_name: last name of the first author
+#    year: year of publication
+#    short_title: first word of the title (excluding words such as "the", "an", ...)
+# modifiers:
+#    l: converts the text to lowercase
+#    u: converts the text to uppercase
+# examples:
+#   {author_last_name:l}{year} generates 'yang2020'
+#   {author_last_name}{year}{short_title} generates 'Yang2020Towards'
+#   {author_last_name:l}{year}{short_title:l} generates 'yang2020towards'
+#   {author_last_name:u}{year} generates 'YANG2020'
+#
+citekey_format = {author_last_name}{year}
+
+# which bibliographic fields to exclude from bibtex files. By default, none.
+# Please note that excluding critical fields such as `title` or `author`
+# will break many commands of pubs.
+exclude_bibtex_fields = ,
+
+[formating]
+
+# Enable bold formatting, if the terminal supports it.
+bold = True
+
+# Enable italics, if the terminal supports it.
+italics = True
+
+# Enable colors, if the terminal supports it.
+color = True
+
+
+[theme]
+
+# Here you can define the color theme used by pubs, if enabled in the
+# 'formating' section. Predefined theme are available at:
+# https://github.com/pubs/pubs/blob/master/extra/themes.md
+
+# Available colors are: 'black', 'red', 'green', 'yellow', 'blue', 'purple',
+# 'cyan', and 'grey'. Bold colors are available by prefixing 'b' in front of
+# the color name ('bblack', 'bred', etc.), italic colors by prefixing 'i',
+# and bold italic by prefixing 'bi'. Finally, 'bold', 'italic' and
+# 'bolditalic' can be used to apply formatting without changing the color.
+# For no color, use an empty string ''
+
+# messages
+ok = green
+warning = yellow
+error = red
+
+# ui elements
+filepath = bold
+citekey = purple
+tag = cyan
+
+# bibliographic fields
+author = bold
+title = ""
+publisher = ""
+year = bold
+volume = bold
+pages = ""
+
+
+[plugins]
+# Comma-separated list of the plugins to load.
+# Currently pubs comes with built-in plugins alias and git.
+active = alias,git
+
+[[alias]]
+# new subcommands can be defined, e.g.:
+# print = open --with lp
+# evince = open --with evince
+
+# shell commands can also be defined, by prefixing them with a bang `!`, e.g:
+# count = !pubs list -k | wc -l
+
+# aliases can also be defined with descriptions using the following configobj
+# subsectioning.  NOTE: any aliases defined this way should come after all other
+# aliases, otherwise simple aliases will be ignored.
+# [[[count]]]
+# command = !pubs list -k | wc -l
+# description = lists number of pubs in repo
+# new subcommands can be defined, e.g.:
+# print = open --with lp
+# evince = open --with evince
+
+# shell commands can also be defined, by prefixing them with a bang `!`, e.g:
+# count = !pubs list -k | wc -l
+
+# aliases can also be defined with descriptions using the following configobj
+# subsectioning.  NOTE: any aliases defined this way should come after all other
+# aliases, otherwise simple aliases will be ignored.
+# [[[count]]]
+# command = !pubs list -k | wc -l
+# description = lists number of pubs in repo
+
+# To use commas in the description, wrap them in a "" string. For example:
+# description = "lists number of pubs in repo, greets the user afterward"
+
+[[git]]
+# The git plugin will commit changes to the repository in a git repository
+# created at the root of the pubs directory. All detected changes will be
+# commited every time a change is made by a pubs command.
+# The plugin also propose the `pubs git` subcommand, to directly send git
+# commands to the pubs repository. Therefore, `pubs git status` is equivalent
+# to `git -C <pubsdir> status`, with the `-C` flag instructing
+# to invoke git as if the current directory was <pubsdir>. Note that a
+# limitation of the subcommand is that you cannot use git commands with the
+# `-c` option (pubs will interpret it first.)
+
+# if False, will display git output when automatic commit are made.
+# Invocation of `pubs git` will always have output displayed.
+quiet = True
+# if True, git will not automatically commit changes
+manual = False
+# if True, color will be conserved from git output (this add `-c color:always`
+# to the git invocation).
+force_color = True
+
+
+[internal]
+# The version of this configuration file. Do not edit.
+version = 0.9.0
+

writing/.config/sh/alias.d/pubs.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+pubs() {
+    command pubs --config "$XDG_CONFIG_HOME/pubs/pubsrc" "${@}"
+    if [ -f "$BIBFILE" ]; then
+        command pubs export > "$BIBFILE"
+    fi
+}

writing/.local/bin/bib-due

@@ -0,0 +1,147 @@
+#!/usr/bin/env sh
+# shows due entries of bibtex file passed in
+# HACK: brittle! will break on various bibfile abnormities (even just on due date w/o priority)
+# FIXME: reimplementation with real library needed
+#
+
+OPTIND=1 # Reset in case getopts has been used previously in the shell.
+fields="due|priority|\bauthor\b|\btitle\b"
+filterby="due"
+file="${BIBFILE}"
+until=""
+
+show_help() {
+  printf "%s\n" \
+    "" \
+    " bib-due       Show due readings from bibtex file." \
+    "" \
+    " Usage: bib-due [-hv] -i input.bib -r 'due|priority|\bauthor|\btitle' -l 'due' -u '2020-05-12'" \
+    "" \
+    " Options:" \
+    "" \
+    "     -i [bibtex-file]                    Input bibtex file to scrape and get items from." \
+    "" \
+    "     -r [fields]                         Field values to read in file." \
+    "" \
+    "     -l [filter]                         Field to use as filter entity." \
+    "                                         This field is required for the scraper to pick entries up." \
+    "" \
+    "     help    | -h | --help               Print out this help." \
+    "" \
+    " Invoked without arguments, bib-due will scrape the file defined in BIBFILE environment variable, " \
+    " filtering entries with the 'due' field, and getting the values for 'due', 'priority', 'author', " \
+    " and 'title' fields. It will then print the entries to stdout." \
+    "" \
+    " Example output line:" \
+    "" \
+    ' 2020-06-25 (1): Sergei Gerasymchuk -- “Ze” time in Ukraine (Gerasymchuk2019) ' \
+    ""
+}
+
+filter_until() {
+  # filter for dates, with line numbers
+  filtered=$(echo "$entries" | grep -noE '[[:digit:]]{4}-[[:digit:]]{2}-[[:digit:]]{2}')
+
+  # redirect entries to fifo pipe
+  mkfifo filteredentries
+  finish() {
+    rm filteredentries
+  }
+  trap finish EXIT
+  echo "$filtered" >filteredentries &
+
+  # find first date past until filter
+  lastline=""
+  while IFS= read -r line; do
+    cond=$(printf '%s' "$line" | cut -d: -f2)
+    cond=$(date -d "$cond" +%s)
+    if [ "$cond" -gt "$until" ]; then
+      lastline=$(printf '%s' "$line" | cut -d: -f1)
+      break
+    fi
+  done <filteredentries
+
+  # special cases all in filter, or none in filter
+  if [ -z "$lastline" ]; then
+    return
+  elif [ "$lastline" -eq 1 ]; then
+    entries=""
+  # filter
+  else
+    # remove lines below found
+    lastprinted="$((lastline - 1))"
+    entries=$(echo "$entries" | sed -n "1,${lastprinted}p;${lastline}q")
+  fi
+}
+
+filter_priority() {
+  priority="$1"
+  # filter for dates, with line numbers
+  # filtered=$(echo "$entries" | grep -noE '[[:digit:]]{4}-[[:digit:]]{2}-[[:digit:]]{2}')
+  filtered=""
+  while [ "$priority" -gt 0 ]; do
+    current=$(echo "$entries" | grep -E "\($priority\)")
+
+    # append found to filtered entries
+    filtered=$(printf "%s\n%s" "$filtered" "$current")
+
+    # go to next 'higher' priority
+    priority="$((priority - 1))"
+  done
+  # sort them chronologically again, remove empty lines
+  entries="$(echo "$filtered" | sed -e '/^$/d' | sort)"
+}
+
+main() {
+  if [ -z "$file" ]; then
+    echo "Requires a bibtex file as argument."
+    exit 1
+  fi
+
+  # filter all entries for those containing filterby field (default: due)
+  # retain values of all fields mentioned in fields variable
+  entries=$(grep -E "^@|$fields" "$file" | awk 1 ORS=' ' | sed -E 's/@\w+\{/\n/g' | grep "$filterby" | tail -n +2 | sed -E 's/(,\s+(\w+)\s+=\s+|,\s*$)/\t/g' | awk -F'\t' '{ print $4 "\t" $5 "\t" $2 "\t" $3 "\t" $1 }')
+
+  # prettify and sort the entries for display (remove {}, order by date,prio,author,title)
+  entries=$(echo "$entries" | awk -F'\t' '{ gsub(/{/,""); gsub(/}/,""); gsub(/prio/,"",$2) } { print $1 " (" $2 "): " $3 " -- " $4 " (" $5 ")"}' | sort)
+
+  if [ -n "$until" ]; then
+    filter_until
+  fi
+  if [ -n "$priority" ]; then
+    filter_priority "$priority"
+  fi
+
+  echo "$entries"
+}
+
+while getopts "h?i:u:r:l:p:" opt; do
+  case "$opt" in
+  h | \?)
+    show_help
+    exit 0
+    ;;
+    # v)  verbose=1
+    # ;;
+  r)
+    fields="$OPTARG"
+    ;;
+  l)
+    filterby="$OPTARG"
+    ;;
+  i)
+    file="$OPTARG"
+    ;;
+  u)
+    until="$(date -d "$OPTARG" +%s)"
+    ;;
+  p)
+    priority="$OPTARG"
+    ;;
+  esac
+done
+shift $((OPTIND - 1))
+
+[ "${1:-}" = "--" ] && shift
+
+main "$@"

writing/.local/bin/rofi-bib-due

@@ -0,0 +1,29 @@
+#!/usr/bin/env sh
+
+exist rofi normal
+
+_rofi() {
+  rofi -dmenu -no-auto-select -i -theme themes/dropdown -p "papers" -l 25 -yoffset 20 -columns 1 -u "$urgent"
+}
+
+# call for whatever file is passed in
+results="$(bib-due "$@")"
+
+# mark priority 1 items as urgent in rofi
+urgent="$(
+  # find all lines with priority 1, (marked as `(1):` );
+  # print them on 1 line, -1 since dmenu is 0 indexed
+  echo "$results" | grep -n '(1):' | cut -d: -f1 | awk '{ $0=$0-1; print $0 }' ORS=','
+)"
+
+# get user choice, exit if nothing selected
+choice=$(echo "$results" | _rofi)
+[ -z "$choice" ] && exit 0
+
+key=$(echo "$choice" | sed -E 's/.*\((\w+)\)$/\1/')
+
+# get library pdf folder (only searches for default ./pdf path)
+library="$(dirname "$(realpath "$BIBFILE")")/pdf"
+
+# find and open the key-associated pdf file
+${FILEREADER:-open} "$(find "$library" -type f -name "$key *.pdf")"

writing/README.md

@@ -1,15 +1,65 @@
 # Writing module
 
-This module contains everything that is specific for me writing prose, journaling and pursuing academic work.
+[bibtex](https://en.wikipedia.org/wiki/BibTeX) - plain-text reference management
-
-That means there are configurations for reference management (`papis`),
-for daily journaling (`jrnl`),
-for reading PDFs (`sioyek`, `zathura`)
-and for general notetaking (`zk`).
-
-[bibtex](https://en.wikipedia.org/wiki/BibTeX) - plain-text references
-[papis](https://github.com/papis/papis) - yaml-driven and bibtex-compatible reference management
-[jrnl](https://github.com/jrnl-org/jrnl) - journaling on the command line
-[zk](https://github.com/zk-org/zk) - notetaking with a 'zettelkasten' principle
 [zathura](git.pwmt.org) - keyboard-driven PDF reading
 [sioyek](http://sioyek.info/) - keyboard-driven PDF reading *and annotating*
+
+This readme is a little out of date, as are the scripts below.
+They are old, I used them during my time as a student and they are probably written terribly.
+But I still think there is value in them, hence not removing them from the repo just yet.
+
+## bib-due
+
+The `bib-due` script depends on (gnu) grep, awk, and sed, date if using date filtering capabilities. It is currently written in a rather haphazard way, and prone to breakage.
+On the other hand, it does what it's supposed to do: list bibtex entries which have their due-date coming up.
+
+The script needs bibtex entries to be marked with two fields: `due`, containing a due date (ideally in YYYY-MM-DD format, for easy sorting), and `priority` containing a read priority. It will also, by default attempt to grab the values of the fields `author` and `title`, as well as the name of the bibtex key of the entry.
+
+It can be invoked with the path to a bibtex file `bib-due path/to/library.bib`, and will gather the entries from the respective file. It can be invoked without an argument if the environment variable `$BIBFILE` is declared (pointing to a bibtex file).
+
+Example output looks as follows:
+
+![bib-due example output](.assets/bibtex/list.png)
+
+The output can then be filtered further through other programs.
+
+Bib-due itself allows 2 filtering options: *until* a certain date (`-u`), and *at least* a certain priority (`-p`).
+
+Using priority is relatively self-explanatory: 1 is the highest priority, 3 the lowest (technically, no priority is the lowest). Choosing `-p3` means priority 1, 2, and 3 will be displayed. Choosing `-p1` will only display the highest priority items.
+
+Using the date works as a cut-off for the future, and it uses gnu `date` to calculate the correct date. That makes things like `-u 'fri this week'` possible, showing only upcoming items until the end of the week. Read the `date` manual for more information.
+There will likely not be a new option for filtering dates *from* a certain point forward since I don't need it and before implementing more stuff what's there should be more solid. (and read your damn overdue texts!)
+
+Again, this script will (for now[^time]) break when bibtex files are formatted in any way other than what it expects.
+An example of a working entry:
+
+[^time]: And probably for some time since I don't see myself sinking too much more time into this in the near future. I actually need to get some of the upcoming readings done that I can now list! 🙂
+
+```
+@InBook{Borhi2016,
+  author    = {László Borhi},
+  chapter   = {1956: Self-Liberation},
+  pages     = {117--137},
+  publisher = {Indiana University Press},
+  title     = {Dealing with dictators: the {United States}, {Hungary}, and {East Central Europe}, 1942-1989},
+  year      = {2016},
+  due       = {2020-05-07},
+  file      = {:Borhi2016 - Dealing with Dictators_ the United States, Hungary, and East Central Europe, 1942 1989.pdf:PDF},
+  pagetotal = {564},
+  priority  = {prio1},
+  timestamp = {2020-05-08},
+}
+```
+
+Important fields are author, title, due, priority. These need to exist, and need to be ordered alphabetically. Otherwise there will probably be some breakage.
+
+## rofi-bib-due
+
+The `rofi-bib-due` script utilizes the `bib-due` script and depends on an existing installed `rofi` module (see [here](rofi/)).
+On invocation, it creates a list of upcoming readings, and allows selecting one of the readings. The selected reading will be passed along to `$FILEREADER` if it is declared, falling back to `xdg-open` if not.
+
+Currently, the path to the reading pdf is hard-coded to be `path/to/bibtex.bib/pdf`, and the name has to begin with the exact bibtex key; otherwise the script will not be able to find the pdf.
+
+An example of the script in action: (window size has been reduced for the recording, cutting off most entry names)
+
+![rofi-bib-due demonstration](.assets/bibtex/rofi.gif)