From 5cbdbb0fc25ce28520d3fb6355775f0e851a2acc Mon Sep 17 00:00:00 2001 From: Kyle Meyer Date: Sat, 8 Feb 2014 00:20:57 -0500 Subject: DOC: Export README text file for GitHub --- README | 178 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 178 insertions(+) create mode 100644 README (limited to 'README') diff --git a/README b/README new file mode 100644 index 0000000..8409bc1 --- /dev/null +++ b/README @@ -0,0 +1,178 @@ + _____ + + 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 + + +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. On the other hand, it shouldn't be so easy that I + file them away without giving them any thought. For me, this means + capturing the article and a link in my normal Org notes system. At + some point, I glance over it enough to decide what general topic it + should be in and refile it into a research notes file. + + I prefer adding BibTeX and PDF files lazily. My only requirement is + that I put it in a relevant heading and that I name it with a + proper citekey. I make sure to add a link to the study online. 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: + | + | + | + | Article notes + `---- + + "name2000word" is the study header. (The default format for the + citekey is the first author's last name, the year, and then the first + non-trivial word.) Bog expects the study citekey to be the title or + property of a heading. + + 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 + -*.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 .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-rename-and-clean-new-bib-files' 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 needs to 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. -- cgit v1.2.3