From 00592f59a48d650967bcbc6e35a2985192935416 Mon Sep 17 00:00:00 2001 From: Joe Wreschnig Date: Sun, 6 Aug 2017 12:32:08 +0200 Subject: [PATCH] Standardization spree: MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit - 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. --- pelican-mode.el | 159 +++++++++++++++++++++++++----------------------- 1 file changed, 82 insertions(+), 77 deletions(-) diff --git a/pelican-mode.el b/pelican-mode.el index 3691c2f..dd251d7 100644 --- 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: -- 2.20.1