You are not logged in.

#1 2021-02-13 22:47:57

From: Germany
Registered: 2012-11-17
Posts: 15

DocMa - A command-line document manager

Hi all,
I'm a researcher in integrated circuit design and therefore read a lot of scientific papers. To deal with the ever-increasing numbers of documents, I wrote a tool which lets me search for saved documents based on authors, title and keywords. If a match is found, it is opened in a pdf viewer, if several are found the user is queried which one should be opened. The tool supports bibtex output, keeps a search history, remembers the last opened document and more. You can check out the project at, here is a simple PKGBUILD:

# Maintainer: Patrick Kurth <>

pkgdesc="A command-line document manager with keyword search"
depends=('lua-penlight' 'lua')

pkgver() {
  cd "${pkgname}"
  printf "r%s.%s" "$(git rev-list --count HEAD)" "$(git rev-parse --short HEAD)"

package() {
    cd "${srcdir}/${pkgname}"
    mkdir -p "${pkgdir}/usr/share/lua/5.4"
    cp --recursive docmalib "${pkgdir}/usr/share/lua/5.4"
    mkdir -p "${pkgdir}/usr/bin"
    cp docma "${pkgdir}/usr/bin"
How to use

In order to open documents you have to have at least one. In its default configuration, docma looks for documents in ~/.docma/data. You can use folders to organize your documents for other uses, but that is not required. DocMa looks recursively for all 'data.lua' files in ~/.docma/data and loads them. These files contain the description of the documents. A simple entry looks like this (data.lua is a regular lua file):

        title = "A Tutorial on Geometric Programming",
        authors = {"Stephen P. Boyd", "Seung Jean Kim", "Lieven Vandenberghe", "Arash Hassibi"},
        keywords = {"oscillator", "optimization"},
        path = "gp_tutorial.pdf",    

The four entries 'title', 'authors', 'keywords' and 'path' have to be present (keywords can be an empty table ({})). The path can be absolute or relative to the data.lua file. Currently, these entries have to be mostly written by hand, there are two generators to help with this task: docma -G and docma -B, where the first is an interactive session and the second takes a bibtex file.

With the above entry you would search for the document like this, where incomplete matches are allowed:

$ docma tut

and as only one document matches this search it will be opened right away. The fallback solution for the viewer is zathura as I am using it, but this can be changed in ~/.docma/.config.lua.

Current State

There is still a lot missing (some command-line options are there, but not implemented), there are still some non-minor bugs etc., but I'm using the tool on a daily basis and adding features here and there when I need a new one. I would be happy to get some feedback and provide a useful tool for others, too. It is definitely not limited to academic papers and can manage any collection of documents.


Board footer

Powered by FluxBB