From 9eb27768890dc9988e01e946bd450d5115f218b1 Mon Sep 17 00:00:00 2001 From: Kyle Meyer Date: Sat, 26 Apr 2014 16:50:39 -0400 Subject: Rename bog-readme.org to README --- README | 139 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 README (limited to 'README') diff --git a/README b/README new file mode 100644 index 0000000..a1080df --- /dev/null +++ b/README @@ -0,0 +1,139 @@ +# -*- mode: org -*- +#+title: Bog +#+options: toc:nil + +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. + +* Installation + +Bog is available on [[http://melpa.milkbox.net/][MELPA]]. + +To enable Bog in all Org buffers, add it to =org-mode-hook=. + +#+begin_src emacs-lisp + (add-hook 'org-mode-hook 'bog-mode) +#+end_src + +* 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 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). + +#+begin_example + + ,* Topic heading + + ,** TODO name2000word :atag: + + + + Article notes ... a reference to another1999study ... +#+end_example + +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. + +#+begin_src emacs-lisp + (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 "") +#+end_src + +* 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. + +- =bog-find-citekey-pdf= + + Open a PDF file for a citekey. + +- =bog-find-citekey-bib= + + Open a BibTeX file for a citekey. + + BibTeX entries can be stored in one of two ways: + - As a single file with many entries + - As single-entry files named citekey.bib within a common directory + +- =bog-search-citekey-on-web= + + Search Google Scholar for a citekey. The default citekey format (first + author's last name, year, and first non-trivial word) usually contains + enough information to make this search successful. + +- =bog-rename-staged-pdf-to-citekey= + + Rename a new PDF. + +- =bog-clean-and-rename-staged-bibs= + + Rename new BibTeX files. If a separate BibTeX file is used for each + citekey, this function can be used to rename all new BibTeX files. + =bibtex-clean-entry= is used to clean the entry and autogenerate the + key. + +- =bog-create-combined-bib= + + Generate a combined BibTeX file for all citekeys in buffer. This is + useful if single-entry BibTeX files are used. + +Other useful functions include + +- =bog-goto-citekey-heading-in-buffer= +- =bog-goto-citekey-heading-in-notes= +- =bog-refile= +- =bog-search-notes= +- =bog-search-notes-for-citekey= +- =bog-sort-topic-headings-in-buffer= +- =bog-sort-topic-headings-in-notes= + +* 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-function= + + 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-function= + + 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. + +* Keybindings + +A keymap is defined for Bog under the prefix =C-c "​=. If you prefer +something else (like =C-c b=), set =bog-keymap-prefix=. -- cgit v1.2.3