Arch Linux

hyde

Member

From: Germany

Registered: 2012-11-17

Posts: 22

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 https://github.com/patrickschulz/docma, here is a simple PKGBUILD:

# Maintainer: Patrick Kurth <p.kurth@posteo.de>

pkgname=docma
pkgver=r12.4fcc3dd
pkgrel=1
pkgdesc="A command-line document manager with keyword search"
arch=('any')
url="https://github.com/patrickschulz/docma"
source=("git+https://github.com/patrickschulz/docma")
sha256sums=('SKIP')
depends=('lua-penlight' 'lua')
makedepends=('git')
license=('MIT')

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.

Stefan Husmann

Member

From: Germany

Registered: 2007-08-07

Posts: 1,391

Re: DocMa - A command-line document manager

Hello, thanks for providing this. I think the audiance for such a program is limited, therefore the calm responses up to now.

The PKGBUILD is a good starting point, but needs some improvements.

First, als long as there are no stable releases and you pull from git tip, the package name should have the -git suffix.

Second, MIT is not a common license in pacman's sense. We need a license file.

Third, the use of mkdir in package function is dicouraged in favour of the install command.

# Maintainer: Patrick Kurth <p.kurth@posteo.de>

pkgname=docma-git
pkgver=r19.b956694
pkgrel=1
pkgdesc="A command-line document manager with keyword search"
arch=('any')
url="https://github.com/patrickschulz/docma"
source=("git+https://github.com/patrickschulz/docma")
sha256sums=('SKIP')
depends=('lua-penlight' 'lua')
makedepends=('git')
conflicts=('docma')
provides=('docma')
license=('MIT')

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

package() {
  cd ${pkgname%-git}
  install -d "$pkgdir"/usr/share/lua/5.4
  cp --recursive docmalib "$pkgdir"/usr/share/lua/5.4
  install -Dm755 ${pkgname%-git} "$pkgdir"/usr/bin/${pkgname%-git}
  # license file?
  #install -Dm644 license "$pkgdir"/usr/share/licenses/$pkgname/license
}