Sunday, January 22

org mode

I finally tried Org mode for Emacs, by way of a spacemacs install. I wanted to find something more structured for notes and TODOs than the directory full of text files I’ve been using, and Org nearly always comes up in these discussions.

It turns out to be nearly as all-singing-all-dancing as it’s made out to be: Crazy huge featureset, and situated in a very capable environment. (Emacs really is something very like an operating system, and has many of the qualities of being an environment of tool usage that I look for in software.)

The basic idea is that it’s an outliner, with collapsible nested sections that can be cycled open and closed by hitting Tab. There are checklist items that can be cycled through various states, date metadata, and ways to execute inlined code. There’s also tooling for viewing uncompleted tasks, a calendar interface, and an agenda based on upcoming events and task start dates / deadlines.

The syntax is moderately ugly and not as regular as I would have expected from its Lisp-adjacency, but it’s handled fluidly, with fewer glitches and more polish than I tend to expect from complex editor plugins.

It’s magical, but I didn’t actually wind up sticking with it.


I got a few days into the Org mode thing, and then Ben pointed me at Vimwiki. I had already by that point tried vim-orgmode, which wasn’t quite what I was looking for. Vimwiki turned out to be it, or at least something much closer.

Vim-instead-of-Emacs reasons:

  • Even with good Vim-style keybindings (and evil-mode, which is on by default in spacemacs, is very good), I always wind up in the part of Emacs that’s physically painful to use. (Lots of key chording really seems to bring on my always-latent RSI.)

  • I lean a lot on Vim behavior that’s different or missing in evil-mode. I’m not sure I could even tell you what behavior, just that it differs enough to break my brain. Stuff around visual selections and line endings is a lot of it, I think.

  • I cannot afford to mess around customizing Emacs for a month right now.

Vimwiki-is-legit-good reasons:

  • This is a simple, old-school wiki. Storage is plaintext with very basic syntax, links and new pages are cheap to create.

  • You can be up and running with no config and 4 or 5 key sequences with pretty simple mnemonics. I didn’t have to memorize much of anything I don’t already know.

  • There’s a checklist syntax, headers are easy, and you can inline code (with syntax highlighting). This is pretty much all I need.

Lastly, there’s the diary. This turns out to be the thing I use more than any other feature. It works like this: You press ,w,w (where , is your leader key) and you get a page for the current date.

Here are the Vimwiki-relevant parts of my current .vimrc (I’m using Vundle to manage plugins - you may prefer other options):

" a calendar - used in conjunction with vimwiki diaries
let g:calendar_keys = { 'goto_next_month': '<C-Right>', 'goto_prev_month': '<C-Left>'}
Plugin 'mattn/calendar-vim'

" CUSTOMIZE: vimwikis - for notes, daily logs, etc. {{{

  let wiki = {}
  let wiki.path = '~/notes/vimwiki/'
  let wiki.path_html = '~/notes/html/'
  let wiki.auto_tags = 1

  " do syntax highlight in preformatted blocks:
  let wiki.nested_syntaxes = {
    \ 'python': 'python',
    \ 'ruby': 'ruby',
    \ 'perl': 'perl',
    \ 'sh': 'sh'
  \ }

  " there can be many of these:
  let g:vimwiki_list = [wiki]

  let g:vimwiki_folding = 'expr'

  Plugin 'vimwiki/vimwiki'

" }}}

Nothing is perfect, but if you’re already a user of Vim and looking for a semi-formal note-taking paradigm, I endorse Vimwiki as a starting point.

For future work, I’d like to think about:

  • Executing inlined code (I already have this for Markdown documents; it should be simple enough).

  • Inlining structured data (like timestamps for invoicing).

  • Some kind of glue script to correlate diary entries with VCS commit logs, Atom/RSS feeds, and command-line history.

  • Using Vimwiki to manage the wiki entries on this site that used to be handled by WalaWiki (I’d intended to turn WalaWiki back on, but the modern web is such a hostile environment that I think it’d require a from-scratch rewrite or use of some other wiki platform to feel safe exposing it. It’s easier to just generate static HTML pages and accept changes by way of git).

addenda, early 2019

For a first pass at correlating diary entries with other dated info, see timeslice.

For invoice timestamps, I wound up using the timelog script originally described in this entry, along with a Makefile like this:

all: *.pdf

# See *.md for vim exec filters that generate the actual markdown.
# Oh my god this is baling wire bullshit.
%.pdf : ~/.timelogrc
        pandoc -o $@ $<

And invoice templates in Markdown like this

Invoiced 2019-02-03

**Billed to:**  
Foo, Inc.
New York, NY

**Pay to:**  
Brennen Bearnes  
Somewhere, CO

<!-- exec-raw zsh -c 'timelog ~/notes/vimwiki/diary/2019-01-*.wiki' -->
*   2019-01-02 10:00 - 17:30    7.500 hours
*   2019-01-03 10:05 - 17:00    6.917 hours
*   2019-01-04 09:40 - 18:35    8.917 hours
*   2019-01-07 09:50 - 18:30    8.667 hours
*   2019-01-08 09:15 - 17:00    7.750 hours
*   2019-01-09 09:50 - 17:45    7.917 hours
*   2019-01-10 10:15 - 17:00    6.750 hours
*   2019-01-11 09:00 - 17:00    8.000 hours
*   2019-01-14 10:00 - 15:35    5.583 hours
*   2019-01-15 10:00 - 16:45    6.750 hours
*   2019-01-16 10:00 - 12:00    2.000 hours
*   2019-01-16 15:00 - 17:30    2.500 hours
*   2019-01-16 21:00 - 21:40    0.667 hours
*   2019-01-20 14:00 - 17:00    3.000 hours
*   2019-01-22 09:30 - 17:00    7.500 hours
*   2019-01-23 09:52 - 12:00    2.133 hours
*   2019-01-25 11:00 - 17:00    6.000 hours

98.550 total hours at $4.20/hr = $413.91  
$0.00 in expenses

**Total due = $413.91**
<!-- end -->

Then I can generate a PDF with:

$ make foo-2019-02-03-hours.pdf

The bit inside the exec-raw comments is refreshed by pressing ,r, which runs the current buffer through some filters including filter-exec-raw. I still haven’t adapted filter-exec-raw or its siblings to be aware of Vimwiki markup, but sometimes I just put the HTML-style comments inside of a {{{ }}} block.

There are several levels on which this is probably not how you should do your invoicing.

tags: topics/emacs, topics/notes, topics/technical, topics/vim, topics/vimwiki

p1k3 / 2017 / 1 / 22