Outlining academical notes in plain-text

When writing a term paper or like now my final thesis, I need for myself to do an outline of all the notes from articles and books I am reading. In the past I used
OmniOutliner for that job but I want to convert to plain text more again. Plain text just has the advantage of portability. Also I can use one editor for writing my notes and my thesis1.

Thus I have my editor open in full screen and just have a split view, left with my notes, on the right with my thesis2. Because I am using a Bib-File for compiling my bibliography, each text has a cite-key which is kind of a unique date to identify the text. My cite-keys have the following format: firstauthorxyearyz, for example cukiermanx1992hc. So first the first author, then an x to divide author and publication year, then the publication year and then to random letters. The advantage of an x in contrast to a special character is well, it is not a special character and won’t make any trouble when using my files on other computers. For administering my bib-file I am using BibDesk which is an awesome piece of software for that and hands-down beats any other bib-application in my opinion. I have unfortunately no suggestions for good software in that regard on *BSD, Linux or Windows.

Usually I start with compiling notes by creating a file per article. Those files are just called citekey.md. And when I see the bigger picture I move to files that have a topic name and move my notes over from the specific article-files to the topic-files. I use md as an ending, even so the files are not really Markdown. But then vim will recognize it as markdown and with it, it does folding accordingly and when I want to format anything, I can do it with the very very easy to learn markdown-syntax3

The note-format is what I had to fight the longest with but I have now an easy solution that is quite satisfying. One line just looks like this:

- [citekey][pagenumber] Text

And I use tab-stops for the indentations. Essential is that each line has the citekey and the page-information. Only with that information you can move stuff around without loosing this information for being able to cite later correctly.

Bonus Content

For reading PDFs I am using now PDF Expert on an iPad. I highlight everything interesting in a PDF, then I “share” it as an e-mail with the notes in the mail-text. On my computer I copy the text in a file4 called citekey.md. After that I run a bash-script which was written by @kopischke after he saw my bad tries doing it.


#!/usr/bin/env bash
declare -i pnum=${2:-1}
file_name="${1##*/}" # remove path
file_name="${file_name%%.*}" # remove extension
page_num_re='^PAGE ([[:digit:]]+):' # match “PAGE XXX”

while read -r line || [[ -n "$line" ]]; do
if [[ $line =~ $page_num_re ]]; then
number=${BASH_REMATCH[1]}
elif [[ $line =~ ^Highlight ]]; then
printf '%s - [%s][%i] ' "$line" "$file_name" $(($pnum - 1 + $number))
elif [[ $line == 'and Note' ]]; then
printf '%s: ' 'Note'
is_note=true
else
$is_note && { line="${line#\"}"; line="${line%\"}"; is_note=false; }
echo "$line"
fi
done < "$1"

The bash-script is run like this:

reformat.sh basepage filename

The basepage is the page number on the first page of the PDF. PDF Expert will give you notes stating "Page 1", "Page 2" etc, even so the article started at page 362. The result is a file that looks exactly like what I have written about above (- [citekey][pagenumber]) when the file-name is in the format citekey.md of course. In addition anytime the word and Note is found at the end of a line, it will remove the and put the word Note in the next line.

Since PDFs usually have some ugly hyphenation, I have to clean that up as well. How to do that depends on your text-editor. In vim I use the following command

:%s/.\zs- //g

This removes all "- " that are not in the beginning of a line. And then you have rather fast a file you can work with.


  1. In my case it is vim and when I understood how awesome the combination of vim+tmux is, I even converted from MacVim/gvim to vim on the cli. If you want learn vim, I can really recommend the Vimcasts and Practical Vim, both by Drew Neil.

  2. which I write in LaTeX, to be correct I write it with XeTeX

  3. lists are prefixed with -, italic is *word*, bold is **word**, heading is 1 # per heading-level like ### Heading 3. That’s all you need to know for the beginning.

  4. Well, I am using mutt nowadays, thus I just save the mail-body as a text-file.

[Resolved] vim-latex: \cite-completion does not work correctly

I am using vim with the LaTeX-suite for writing longer texts. But I had one problem when using the \cite-completion with F9. Instead of getting one split-view with nicely formatted entries of my bib-file, I got two split-views: one with cite-keys, one with my unformatted bib-file. I could go through the cite-keys and the bib-file would jump to the right entry but that’s it. Nothing to see of functions like filtering etc.

The solution was to install vim-latex manually. I am using normally NeoBundle and used previously vundle for managing my plug-ins. But those seem to interfer with the functionality of vim-latex. So, if you run into the same problem, just de-install it with your package-manager and install it manually from Sourceforge. It is cumbersome but it works and the plug-in got updated the last time over a year ago, so missing out on updates do not seem to be that much of an issue.

P.s.: Another problem I found when googling many people seem to have is, that the cite-autocompletion won’t work when there is a space in the path to the bib-file or when there is for example a leading space in bib-entries like “@article{kobschaetzkix2014gh, …”