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.

Kommentar verfassen