From 697d335ec491ec48e3cec0d59d15e839b0f22dec Mon Sep 17 00:00:00 2001 From: Kyle Meyer Date: Sun, 16 Mar 2014 01:29:27 -0400 Subject: DOC: Switch bog-readme.org export to markdown --- README.md | 196 +++++++++++++++++++++++++++++++++++++++++++++++++++++ pre-commit | 4 +- readme-to-ascii.el | 12 ---- readme-to-md.el | 13 ++++ 4 files changed, 211 insertions(+), 14 deletions(-) create mode 100644 README.md delete mode 100644 readme-to-ascii.el create mode 100644 readme-to-md.el diff --git a/README.md b/README.md new file mode 100644 index 0000000..b529363 --- /dev/null +++ b/README.md @@ -0,0 +1,196 @@ +
+

Table of Contents

+
+ +
+
+ +Bog is a system for taking research notes in [Org mode](http://orgmode.org/). 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. + +# 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](http://thread.gmane.org/gmane.emacs.orgmode/78983) [threads](http://thread.gmane.org/gmane.emacs.orgmode/14756) on the Org mode mailing list). + +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. + +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). + + + * Topic heading + + ** TODO name2000word :atag: + + + + Article notes ... a reference to another1999study ... + +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-*` +settings can be modified. + + (setq bibtex-autokey-year-length 4 + bibtex-autokey-titleword-length nil + bibtex-autokey-titlewords-stretch 0 + bibtex-autokey-titlewords 1 + bibtex-autokey-year-title-separator "") + +# Main features + +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 + +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. + +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 + +## Searching online for a citekey + +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. + +## Renaming new BibTeX files + +If a separate BibTeX file is used for each citekey, +`bog-clean-and-rename-staged-bibs` can be used to rename all new BibTeX +files. `bibtex-clean-entry` is used to clean the entry and autogenerate +the key. + +## Generating a combined BibTeX file + +If single-entry BibTeX files are used, there should 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. + +# 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 +in Org mode is a good option. + + + + +++ ++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyCommand
C-c b pbog-find-citekey-pdf
C-c b rbog-rename-staged-pdf-to-citekey
C-c b bbog-find-citekey-bib
C-c b hbog-goto-citekey-heading-in-buffer
C-c b Hbog-goto-citekey-heading-in-notes
C-c b wbog-search-citekey-on-web
+ +This can be achieved by placing the code below in your .emacs file. + + (define-prefix-command 'bog-map) + (define-key org-mode-map (kbd "C-c b") 'bog-map) + (define-key bog-map "p" 'bog-find-citekey-pdf) + (define-key bog-map "r" 'bog-rename-staged-pdf-to-citekey) + (define-key bog-map "b" 'bog-find-citekey-bib) + (define-key bog-map "h" 'bog-goto-citekey-heading-in-buffer) + (define-key bog-map "H" 'bog-goto-citekey-heading-in-notes) + (define-key bog-map "w" 'bog-search-citekey-on-web) \ No newline at end of file diff --git a/pre-commit b/pre-commit index 67247cf..67dd01f 100755 --- a/pre-commit +++ b/pre-commit @@ -1,4 +1,4 @@ #!/usr/bin/env sh -emacs --batch --load readme-to-ascii.el -git add README +emacs --batch --load readme-to-md.el +git add README.md diff --git a/readme-to-ascii.el b/readme-to-ascii.el deleted file mode 100644 index 2979d88..0000000 --- a/readme-to-ascii.el +++ /dev/null @@ -1,12 +0,0 @@ -(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 "bog-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)) diff --git a/readme-to-md.el b/readme-to-md.el new file mode 100644 index 0000000..3303029 --- /dev/null +++ b/readme-to-md.el @@ -0,0 +1,13 @@ +(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)) +(require 'ox-md) + +(let ((readme-file "bog-readme.org") + exported-file + (final-file "README.md")) + (with-current-buffer (find-file-noselect readme-file) + (setq exported-file (org-md-export-to-markdown))) + (rename-file exported-file final-file t)) -- cgit v1.2.3