1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
#+title: Bog
#+options: toc:nil
#+startup: showall
[[https://github.com/kyleam/bog/actions/workflows/test.yml][https://github.com/kyleam/bog/actions/workflows/test.yml/badge.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:
<URL for study>
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/528AC19F.3000803@binghamton.edu/][nice]] [[https://yhetil.org/orgmode/2c75873c0906230106h3daf3d34y230845e15dad278e@mail.gmail.com/][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]].
|