summaryrefslogtreecommitdiff
path: root/README
blob: 79e09df739fccccd8a65b0a0e79c886242dd95e0 (plain)
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
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
				 _____

				  BOG
				 _____


Table of Contents
_________________

1 Bog workflow
2 Features
.. 2.1 Adding citekeys to notes
.. 2.2 Referencing studies within notes
.. 2.3 Opening a PDF file for a citekey
.. 2.4 Opening a BibTeX file for a citekey
.. 2.5 Searching online for a citekey
.. 2.6 Renaming a new PDF
.. 2.7 Renaming a new BibTeX file
.. 2.8 Generating a combined BibTeX file
3 Recommended keybindings


Bog is a system for taking research notes in [Org mode]. As any Org user
knows, Org handles notetaking beautifully. Bog just 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 Bog 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 workflow for Bog is based on these preferences:

  1. I don't want to store a lot of metadata with my notes.

     The citekey is the unique identifier that I use to link the notes
     with the BibTeX and PDF files. With just the citekey, I should be
     able to access this. If desired, more information can be added
     (such as bibliographic properties that can be generated with
     org-bibtex), but this is not required.

     One of the reasons for this is #2.

  2. I want to have low friction for adding articles to the notes, but
     not mindless.

     There is an endless stream of research articles, so it should be
     easy to add them, but it shouldn't be so easy that I file them away
     without giving them any thought. For me, this means glancing over
     it at least enough to place it under a general topic (or capturing
     the article and a link in my normal Org notes system until I take
     time to refile it to my research notes). I only retrieve the BibTeX
     file or PDF file when I need to use them.


  [these] http://thread.gmane.org/gmane.emacs.orgmode/78983

  [threads] http://thread.gmane.org/gmane.emacs.orgmode/14756


2 Features
==========

2.1 Adding citekeys to notes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  As mentioned above, when citekeys are added, they should be filed
  under the appropriate topic. I organize my research notes into a few
  files with broad topics then have one level of headers representing
  topics to file studies under.

  ,----
  | # In a very general topic file
  | 
  | * Topic heder
  | 
  | ** name2000word                                    :atag:
  | 
  | <URL for study>
  | 
  | Article notes
  `----

  "name2000word" is the study header. Bog expects the study citekey to
  be the title or property of a heading.

  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 "")
  `----

  If the study was added when checking journals online, I tend to add
  the URL right under the heading. However, I often add citekeys from
  the references of an article that I'm reading. In this case, I often
  store only the heading.


2.2 Referencing studies within notes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  You can reference other studies with their citekey.

  ,----
  | ** name2000word                                    :atag:
  | 
  | Another study (another1999word).
  `----

  "another1999word" will be highlighted within the text. When the point
  is within the citekey, many Bog functions can extract and use the
  citekey.


2.3 Opening a PDF file for a citekey
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  All PDF files are kept in a single directory and are named as
  <citekey>-*.pdf. The function `bog-find-citekey-pdf' will open a PDF
  associated with a citekey. If the point is on a citekey, it will open
  that citekey. Otherwise, it will use the citekey from the first parent
  heading that is a study.


2.4 Opening a BibTeX file for a citekey
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  The function `bog-find-citekey-bib' will open the BibTeX entry
  associated with a citekey.

  The citekey is obtained in the same way as the PDF 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.5 Searching online for a citekey
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  The function `bog-search-citekey-on-web' will perform a search with
  the citekey information. By default, Google Scholar is searched. 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.6 Renaming a new PDF
~~~~~~~~~~~~~~~~~~~~~~

  New PDF files can be put in a "stage" directory and then renamed to a
  citekey. (The citekey can be taken from the notes context, as
  described in Opening a PDF file.)


2.7 Renaming a new BibTeX file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  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.8 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 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 b  bog-find-citekey-bib      
   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 "b" 'bog-find-citekey-bib)
  | (define-key bog-map "w" 'bog-search-citekey-on-web)
  `----