bog
bog copied to clipboard
kyleam
Extensions for research notes in Org mode
#+title: Bog #+options: toc:nil #+startup: showall
[[https://travis-ci.org/kyleam/bog][https://travis-ci.org/kyleam/bog.svg]] [[https://melpa.org/#/bog][https://melpa.org/packages/bog-badge.svg]]
Bog is a system for taking research notes in [[https://orgmode.org/][Org mode]]. It adds a few research-specific features, nearly all of which are focused on managing and taking notes with Org, not on writing research articles with Org.
- Installation
Bog is available on [[https://melpa.org/][MELPA]].
To enable Bog in all Org buffers, add it to =org-mode-hook=.
#+begin_src emacs-lisp (add-hook 'org-mode-hook #'bog-mode) #+end_src
- Workflow
The Bog workflow is focused around the citekey, which is the only study information that must be included in the notes. This unique identifier is used as a link to the BibTeX file and other associated files.
In the example below, the citekey "name2000word" is a study heading. A study heading is defined as a heading that has a citekey as a title or as the value of =bog-citekey-property=. When a citekey occurs anywhere else (like "another1999study" below), it is taken as a reference to another study (which may or may not have a subtree in this or another Org file).
#+begin_example
,* Topic heading
,** TODO name2000word :atag:
Article notes ... a reference to another1999study ... #+end_example
The default format for the citekey is the first author's last name, the year, and then the first non-trivial word. To have BibTeX mode automatically generate a key of this format, the =bibtex-autokey-*= settings can be modified.
#+begin_src emacs-lisp (setq bibtex-autokey-year-length 4 bibtex-autokey-titleword-length 'infty bibtex-autokey-titlewords-stretch 0 bibtex-autokey-titlewords 1 bibtex-autokey-year-title-separator "") #+end_src
- Main features
Many Bog functions take the citekey from the notes. If the point is on a citekey (like "another1999study" above), then that citekey will be used. If this fails, many functions will try to take the citekey from the first parent heading that is a study heading.
-
=bog-find-citekey-file=
Open an associated file (usually a PDF) for a citekey.
-
=bog-find-citekey-bib=
Open a BibTeX file for a citekey.
BibTeX entries can be stored in one of two ways:
- As a single file with many entries
- As single-entry files named citekey.bib within a common directory
-
=bog-search-citekey-on-web=
Search Google Scholar for a citekey. The default citekey format (first author's last name, year, and first non-trivial word) usually contains enough information to make this search successful.
-
=bog-rename-staged-file-to-citekey=
Rename a new file (usually a PDF) to be associated with a citekey.
-
=bog-clean-and-rename-staged-bibs=
Rename new BibTeX files. If a separate BibTeX file is used for each citekey, this function can be used to rename all new BibTeX files. =bibtex-clean-entry= is used to clean the entry and autogenerate the key.
-
=bog-create-combined-bib=
Generate a combined BibTeX file for all citekeys in buffer. This is useful if single-entry BibTeX files are used.
Other useful functions include
- =bog-citekey-tree-to-indirect-buffer=
- =bog-goto-citekey-heading-in-notes=
- =bog-insert-heading-citekey=
- =bog-jump-to-topic-heading=
- =bog-list-duplicate-heading-citekeys=
- =bog-list-orphan-citekeys=
- =bog-open-citekey-link=
- =bog-open-first-citekey-link=
- =bog-refile=
- =bog-search-notes=
- =bog-search-notes-for-citekey=
- =bog-sort-topic-headings-in-buffer=
- =bog-sort-topic-headings-in-notes=
You can try out many of the commands in [[file:example/notes/org-mode-pubs.org][example/notes/org-mode-pubs.org]].
- Variables
Several variables determine where Bog looks for things.
- =bog-bib-directory= or =bog-bib-file=
- =bog-file-directory=
- =bog-note-directory=
- =bog-stage-directory=
The variables below are important for specifying how Bog behaves.
-
=bog-citekey-format=
A regular expression that defines the format used for citekeys.
-
=bog-find-citekey-bib-func=
A function to find a citekey in a BibTeX file. This determines whether a directory of single-entry BibTeX files or a single BibTeX file is used.
- Keybindings
A keymap is defined for Bog under the prefix =C-c "=. If you prefer something else (like =C-c b=), set =bog-keymap-prefix=.
Many of the Bog functions are useful outside of an Org buffer. You can turn Bog minor mode on (=bog-mode=) in non-Org buffers to get access to the keymap and citekey highlighting. To make Bog commands available from any buffer, bind =bog-command-map= to a global key.
- Other approaches
If Bog doesn't fit your workflow, there are a good number of other approaches to explore. On the Org mode mailing list, there are some [[https://yhetil.org/orgmode/[email protected]/][nice]] [[https://yhetil.org/orgmode/[email protected]/][descriptions]] of systems people have come up with for taking research notes in Org. For a package that focuses on both taking research notes and writing research articles, look into [[https://github.com/jkitchin/org-ref][Org-ref]].
kyleam