#+title: Bog
#+options: toc:nil
#+startup: showall

[[https://github.com/kyleam/bog/actions/workflows/test.yml][https://github.com/kyleam/bog/actions/workflows/test.yml/badge.svg]]
[[https://melpa.org/#/bog][https://melpa.org/packages/bog-badge.svg]]

Bog is a system for taking research notes in [[https://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 [[https://melpa.org/][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

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 file and other associated files.

In the example below, the citekey "name2000word" is a study heading.  A
study heading is defined as a heading that has a citekey as a title or
as the value of =bog-citekey-property=.  When a citekey occurs anywhere
else (like "another1999study" below), it is taken as 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:

  <URL for study>

  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 'infty
        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.  If the point is on
a citekey (like "another1999study" above), then that citekey will be
used.  If this fails, many functions will try to take the citekey from
the first parent heading that is a study heading.

- =bog-find-citekey-file=

  Open an associated file (usually a PDF) 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-file-to-citekey=

  Rename a new file (usually a PDF) to be associated with a citekey.

- =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-citekey-tree-to-indirect-buffer=
- =bog-goto-citekey-heading-in-notes=
- =bog-insert-heading-citekey=
- =bog-jump-to-topic-heading=
- =bog-list-duplicate-heading-citekeys=
- =bog-list-orphan-citekeys=
- =bog-open-citekey-link=
- =bog-open-first-citekey-link=
- =bog-refile=
- =bog-search-notes=
- =bog-search-notes-for-citekey=
- =bog-sort-topic-headings-in-buffer=
- =bog-sort-topic-headings-in-notes=

You can try out many of the commands in
[[file:example/notes/org-mode-pubs.org][example/notes/org-mode-pubs.org]].

* Variables

Several variables determine where Bog looks for things.

- =bog-bib-directory= or =bog-bib-file=
- =bog-file-directory=
- =bog-note-directory=
- =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-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.

* 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=.

Many of the Bog functions are useful outside of an Org buffer.  You
can turn Bog minor mode on (=bog-mode=) in non-Org buffers to get
access to the keymap and citekey highlighting.  To make Bog commands
available from any buffer, bind =bog-command-map= to a global key.

* Other approaches

If Bog doesn't fit your workflow, there are a good number of other
approaches to explore.  On the Org mode mailing list, there are some
[[https://yhetil.org/orgmode/528AC19F.3000803@binghamton.edu/][nice]] [[https://yhetil.org/orgmode/2c75873c0906230106h3daf3d34y230845e15dad278e@mail.gmail.com/][descriptions]] of systems people have come up with for taking
research notes in Org.  For a package that focuses on both taking
research notes and writing research articles, look into [[https://github.com/jkitchin/org-ref][Org-ref]].