Standardization spree:

- Use `pelican-mode’ rather than `pelican’ as a prefix, to match
  the package name

- Talk about “articles and pages”, not “posts and pages”, to match
  Pelican documentation.

- Improve a few documentation strings.

diff --git a/pelican-mode.el b/pelican-mode.el
index 3691c2fe4095a95dc6468c5001e2cd69235fd834..dd251d71d3f97bde9d06c362f1402cca3af0151d 100644 (file)
--- a/pelican-mode.el
+++ b/pelican-mode.el
@@ -33,32 +33,32 @@
 (require 'subr-x)
 
 (defgroup pelican-mode nil
-  "Support for Pelican posts and pages."
+  "Support for Pelican articles and pages."
   :group 'convenience)
 
 (defcustom pelican-mode-default-page-fields
   '(:slug slug)
   "Fields to include when creating a new page.
 
-See the documentation for `pelican-field' for more information
+See the documentation for `pelican-mode-field' for more information
 about metadata fields and special values."
-  :group 'pelican-mode
+  :group 'pelican
   :type '(plist))
 
-(defcustom pelican-mode-default-post-fields
+(defcustom pelican-mode-default-article-fields
   '(:date now :status "draft" :slug slug)
-  "Fields to include when creating a new post.
+  "Fields to include when creating a new article.
 
-See the documentation for `pelican-field' for more information
+See the documentation for `pelican-mode-field' for more information
 about metadata fields and special values."
-  :group 'pelican-mode
+  :group 'pelican
   :type '(plist))
 
-(defun pelican-timestamp (&optional time)
-  "Generate a Pelican-compatible timestamp for TIME."
+(defun pelican-mode-timestamp (&optional time)
+  "Generate a pelican-mode-compatible timestamp for TIME."
   (format-time-string "%Y-%m-%d %H:%M" time))
 
-(defun pelican-field (name value)
+(defun pelican-mode-field (name value)
   "Format a line for a field NAME with a VALUE.
 
 NAME may be a string or a symbol; if it is a symbol, the
@@ -67,16 +67,16 @@ symbol name is used (removing a leading ':' if present).
 VALUE may be any value; except for the following special values,
 the unquoted printed representation of it is used:
 
-- `now' means the current time; see `pelican-timestamp'.
+- `now' means the current time; see `pelican-mode-timestamp'.
 
 - `slug' means the file's path relative to the document root sans
-  extension; see `pelican-default-slug'.
+  extension; see `pelican-mode-default-slug'.
 
 - nil or an empty strings means return an empty string, without
   any name or value."
   (setq value (pcase value
-                ('now (pelican-timestamp))
-                ('slug (pelican-default-slug))
+                ('now (pelican-mode-timestamp))
+                ('slug (pelican-mode-default-slug))
                 ('"" nil)
                 (_ value)))
   (when (symbolp name)
@@ -89,55 +89,55 @@ the unquoted printed representation of it is used:
             (t (error "Unsupported major mode %S" major-mode)))
     ""))
 
-(defun pelican-rst-title (title)
+(defun pelican-mode-rst-title (title)
   "Format a reStructureText version of TITLE."
   (concat title "\n" (make-string (string-width title) ?#) "\n\n"))
 
-(defun pelican-title (title)
+(defun pelican-mode-title (title)
   "Format a TITLE for the current document, according to major mode."
   (cond ((derived-mode-p 'markdown-mode)
-         (pelican-field "title" title))
+         (pelican-mode-field "title" title))
         ((derived-mode-p 'rst-mode)
-         (pelican-rst-title title))
+         (pelican-mode-rst-title title))
         (t (error "Unsupported major mode %S" major-mode))))
 
-(defun pelican-header (title &rest fields)
-  "Generate a Pelican header for a post with a TITLE and metadata FIELDS."
-  (concat (pelican-title title)
-          (mapconcat (apply-partially #'apply #'pelican-field)
+(defun pelican-mode-header (title &rest fields)
+  "Generate a Pelican header for an article with a TITLE and metadata FIELDS."
+  (concat (pelican-mode-title title)
+          (mapconcat (apply-partially #'apply #'pelican-mode-field)
                      (seq-partition fields 2) "")
           "\n"))
 
-(defun pelican-insert-header (title &rest fields)
-  "Insert a Pelican header for a post with a TITLE and metadata FIELDS."
+(defun pelican-mode-insert-header (title &rest fields)
+  "Insert a Pelican header for an article with a TITLE and metadata FIELDS."
   (save-excursion
     (goto-char 0)
-    (insert (apply #'pelican-header (cons title fields)))))
+    (insert (apply #'pelican-mode-header (cons title fields)))))
 
-(defun pelican-insert-draft-post-header (title tags)
+(defun pelican-mode-insert-draft-article-header (title tags)
   "Insert a Pelican header for a draft with a TITLE and TAGS."
-  (interactive "sPost title: \nsTags: ")
-  (apply #'pelican-insert-header
-         `(,title ,@pelican-mode-default-post-fields :tags ,tags)))
+  (interactive "sArticle title: \nsTags: ")
+  (apply #'pelican-mode-insert-header
+         `(,title ,@pelican-mode-default-article-fields :tags ,tags)))
 
-(defun pelican-insert-page-header (title &optional hidden)
+(defun pelican-mode-insert-page-header (title &optional hidden)
   "Insert a Pelican header for a page with a TITLE, potentially HIDDEN."
   (interactive
    (list (read-string "Page title: ")
          (y-or-n-p "Hidden? ")))
-  (apply #'pelican-insert-header
+  (apply #'pelican-mode-insert-header
          `(,title ,@pelican-mode-default-page-fields
                   :hidden ,(when hidden "hidden"))))
 
-(defun pelican-insert-auto-header ()
-  "Insert a Pelican header for a page or post."
+(defun pelican-mode-insert-auto-header ()
+  "Insert a Pelican header for a page or article."
   (interactive)
   (call-interactively
-   (if (pelican-page-p)
-       #'pelican-insert-page-header
-     #'pelican-insert-draft-post-header)))
+   (if (pelican-mode-page-p)
+       #'pelican-mode-insert-page-header
+     #'pelican-mode-insert-draft-article-header)))
 
-(defun pelican-set-field (field value)
+(defun pelican-mode-set-field (field value)
   "Set FIELD to VALUE."
   (interactive "sField: \nsValue: ")
   (save-excursion
@@ -145,51 +145,51 @@ the unquoted printed representation of it is used:
     (when (and (derived-mode-p 'rst-mode)
                (re-search-forward "^#" nil t))
       (forward-line 2))
-    (if (re-search-forward (concat "^" (pelican-field field ".+*")) nil t)
-        (replace-match (pelican-field field value))
+    (if (re-search-forward (concat "^" (pelican-mode-field field ".+*")) nil t)
+        (replace-match (pelican-mode-field field value))
       (when value
         (re-search-forward "^$")
-        (replace-match (pelican-field field value))))))
+        (replace-match (pelican-mode-field field value))))))
 
-(defun pelican-remove-field (field)
+(defun pelican-mode-remove-field (field)
   "Remove FIELD."
-  (pelican-set-field field nil))
+  (pelican-mode-set-field field nil))
 
-(defun pelican-set-title (title)
+(defun pelican-mode-set-title (title)
   "Set the title to TITLE."
   (interactive "sTitle: ")
   (if (derived-mode-p 'markdown-mode)
-      (pelican-set-field "title" title)
+      (pelican-mode-set-field "title" title)
     (save-excursion
       (goto-char 0)
-      (let ((header (pelican-rst-title title)))
+      (let ((header (pelican-mode-rst-title title)))
         (if (looking-at ".*\n#+\n+")
             (replace-match header)
           (insert header))))))
 
-(defun pelican-update-date ()
+(defun pelican-mode-update-date ()
   "Update a Pelican date header."
   (interactive)
-  (pelican-set-field :date 'now))
+  (pelican-mode-set-field :date 'now))
 
-(defun pelican-publish-draft ()
-  "Remove draft status from a Pelican post."
+(defun pelican-mode-publish-draft ()
+  "Remove draft status from a Pelican article."
   (interactive)
-  (pelican-remove-field :status)
-  (pelican-update-date))
+  (pelican-mode-remove-field :status)
+  (pelican-mode-update-date))
 
-(defun pelican-page-p ()
-  "Guess the current buffer is a Pelican page (vs. a post or neither)."
-  (when-let (pelican-base (pelican-find-root))
-    (let* ((relative (file-relative-name buffer-file-name pelican-base))
+(defun pelican-mode-page-p ()
+  "Return non-nil the current buffer is a Pelican page."
+  (when-let (pelican-mode-base (pelican-mode-find-root))
+    (let* ((relative (file-relative-name buffer-file-name pelican-mode-base))
            (components (split-string relative "/")))
       (equal "pages" (cadr components)))))
 
-(defun pelican-default-slug ()
-  "Generate a Pelican post/page slug for the current buffer."
-  (if-let ((pelican-base (pelican-find-root))
+(defun pelican-mode-default-slug ()
+  "Generate a Pelican article/page slug for the current buffer."
+  (if-let ((pelican-mode-base (pelican-mode-find-root))
            (file-name (file-name-sans-extension buffer-file-name)))
-      (let* ((relative (file-relative-name file-name pelican-base))
+      (let* ((relative (file-relative-name file-name pelican-mode-base))
              (components (cdr (split-string relative "/")))
              (components (if (string= "pages" (car components))
                              (cdr components) components)))
@@ -200,7 +200,7 @@ the unquoted printed representation of it is used:
               (file-name-directory file-name)))
             (file-name-base file-name))))
 
-(defun pelican-find-in-parents (file-name)
+(defun pelican-mode-find-in-parents (file-name)
   "Find FILE-NAME in the default directory or one of its parents, or nil."
   (let* ((parent (expand-file-name default-directory)))
     (while (and (not (file-readable-p (concat parent file-name)))
@@ -209,19 +209,15 @@ the unquoted printed representation of it is used:
     (let ((found (concat parent file-name)))
       (if (file-readable-p found) found nil))))
 
-(defun pelican-find-root ()
+(defun pelican-mode-find-root ()
   "Return the root of the buffer's Pelican site, or nil."
-  (when-let (conf (pelican-find-in-parents "pelicanconf.py"))
+  (when-let (conf (pelican-mode-find-in-parents "pelicanconf.py"))
     (file-name-directory conf)))
 
-(defun pelican-site-p ()
-  "Check if this buffer is under a Pelican site."
-  (not (null (pelican-find-root))))
-
 (defun pelican-make (target)
   "Execute TARGET in a Makefile at the root of the site."
   (interactive "sMake Pelican target: ")
-  (if-let (default-directory (pelican-find-root))
+  (if-let (default-directory (pelican-mode-find-root))
       (compilation-start (format "make %s" target)
                          nil (lambda (_) "*pelican*"))
     (user-error "This doesn't look like a Pelican site")))
@@ -239,28 +235,37 @@ the unquoted printed representation of it is used:
 ;;;###autoload
 (define-minor-mode pelican-mode
   "Toggle Pelican mode.
+With a prefix argument ARG, enable Pelican mode if ARG is
+positive, and disable it otherwise.  If called from Lisp, enable
+the mode if ARG is omitted or nil.
 
-Interactively with no argument, this command toggles the mode.
-for editing Pelican site files."
+When Pelican mode is enabled, additional commands are available
+for editing articles or pages:
+
+\\{pelican-mode-map}"
   :lighter " Pelican"
   :group 'pelican
-  :keymap `((,(kbd "C-c P n") . pelican-insert-auto-header)
-            (,(kbd "C-c P p") . pelican-publish-draft)
-            (,(kbd "C-c P t") . pelican-update-date)
+  :keymap `((,(kbd "C-c P n") . pelican-mode-insert-auto-header)
+            (,(kbd "C-c P p") . pelican-mode-publish-draft)
+            (,(kbd "C-c P t") . pelican-mode-update-date)
             (,(kbd "C-c P h") . pelican-make-html)
             (,(kbd "C-c P u") . pelican-make-rsync-upload)))
 
 ;;;###autoload
-(defun pelican-enable-if-site ()
-  "Enable `pelican-mode' if this buffer is under a Pelican site."
-  (when (pelican-site-p)
+(defun pelican-mode-enable-if-site ()
+  "Enable `pelican-mode' if this buffer is part of a Pelican site."
+  (when (not (null (pelican-mode-find-root)))
     (pelican-mode 1)))
 
 ;;;###autoload
-(add-hook 'markdown-mode-hook 'pelican-enable-if-site)
+(add-hook 'markdown-mode-hook 'pelican-mode-enable-if-site)
 
 ;;;###autoload
-(add-hook 'rst-mode-hook 'pelican-enable-if-site)
+(add-hook 'rst-mode-hook 'pelican-mode-enable-if-site)
 
 (provide 'pelican-mode)
 ;;; pelican-mode.el ends here
+
+;; Local Variables:
+;; sentence-end-double-space: t
+;; End: