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 +++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 7 --- pre-commit | 4 ++ readme-to-ascii.el | 12 ++++ 4 files changed, 194 insertions(+), 7 deletions(-) create mode 100644 README delete mode 100644 README.md create mode 100755 pre-commit create mode 100644 readme-to-ascii.el 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. diff --git a/README.md b/README.md deleted file mode 100644 index 1c73bef..0000000 --- a/README.md +++ /dev/null @@ -1,7 +0,0 @@ -```lisp -(let ((url "https://raw.github.com/kyleam/bog/master/README.org") - (buffer (generate-new-buffer "*Bog README*"))) - (switch-to-buffer-other-window buffer) - (url-insert-file-contents url) - (org-mode)) -``` diff --git a/pre-commit b/pre-commit new file mode 100755 index 0000000..67247cf --- /dev/null +++ b/pre-commit @@ -0,0 +1,4 @@ +#!/usr/bin/env sh + +emacs --batch --load readme-to-ascii.el +git add README diff --git a/readme-to-ascii.el b/readme-to-ascii.el new file mode 100644 index 0000000..5d28a34 --- /dev/null +++ b/readme-to-ascii.el @@ -0,0 +1,12 @@ +(defvar org-location "~/src/emacs/org-mode/lisp") + +(when (and org-location (file-exists-p org-location)) + (add-to-list 'load-path org-location) + (require 'org)) + +(let ((readme-file "README.org") + exported-file + (final-file "README")) + (with-current-buffer (find-file-noselect readme-file) + (setq exported-file (org-ascii-export-to-ascii))) + (rename-file exported-file final-file t)) -- cgit v1.2.3