summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKyle Meyer <kyle@kyleam.com>2014-02-08 00:20:57 -0500
committerKyle Meyer <kyle@kyleam.com>2014-02-08 00:22:23 -0500
commit5cbdbb0fc25ce28520d3fb6355775f0e851a2acc (patch)
treee28062896191f807522fefe3f67d077c8e6ec9d9
parentff679136b8e2273a79dc6ce68785b6fbbd898de7 (diff)
downloadbog-5cbdbb0fc25ce28520d3fb6355775f0e851a2acc.tar.gz
DOC: Export README text file for GitHub
-rw-r--r--README178
-rw-r--r--README.md7
-rwxr-xr-xpre-commit4
-rw-r--r--readme-to-ascii.el12
4 files changed, 194 insertions, 7 deletions
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:
+ |
+ | <URL for study>
+ |
+ | 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
+ <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.
+
+
+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 <citekey>.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))