From 606f7b501a60afe2f6c135acb0ce9974eb9b991c Mon Sep 17 00:00:00 2001 From: Kyle Meyer Date: Sun, 16 Mar 2014 01:26:54 -0400 Subject: DOC: Revise README --- README | 170 ++++++++++++++++++++++++--------------------------------- bog-readme.org | 114 +++++++++++++++----------------------- 2 files changed, 117 insertions(+), 167 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: | | | - | 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 - .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 .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 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: - 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 -.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 -- cgit v1.2.3