summaryrefslogtreecommitdiff
path: root/README
diff options
context:
space:
mode:
authorKyle Meyer <kyle@kyleam.com>2014-03-16 01:26:54 -0400
committerKyle Meyer <kyle@kyleam.com>2014-03-16 02:39:35 -0400
commit606f7b501a60afe2f6c135acb0ce9974eb9b991c (patch)
treefe5ef411bb48fc989a5c72ef3d8e998fbbc740bc /README
parentd7ef28aa79d92cc088898284688dbc134b0bdd5e (diff)
downloadbog-606f7b501a60afe2f6c135acb0ce9974eb9b991c.tar.gz
DOC: Revise README
Diffstat (limited to 'README')
-rw-r--r--README170
1 files changed, 72 insertions, 98 deletions
diff --git a/README b/README
index 5e2f89a..43f477d 100644
--- a/README
+++ b/README
@@ -7,21 +7,19 @@
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 new PDFs
-.. 2.7 Renaming new BibTeX files
-.. 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
+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.
@@ -29,68 +27,33 @@ and taking notes with Org, not on writing research articles with Org.
[Org mode] http://orgmode.org/
-1 Bog workflow
-==============
+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 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.
+ 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.
- 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 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).
,----
- | # In a very general topic file
+ | * Topic heading
|
- | * Topic heder
- |
- | ** name2000word :atag:
+ | ** TODO name2000word :atag:
|
| <URL for study>
|
- | Article notes
+ | Article notes ... a reference to another1999study ...
`----
- "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-*'
@@ -104,70 +67,58 @@ and taking notes with Org, not on writing research articles with Org.
| 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.
+ [these] http://thread.gmane.org/gmane.emacs.orgmode/78983
-2.2 Referencing studies within notes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ [threads] http://thread.gmane.org/gmane.emacs.orgmode/14756
- You can reference other studies with their citekey.
- ,----
- | ** name2000word :atag:
- |
- | Another study (another1999word).
- `----
+2 Main features
+===============
- "another1999word" will be highlighted within the text. When the point
- is within the citekey, many Bog functions can extract and use the
- citekey.
+ 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.3 Opening a PDF file for a citekey
+2.1 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.
+ The function `bog-find-citekey-pdf' will open a PDF associated with a
+ citekey.
-2.4 Opening a BibTeX file for 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.
- 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
+2.3 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.
+ 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.6 Renaming new PDFs
+2.4 Renaming new PDFs
~~~~~~~~~~~~~~~~~~~~~
New PDF files can be put in a "stage" directory and then renamed to a
- citekey. (The citekey is taken from the notes context.)
+ citekey.
-2.7 Renaming new BibTeX files
+2.5 Renaming new BibTeX files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If a separate BibTeX file is used for each citekey,
@@ -176,7 +127,7 @@ and taking notes with Org, not on writing research articles with Org.
autogenerate the key.
-2.8 Generating a combined BibTeX file
+2.6 Generating a combined BibTeX file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If single-entry BibTeX files are used, there should be a way to
@@ -185,7 +136,30 @@ and taking notes with Org, not on writing research articles with Org.
in the current buffer.
-3 Recommended keybindings
+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