summaryrefslogtreecommitdiff
path: root/bog.el
diff options
context:
space:
mode:
Diffstat (limited to 'bog.el')
-rw-r--r--bog.el121
1 files changed, 60 insertions, 61 deletions
diff --git a/bog.el b/bog.el
index f60e952..9a0150b 100644
--- a/bog.el
+++ b/bog.el
@@ -101,7 +101,7 @@ The default corresponds to the default value of
(expand-file-name "stage/" bog-root-directory)
"Directory to search for new files.
`bog-rename-staged-file-to-citekey' and
-`bog-rename-staged-bib-to-citekey' will search here for files to
+`bog-rename-staged-bib-to-citekey' searches here for files to
rename."
:group 'bog
:type 'directory)
@@ -152,11 +152,10 @@ only built-in function is `bog-file-ask-on-conflict'."
(defcustom bog-file-secondary-name "-supplement"
"Modification to make to file name on renaming confict.
-When a staged file is being renamed with
-`bog-file-ask-on-conflict', the user will be prompted if
-<citekey>.<ext> already exists.
-<citekey>`bog-file-secondary-name'.<ext> will be the default
-value for the prompt."
+If <citekey>.<ext> already exists, `bog-file-ask-on-conflict'
+prompts for another name.
+<citekey>`bog-file-secondary-name'.<ext> is the default value for
+the prompt."
:group 'bog
:type 'string)
@@ -200,11 +199,12 @@ added citekeys, clear the cache with `bog-clear-citekey-cache'."
(defmacro bog-selection-method (name context-method collection-method)
"Create citekey selection function.
-Function will be named bog-citekey-from-NAME and will take one
-argument (NO-CONTEXT). If NO-CONTEXT is nil, CONTEXT-METHOD will
-be called with no arguments. If CONTEXT-METHOD returns nil or if
-NO-CONTEXT is non-nil, the user will be prompted with citekeys
-gathered by COLLECTION-METHOD."
+Create a function named bog-citekey-from-NAME with the following
+behavior:
+- Takes one argument (NO-CONTEXT).
+- If NO-CONTEXT is nil, calls CONTEXT-METHOD with no arguments.
+- If CONTEXT-METHOD returns nil or if NO-CONTEXT is non-nil,
+ prompts with the citekeys gathered by COLLECTION-METHOD."
`(defun ,(intern (concat "bog-citekey-from-" name)) (no-context)
,(format "Select citekey with `%s', falling back on `%s'.
If NO-CONTEXT is non-nil, immediately fall back."
@@ -307,7 +307,7 @@ word constituents."
(defvar bog--all-heading-citekeys nil)
(defun bog-all-heading-citekeys ()
- "Return all citekeys in headings of notes."
+ "Return citekeys that have a heading in any note file."
(or (and bog-use-citekey-cache bog--all-heading-citekeys)
(setq bog--all-heading-citekeys (-mapcat 'bog-heading-citekeys-in-file
(bog-notes)))))
@@ -396,12 +396,12 @@ With prefix FILE, include only orphan citekeys from that file."
(defun bog-find-citekey-file (&optional no-context)
"Open citekey-associated file.
-The citekey will be taken from the text under point if it matches
+The citekey is taken from the text under point if it matches
`bog-citekey-format' or from the current tree.
-With prefix argument NO-CONTEXT, a prompt will open to select
-from citekeys for all associated files. This same prompt will be
-opened if locating a citekey from context fails."
+With prefix argument NO-CONTEXT, prompt with citekeys that have
+an associated file in `bog-file-directory'. Do the same if
+locating a citekey from context fails."
(interactive "P")
(bog--find-citekey-file
(bog-citekey-from-surroundings-or-files no-context)))
@@ -435,12 +435,12 @@ character in `bog-citekey-file-name-separators'."
(defun bog-rename-staged-file-to-citekey (&optional no-context)
"Rename citekey file in `bog-stage-directory' with `bog-file-renaming-func'.
-The citekey will be taken from the text under point if it matches
+The citekey is taken from the text under point if it matches
`bog-citekey-format' or from the current tree.
-With prefix argument NO-CONTEXT, a prompt will open to select
-from all citekeys present in notes. This same prompt will be
-opened if locating a citekey from context fails.
+With prefix argument NO-CONTEXT, prompt with citekeys present in
+any note file. Do the same if locating a citekey from context
+fails.
If the citekey file prompt is slow to appear, consider enabling
`bog-use-citekey-cache'."
@@ -465,10 +465,10 @@ If the citekey file prompt is slow to appear, consider enabling
(defun bog-file-ask-on-conflict (staged-file citekey)
"Rename citekey file, prompting for a new name if it already exists.
-STAGED-FILE will be renamed to <citekey>.<ext> within
-`bog-file-directory'. If this file already exists, the user will
-be prompted for another name. `bog-file-secondary-name' can be
-used to control the default string used in the prompt."
+STAGED-FILE is renamed to <citekey>.<ext> within
+`bog-file-directory'. If this file already exists, prompt for
+another name. `bog-file-secondary-name' controls the default
+string for the prompt."
(let* ((ext (file-name-extension staged-file))
(citekey-file (bog-citekey-as-file citekey ext)))
(condition-case nil
@@ -521,15 +521,15 @@ used to control the default string used in the prompt."
(defun bog-find-citekey-bib (&optional no-context)
"Open BibTeX file for a citekey.
-The citekey will be taken from the text under point if it matches
+The citekey is taken from the text under point if it matches
`bog-citekey-format' or from the current tree.
The variable `bog-find-citekey-bib-func' determines how the
citekey is found.
-With prefix argument NO-CONTEXT, a prompt will open to select
-from citekeys for all BibTeX files. This same prompt will be
-opened if locating a citekey from context fails."
+With prefix argument NO-CONTEXT, prompt with citekeys that have a
+BibTeX entry. Do the same if locating a citekey from context
+fails."
(interactive "P")
(funcall bog-find-citekey-bib-func
(bog-citekey-from-surroundings-or-bibs no-context)))
@@ -550,9 +550,9 @@ opened if locating a citekey from context fails."
(defun bog-clean-and-rename-staged-bibs ()
"Clean and rename BibTeX files in `bog-stage-directory'.
-New BibTeX files are searched for in `bog-stage-directory', and
-`bibtex-clean-entry' will be run one each file before it is moved
-to `bog-bib-directory'/<citekey>.bib.
+Search for new BibTeX files in `bog-stage-directory', and run
+`bibtex-clean-entry' on each file before it is moved to
+`bog-bib-directory'/<citekey>.bib.
This function is only useful if you use the non-standard setup of
one entry per BibTeX file."
@@ -639,17 +639,17 @@ instead of citekeys from file names in `bog-bib-directory'."
(defun bog-search-citekey-on-web (&optional no-context)
"Open browser and perform query based for a citekey.
-The URL will be taken from `bog-web-search-url'.
+Take the URL from `bog-web-search-url'.
The citekey is split by groups in `bog-citekey-format' and joined by
\"+\" to form the query string.
-The citekey will be taken from the text under point if it matches
+The citekey is taken from the text under point if it matches
`bog-citekey-format' or from the current tree.
-With prefix argument NO-CONTEXT, a prompt will open to select
-from all citekeys present in notes. This same prompt will be
-opened if locating a citekey from context fails.
+With prefix argument NO-CONTEXT, prompt with citekeys present in
+any note file. Do the same if locating a citekey from context
+fails.
If the citekey file prompt is slow to appear, consider enabling
`bog-use-citekey-cache'."
@@ -679,12 +679,12 @@ Groups are specified by `bog-citekey-web-search-groups'."
(defun bog-goto-citekey-heading-in-buffer (&optional no-context)
"Find citekey heading in this buffer.
-The citekey will be taken from the text under point if it matches
+The citekey is taken from the text under point if it matches
`bog-citekey-format'.
-With prefix argument NO-CONTEXT, a prompt will open to select
-from all citekeys for headings in the current buffer. This same
-prompt will be opened if locating a citekey from context fails.
+With prefix argument NO-CONTEXT, prompt with citekeys that have a
+heading in the current buffer. Do the same if locating a citekey
+from context fails.
If the heading is found outside any current narrowing of the
buffer, the narrowing is removed."
@@ -734,12 +734,12 @@ is non-nil, return the position instead of a marker."
(defun bog-goto-citekey-heading-in-notes (&optional no-context)
"Find citekey heading in notes.
-The citekey will be taken from the text under point if it matches
+The citekey is taken from the text under point if it matches
`bog-citekey-format'.
-With prefix argument NO-CONTEXT, a prompt will open to select
-from all citekeys for headings in notes. This same prompt will
-be opened if locating a citekey from context fails.
+With prefix argument NO-CONTEXT, prompt with citekeys that have a
+heading in any note file. Do the same if locating a citekey from
+context fails.
If the citekey file prompt is slow to appear, consider enabling
`bog-use-citekey-cache'.
@@ -787,12 +787,12 @@ there first."
(defun bog-citekey-tree-to-indirect-buffer (&optional no-context)
"Open subtree for citekey in an indirect buffer.
-The citekey will be taken from the text under point if it matches
+The citekey is taken from the text under point if it matches
`bog-citekey-format'.
-With prefix argument NO-CONTEXT, a prompt will open to select
-from all citekeys for headings in notes. This same prompt will
-be opened if locating a citekey from context fails.
+With prefix argument NO-CONTEXT, prompt with citekeys that have a
+heading in any note file. Do the same if locating a citekey from
+context fails.
If the citekey file prompt is slow to appear, consider enabling
`bog-use-citekey-cache'."
@@ -834,9 +834,9 @@ level `bog-refile-maxlevel' are considered."
(defun bog-search-notes (&optional todo-only string)
"Search notes using `org-search-view'.
-With prefix argument TODO-ONLY, only TODO entries are searched.
-If STRING is non-nil, this will be used as the search
-term (instead of prompting the user for one)."
+With prefix argument TODO-ONLY, search only TODO entries. If
+STRING is non-nil, use it as the search term (instead of
+prompting for one)."
(interactive "P")
(let ((lprops '((org-agenda-files (bog-notes))
(org-agenda-text-search-extra-files nil))))
@@ -846,12 +846,11 @@ term (instead of prompting the user for one)."
(defun bog-search-notes-for-citekey (&optional todo-only)
"Search notes for citekey using `org-search-view'.
-With prefix argument TODO-ONLY, only TODO entries are searched.
+With prefix argument TODO-ONLY, search only TODO entries.
-The citekey will be taken from the text under point if it matches
+The citekey is taken from the text under point if it matches
`bog-citekey-format' or from the current tree. If a citekey is
-not found, a prompt will open to select from all citekeys present
-in notes."
+not found, prompt with citekeys present in any note file."
(interactive "P")
(bog-search-notes todo-only
(bog-citekey-from-surroundings-or-all nil)))
@@ -859,7 +858,7 @@ in notes."
(defun bog-sort-topic-headings-in-buffer (&optional sorting-type)
"Sort topic headings in this buffer.
SORTING-TYPE is a character passed to `org-sort-entries'. If
-nil, ?a is used. The level to sort is determined by
+nil, use ?a. The level to sort is determined by
`bog-topic-heading-level'."
(interactive)
(org-map-entries (lambda () (bog-sort-if-topic-header sorting-type))))
@@ -867,7 +866,7 @@ nil, ?a is used. The level to sort is determined by
(defun bog-sort-topic-headings-in-notes (&optional sorting-type)
"Sort topic headings in notes.
Unlike `bog-sort-topic-headings-in-buffer', sort topic headings
-in all notes."
+in all note files."
(interactive)
(org-map-entries (lambda () (bog-sort-if-topic-header sorting-type))
nil (bog-notes)))
@@ -895,12 +894,12 @@ current buffer."
(defun bog-open-first-citekey-link (&optional no-context)
"Open first link under citekey heading.
-The citekey will be taken from the text under point if it matches
+The citekey is taken from the text under point if it matches
`bog-citekey-format' or from the current tree.
-With prefix argument NO-CONTEXT, a prompt will open to select
-from all citekeys for headings in notes. This same prompt will
-be opened if locating a citekey from context fails."
+With prefix argument NO-CONTEXT, prompt with citekeys that have a
+heading in any note file. Do the same if locating a citekey from
+context fails."
(interactive "P")
(let* ((citekey (bog-citekey-from-point-or-all-headings no-context))
(marker (bog--find-exact-heading-in-notes citekey)))