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
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
|
_____
BOG
_____
Table of Contents
_________________
1 Workflow
2 Main features
.. 2.1 Opening a PDF file for a citekey
.. 2.2 Opening a BibTeX file for a citekey
.. 2.3 Searching online for a citekey
.. 2.4 Renaming new PDFs
.. 2.5 Renaming new BibTeX files
.. 2.6 Generating a combined BibTeX file
3 Variables
4 Recommended keybindings
Bog is a system for taking research notes in [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.
[Org mode] http://orgmode.org/
1 Workflow
==========
Many people use Org for taking research notes, and there are some
really nice descriptions of systems people have come up with (for a
few examples, see [these] [threads] on the Org mode mailing list).
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 and PDF files.
In the example below, the citekey "name2000word" is a study
heading. Bog expects the citekey to be the title or property of a
heading. The citekey "another1999study" is a reference to another
study (which may or may not have a subtree in this or another Org
file).
,----
| * Topic heading
|
| ** TODO name2000word :atag:
|
| <URL for study>
|
| Article notes ... a reference to another1999study ...
`----
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.
,----
| (setq bibtex-autokey-year-length 4
| bibtex-autokey-titleword-length nil
| bibtex-autokey-titlewords-stretch 0
| bibtex-autokey-titlewords 1
| bibtex-autokey-year-title-separator "")
`----
[these] http://thread.gmane.org/gmane.emacs.orgmode/78983
[threads] http://thread.gmane.org/gmane.emacs.orgmode/14756
2 Main features
===============
Many Bog functions take the citekey from the notes context. If the
point is on a citekey (like "another1999study" above), then that
citekey will be used. Otherwise, the citekey will be taken from the
first parent heading that is a study. If one isn't found, the user
will be prompted for the citekey.
2.1 Opening a PDF file for a citekey
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The function `bog-find-citekey-pdf' will open a PDF associated with a
citekey.
2.2 Opening a BibTeX file for a citekey
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The function `bog-find-citekey-bib' will open the BibTeX entry
associated with a citekey.
BibTeX entries can be stored in one of two ways:
1. As a single file with many entries
2. As single-entry files named <citekey>.bib within a common directory
2.3 Searching online for a citekey
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The function `bog-search-citekey-on-web' will perform a Google Scholar
search with the citekey information. The default citekey format (first
author's last name, year, and first non-trivial word) usually contains
enough information to make this search successful.
2.4 Renaming new PDFs
~~~~~~~~~~~~~~~~~~~~~
New PDF files can be put in a "stage" directory and then renamed to a
citekey.
2.5 Renaming new BibTeX files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If a separate BibTeX file is used for each citekey,
`bog-clean-and-rename-staged-bibs' can be used to rename all new
BibTeX files. `bibtex-clean-entry' is used to clean the entry and
autogenerate the key.
2.6 Generating a combined BibTeX file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If single-entry BibTeX files are used, there should be a way to
collect the references that are needed. `bog-create-combined-bib' can
be used to create a BibTeX file that has entries for all the citekeys
in the current buffer.
3 Variables
===========
Several variables determine where Bog looks for things.
- bog-notes-directory
- bog-pdf-directory
- bog-bib-directory or bog-bib-file
- 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-citekey-func: A function to extract a citekey from the current
subtree. Use this to indicate whether the citekey
should be taken from the heading or property.
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.
4 Recommended keybindings
=========================
Bog doesn't claim any keybindings, but using "C-c b" as a prefix while
in Org mode is a good option.
Key Command
---------------------------------------------
C-c b p bog-find-citekey-pdf
C-c b r bog-rename-staged-pdf-to-citekey
C-c b b bog-find-citekey-bib
C-c b h bog-goto-citekey-heading-in-buffer
C-c b H bog-goto-citekey-heading-in-notes
C-c b w bog-search-citekey-on-web
This can be achieved by placing the code below in your .emacs file.
,----
| (define-prefix-command 'bog-map)
| (define-key org-mode-map (kbd "C-c b") 'bog-map)
| (define-key bog-map "p" 'bog-find-citekey-pdf)
| (define-key bog-map "r" 'bog-rename-staged-pdf-to-citekey)
| (define-key bog-map "b" 'bog-find-citekey-bib)
| (define-key bog-map "h" 'bog-goto-citekey-heading-in-buffer)
| (define-key bog-map "H" 'bog-goto-citekey-heading-in-notes)
| (define-key bog-map "w" 'bog-search-citekey-on-web)
`----
|