diff --git a/ChangeLog b/ChangeLog index 44116354..ab836ea2 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2022-08-06 Mats Lidell + +* hyrolo.el: Shorten docs strings to be within 80 char limit. + 2022-07-26 Mats Lidell * kotl/kproperty.el: diff --git a/hyrolo.el b/hyrolo.el index 1d50f590..6e0013e7 100644 --- a/hyrolo.el +++ b/hyrolo.el @@ -3,7 +3,7 @@ ;; Author: Bob Weiner ;; ;; Orig-Date: 7-Jun-89 at 22:08:29 -;; Last-Mod: 3-Jul-22 at 09:46:59 by Bob Weiner +;; Last-Mod: 6-Aug-22 at 22:46:40 by Mats Lidell ;; ;; Copyright (C) 1991-2022 Free Software Foundation, Inc. ;; See the "HY-COPY" file for license information. @@ -48,15 +48,17 @@ :group 'hyperbole) (defcustom hyrolo-date-format "%m/%d/%Y" - "*Format of date string used in Rolo automatic date stamps. Default is American style. -See documentation of the function `format-time-string' for format options." + "*Format of date string used in Rolo automatic date stamps. +Default is American style. See documentation of the function +`format-time-string' for format options." :type 'string :group 'hyperbole-rolo) (defvar hyrolo-display-format-function (lambda (entry) (concat (replace-regexp-in-string "[ \t\n\r]+\\'" "" entry nil t) "\n")) - "*Function of one argument, a rolo entry string, which modifies the string for display.") + "*Function of one argument which modifies the string for display. +The argument is a rolo entry string.") (defcustom hyrolo-email-format "%s\t\t<%s>" "*Format string to use when adding an entry with e-mail addr from a mail msg. @@ -103,7 +105,10 @@ executable must be found as well (for Oauth security)." (defvar hproperty:highlight-face) (defun hyrolo-google-contacts-p () - "Return non-nil if `hyrolo-google-contacts-flag' is non-nil and google-contacts package and gpg executables are available for use." + "Non-nil means google contacts package is available and feature is enabled. +Requires `hyrolo-google-contacts-flag' set as non-nil and +google-contacts package and gpg executables to be available for +use." (and hyrolo-google-contacts-flag (featurep 'google-contacts) (boundp 'google-contacts-buffer-name) @@ -165,7 +170,7 @@ Only unmodified buffers are killed." (add-hook 'hyrolo-edit-hook #'hyrolo-set-date) (defvar hyrolo-yank-reformat-function nil - "*Value is a function of two arguments, START and END, invoked after a hyrolo-yank. + "*A function of two arguments, START and END, invoked after a hyrolo-yank. It should reformat the region given by the arguments to some preferred style. Default value is nil, meaning no reformmating is done.") @@ -299,7 +304,8 @@ entry which begins with the parent string." (defun hyrolo-display-matches (&optional display-buf return-to-buffer) "Display optional DISPLAY-BUF buffer of previously found rolo matches. If DISPLAY-BUF is nil, use the value in `hyrolo-display-buffer'. -Second arg RETURN-TO-BUFFER is the buffer to leave point within after the display." +Second arg RETURN-TO-BUFFER is the buffer to leave point within +after the display." (interactive) (unless display-buf (setq display-buf (get-buffer hyrolo-display-buffer))) @@ -332,10 +338,11 @@ Second arg RETURN-TO-BUFFER is the buffer to leave point within after the displa ;;;###autoload (defun hyrolo-edit (&optional name file) "Edit a rolo entry given by optional NAME within `hyrolo-file-list'. -With prefix argument, prompts for optional FILE to locate entry within. -With no NAME arg, simply displays FILE or first entry in `hyrolo-file-list' in an -editable mode. NAME may be of the form: parent/child to edit child below a -parent entry which begins with the parent string." +With prefix argument, prompts for optional FILE to locate entry +within. With no NAME arg, simply displays FILE or first entry in +`hyrolo-file-list' in an editable mode. NAME may be of the form: +parent/child to edit child below a parent entry which begins with +the parent string." (interactive "sEdit rolo entry named: \nP") (when (string-equal name "") (setq name nil)) @@ -392,7 +399,8 @@ Return entry name if found, else nil." ;;;###autoload (defun hyrolo-fgrep (string &optional max-matches hyrolo-file count-only no-display) - "Display rolo entries matching STRING (or a logical match expression) and return count of matches. + "Display rolo entries matching STRING or a logical match expression. +Return count of matches. To a maximum of optional prefix arg MAX-MATCHES, in file(s) from optional HYROLO-FILE or `hyrolo-file-list'. Default is to find all matching entries. Each entry is displayed with all of its sub-entries. Optional COUNT-ONLY @@ -426,7 +434,8 @@ the logical expression matching." ;;;###autoload (defun hyrolo-find-file (&optional file) - "Select and edit a file in `hyrolo-file-list', defaulting to the first listed file when not given a prefix arg." + "Select and edit a file in `hyrolo-file-list'. +Default is the first listed file when not given a prefix arg." (interactive "P") (when (or (called-interactively-p 'interactive) (null file)) @@ -442,11 +451,12 @@ the logical expression matching." ;;;###autoload (defun hyrolo-grep (regexp &optional max-matches hyrolo-file-or-bufs count-only no-display) "Display rolo entries matching REGEXP and return count of matches. -To a maximum of prefix arg MAX-MATCHES, in buffer(s) from optional HYROLO-FILE-OR-BUFS or -hyrolo-file-list. Default is to find all matching entries. Each entry is -displayed with all of its sub-entries. Optional COUNT-ONLY non-nil means don't -retrieve and don't display matching entries. Optional NO-DISPLAY non-nil -means retrieve entries but don't display. +To a maximum of prefix arg MAX-MATCHES, in buffer(s) from +optional HYROLO-FILE-OR-BUFS or hyrolo-file-list. Default is to +find all matching entries. Each entry is displayed with all of +its sub-entries. Optional COUNT-ONLY non-nil means don't +retrieve and don't display matching entries. Optional NO-DISPLAY +non-nil means retrieve entries but don't display. Nil value of MAX-MATCHES means find all matches, t value means find all matches but omit file headers, negative values mean find up to the inverse of that @@ -504,7 +514,7 @@ With optional prefix ARG, do an fgrep string match instead of a regexp match." (call-interactively (if arg 'hyrolo-fgrep 'hyrolo-grep))) (defun hyrolo-hide-subtree () - "Move back to the start of current subtree if any and hide everything after the heading. + "Move back to the start of current subtree and hide everything after the heading. Necessary, since with reveal-mode active, outline-hide-subtree works only if on the heading line of the subtree." @@ -518,9 +528,10 @@ only if on the heading line of the subtree." (goto-char opoint)))) (defun hyrolo-isearch (&optional arg) - "Interactively search forward for the next occurrence of the current match string. -Then add characters to further narrow the search. With optional prefix ARG non-nil, -search for the current match regular expression rather than string." + "Interactively search forward for the next occurrence of current match string. +Then add characters to further narrow the search. With optional +prefix ARG non-nil, search for the current match regular +expression rather than string." (interactive "P") (if arg (hyrolo-isearch-regexp) @@ -531,9 +542,10 @@ search for the current match regular expression rather than string." (isearch-forward)))) (defun hyrolo-isearch-regexp (&optional arg) - "Interactively search forward for the next occurrence of the current match regexp. -Then add characters to further narrow the search. With optional prefix ARG non-nil, -search for the current match string rather than regular expression." + "Interactively search forward for the next occurrence of current match regexp. +Then add characters to further narrow the search. With optional +prefix ARG non-nil, search for the current match string rather +than regular expression." (interactive "P") (if arg (hyrolo-isearch) @@ -635,7 +647,8 @@ Return t if entry is killed, nil otherwise." (defun hyrolo-overview (levels-to-show) "Show the first line of all levels of rolo matches. -With a prefix argument of LEVELS-TO-SHOW > 0, show the first lines of entries only to that depth." +With a prefix argument of LEVELS-TO-SHOW > 0, show the first +lines of entries only to that depth." (interactive "P") (hyrolo-verify) ;; Use {t} to display top-level cells only. @@ -758,7 +771,8 @@ of groupings sorted." ;; This wraps forward-visible-line, making its ARG optional, making ;; its calling convention match that of forward-line. (defun hyrolo-forward-visible-line (&optional arg) - "Move forward by optional ARG lines (default = 1), ignoring currently invisible newlines only. + "Move forward by optional ARG lines (default = 1). +Ignore currently invisible newlines only. If ARG is negative, move backward -ARG lines. If ARG is zero, move to the beginning of the current line." (unless arg @@ -905,7 +919,8 @@ Output looks like so: (read-only-mode 1))) (defun hyrolo-bbdb-grep-file (hyrolo-file-or-buf regexp &optional max-matches count-only) - "Retrieve entries in bbdb HYROLO-FILE-OR-BUF matching REGEXP to a maximum of optional MAX-MATCHES. + "Retrieve entries in bbdb HYROLO-FILE-OR-BUF matching REGEXP. +Find a maximum of optional MAX-MATCHES. Nil value of MAX-MATCHES means find all matches, t value means find all matches but omit file headers, negative values mean find up to the inverse of that number of entries and omit file headers. Optional COUNT-ONLY non-nil @@ -959,7 +974,8 @@ Output looks like so: (read-only-mode 1))) (defun hyrolo-google-contacts-grep-file (hyrolo-file-or-buf regexp &optional max-matches count-only) - "Retrieve entries in google-contacts HYROLO-FILE-OR-BUF matching REGEXP to a maximum of optional MAX-MATCHES. + "Retrieve entries in google-contacts HYROLO-FILE-OR-BUF matching REGEXP. +Find a maximum of optional MAX-MATCHES. Nil value of MAX-MATCHES means find all matches, t value means find all matches but omit file headers, negative values mean find up to the inverse of that number of entries and omit file headers. Optional COUNT-ONLY non-nil @@ -1105,7 +1121,8 @@ otherwise just use the cdr of the item." ;;;###autoload (defun hyrolo-helm-org-rifle () - "Prompt for a search pattern with helm and interactively show all matches from `hyrolo-file-list'." + "Search with helm and interactively show all matches from `hyrolo-file-list'. +Prompt for the search pattern." (interactive) (unless (package-installed-p 'helm-org-rifle) (package-install 'helm-org-rifle)) @@ -1120,7 +1137,8 @@ otherwise just use the cdr of the item." ;;;###autoload (defun hyrolo-org () - "Prompt for patterns and search Org directory files for string or logic-based matches." + "Search Org directory files for string or logic-based matches. +Prompt for patterns to search for." (interactive "sFind Org directory string (or logical expression): \nP") (require 'org) (unless (file-readable-p org-directory) @@ -1134,7 +1152,7 @@ otherwise just use the cdr of the item." ;;;###autoload (defun hyrolo-org-roam (string &optional max-matches) - "Search Org Roam directory files for string or logic-based matches." + "Search Org Roam directory files for STRING or logic-based matches." (interactive "sFind Org Roam directory string (or logical expression): \nP") (unless (package-installed-p 'org-roam) (package-install #'org-roam)) @@ -1153,7 +1171,8 @@ otherwise just use the cdr of the item." ;;; ************************************************************************ (defun hyrolo-fgrep-file (hyrolo-file-or-buf string &optional max-matches count-only) - "Retrieve entries in HYROLO-FILE-OR-BUF matching STRING to a maximum of optional MAX-MATCHES. + "Retrieve entries in HYROLO-FILE-OR-BUF matching STRING. +Retrieve a maximum of optional MAX-MATCHES. Nil value of MAX-MATCHES means find all matches, t value means find all matches but omit file headers, negative values mean find up to the inverse of that number of entries and omit file headers. Optional COUNT-ONLY non-nil @@ -1162,7 +1181,8 @@ Return number of matching entries found." (hyrolo-grep-file hyrolo-file-or-buf (regexp-quote string) max-matches count-only)) (defun hyrolo-grep-file (hyrolo-file-or-buf regexp &optional max-matches count-only) - "Retrieve entries in HYROLO-FILE-OR-BUF matching REGEXP to a maximum of optional MAX-MATCHES. + "Retrieve entries in HYROLO-FILE-OR-BUF matching REGEXP. +Retrieve a maximum of optional MAX-MATCHES. Nil value of MAX-MATCHES means find all matches, t value means find all matches but omit file headers, negative values mean find up to the inverse of that number of entries and omit file headers. Optional COUNT-ONLY non-nil @@ -1307,7 +1327,8 @@ Return number of groupings matched." ;;; ************************************************************************ (defun hyrolo-add-match (hyrolo-matches-buffer regexp start end) - "Insert before point in HYROLO-MATCHES-BUFFER an entry matching REGEXP from the current region between START to END." + "Insert in HYROLO-MATCHES-BUFFER an entry matching REGEXP from current region. +Entry is inserted before point. The region is between START to END." (let ((hyrolo-buf (current-buffer)) (hyrolo-entry (buffer-substring-no-properties start end)) opoint) @@ -1408,7 +1429,7 @@ Name is returned as `last, first-and-middle'." (list name email)))) (defun hyrolo-name-at () - "If point is within an entry in `hyrolo-display-buffer', return the entry name, else nil." + "If point is on an entry in `hyrolo-display-buffer', return its name, else nil." (if (string-equal (buffer-name) hyrolo-display-buffer) (save-excursion (if (or (looking-at hyrolo-entry-regexp) @@ -1447,7 +1468,8 @@ a default of MM/DD/YYYY." (insert "\n\t" (hyrolo-current-date))))) (defun hyrolo-show-levels (num-levels) - "Show only the first line of up to NUM-LEVELS of rolo matches. NUM-LEVELS must be 1 or greater." + "Show only the first line of up to NUM-LEVELS of rolo matches. +NUM-LEVELS must be 1 or greater." (outline-show-all) (save-excursion (goto-char (point-min)) @@ -1539,10 +1561,10 @@ Return point where matching entry begins or nil if not found." (pop-to-buffer buffer other-window-flag)) (defun hyrolo-to-entry-end (&optional include-sub-entries curr-entry-level-len) - "Move point to the end of the whole entry that point is within if optional INCLUDE-SUB-ENTRIES is non-nil. + "Move point to the end of whole entry if optional INCLUDE-SUB-ENTRIES is non-nil. CURR-ENTRY-LEVEL-LEN is the integer length of the last entry -header found. If INCLUDE-SUB-ENTRIES is nil, CURR-ENTRY-LEVEL-LEN is not needed. -Return current point." +header found. If INCLUDE-SUB-ENTRIES is nil, +CURR-ENTRY-LEVEL-LEN is not needed. Return current point." ;; Set free variable, next-entry-exists, for speed. (while (and (setq next-entry-exists (re-search-forward hyrolo-entry-regexp nil t)) @@ -1581,7 +1603,8 @@ Calls the functions given by `hyrolo-mode-hook'. "Buffer used to display set of last matching rolo entries.") (defvar hyrolo-entry-group-number 1 - "Group number within `hyrolo-entry-regexp' whose length represents the level of any entry matched.") + "Group number whose length represents the level of any entry matched. +See `hyrolo-entry-regexp'") (defvar hyrolo-entry-trailing-space-group-number 2 "Group number within `hyrolo-entry-regexp; containing trailing space.")