Explain what Pelican is.

[pelican-mode.git] / pelican-mode.el

diff --git a/pelican-mode.el b/pelican-mode.el
index 7f7460b..f87e73e 100644 (file)
--- a/pelican-mode.el
+++ b/pelican-mode.el
@@ -20,11 +20,24 @@
 ;; You should have received a copy of the GNU General Public License
 ;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+
 ;;; Commentary:
 ;;
-;; Probably, this doesn't handle a lot of error cases.  I also never
-;; tested it on networked drives and the lookup for pelicanconf.py
-;; might slow it down considerably.
+;; pelican-mode is an Emacs minor mode for editing pages and posts in
+;; Pelican sites.  Pelican is a static site generator which can
+;; process a variety of text file formats.  For more information, see
+;; URL https://blog.getpelican.com/.
+;;
+;; It's intended to be used alongside `markdown-mode' or `rst-mode'.
+;; It also assumes you've set up Pelican with ``pelican-quickstart''
+;; or something like it.  In particular it assumes:
+;;
+;;  * The existence of ``pelicanconf.py'' and ``Makefile'' in some
+;;    ancestor directory.
+;;  * The first component of the path (e.g. ``content'') after that
+;;    ancestor is irrelevant.
+;;  * If the next component is ``pages'', that indicates a page
+;;    rather than an article.
 
 
 ;;; Code:
@@ -33,7 +46,9 @@
 (require 'subr-x)
 
 (defgroup pelican-mode nil
-  "Support for Pelican articles and pages."
+  "Support for Pelican articles and pages.
+
+For more information about Pelican see URL https://blog.getpelican.com/."
   :group 'convenience)
 
 (defcustom pelican-mode-default-page-fields
@@ -196,19 +211,9 @@ the unquoted printed representation of it is used:
     (when-let (file-name (file-name-sans-extension buffer-file-name))
       (file-name-base 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)))
-                (not (string= parent (directory-file-name parent))))
-      (setq parent (file-name-directory (directory-file-name parent))))
-    (let ((found (concat parent file-name)))
-      (if (file-readable-p found) found nil))))
-
 (defun pelican-mode-find-root ()
   "Return the root of the buffer's Pelican site, or nil."
-  (when-let (conf (pelican-mode-find-in-parents "pelicanconf.py"))
-    (file-name-directory conf)))
+  (locate-dominating-file default-directory "pelicanconf.py"))
 
 (defun pelican-make (target)
   "Execute TARGET in a Makefile at the root of the site."
@@ -235,6 +240,10 @@ 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.
 
+Pelican is a static site generator which can process a variety of
+text file formats.  For more information, see URL
+https://blog.getpelican.com/.
+
 When Pelican mode is enabled, additional commands are available
 for editing articles or pages:
 
@@ -253,6 +262,10 @@ With a prefix argument ARG, enable Pelican global mode if ARG is
 positive, and disable it otherwise.  If called from Lisp, enable
 the mode if ARG is omitted or nil.
 
+Pelican is a static site generator which can process a variety of
+text file formats.  For more information, see URL
+https://blog.getpelican.com/.
+
 When Pelican global mode is enabled, text files which seem to
 be part of a Pelican site will have `pelican-mode' automatically
 enabled.