DOC: Revise README

1 files changed, 45 insertions, 69 deletions

diff --git a/bog-readme.org b/bog-readme.org
index a79e152..3a334a4 100644
--- a/bog-readme.org
+++ b/bog-readme.org
@@ -1,63 +1,35 @@
 #+title: Bog
 
-Bog is a system for taking research notes in [[http://orgmode.org/][Org mode]]. As any Org user
-knows, Org handles notetaking beautifully. Bog just adds a few
+Bog is a system for taking research notes in [[http://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.
 
-* Bog workflow
+* 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 [[http://thread.gmane.org/gmane.emacs.orgmode/78983][these]] [[http://thread.gmane.org/gmane.emacs.orgmode/14756][threads]] on the Org mode mailing list).
 
-The workflow for Bog is based on these preferences:
+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.
 
-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.
-
-* Features
-
-** 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).
 
 #+begin_example
-  # In a very general topic file
 
-  ,* Topic heder
+  ,* Topic heading
 
-  ,** name2000word                                    :atag:
+  ,** TODO name2000word                               :atag:
 
   <URL for study>
 
-  Article notes
+  Article notes ... a reference to another1999study ...
 #+end_example
 
-"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-*=
@@ -71,39 +43,24 @@ settings can be modified.
         bibtex-autokey-year-title-separator "")
 #+end_src
 
-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.
-
-** Referencing studies within notes
-
-You can reference other studies with their citekey.
+* Main features
 
-#+begin_example
-  ,** name2000word                                    :atag:
-
-  Another study (another1999word).
-#+end_example
-
-"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.
 
 ** 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.
 
 ** 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 [[Opening%20a%20PDF%20file][PDF citekey]].
-
 BibTeX entries can be stored in one of two ways:
 
 1. As a single file with many entries
@@ -111,16 +68,15 @@ BibTeX entries can be stored in one of two ways:
 
 ** 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.
 
 ** 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.
 
 ** Renaming new BibTeX files
 
@@ -136,6 +92,26 @@ 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.
 
+* 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.
+
 * Recommended keybindings
 
 Bog doesn't claim any keybindings, but using "C-c b" as a prefix while