diff options
Diffstat (limited to 'bog-readme.org')
| -rw-r--r-- | bog-readme.org | 114 |
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 |