lisp/muse-blosxom.el

   1 ;;; muse-blosxom.el --- Publish a document tree for serving by (py)Blosxom
   2
   3 ;; Copyright (C) 2004, 2005  Free Software Foundation, Inc.
   4
   5 ;; Date: Wed, 23 March 2005
   6 ;; Author: Michael Olson (mwolson AT gnu DOT org)
   7 ;; Maintainer: Michael Olson (mwolson AT gnu DOT org)
   8
   9 ;; This file is not part of GNU Emacs.
  10
  11 ;; This is free software; you can redistribute it and/or modify it under
  12 ;; the terms of the GNU General Public License as published by the Free
  13 ;; Software Foundation; either version 2, or (at your option) any later
  14 ;; version.
  15 ;;
  16 ;; This is distributed in the hope that it will be useful, but WITHOUT
  17 ;; ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  18 ;; FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  19 ;; for more details.
  20 ;;
  21 ;; You should have received a copy of the GNU General Public License
  22 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  23 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  24 ;; Boston, MA 02110-1301, USA.
  25
  26 ;;; Commentary:
  27
  28 ;; The Blosxom publishing style publishes a tree of categorised files
  29 ;; to a mirrored tree of stories to be served by blosxom.cgi or
  30 ;; pyblosxom.cgi.
  31 ;;
  32 ;; Serving entries with (py)blosxom
  33 ;; --------------------------------
  34 ;;
  35 ;; Each Blosxom file must include `#date yyyy-mm-dd', or optionally
  36 ;; the longer `#date yyyy-mm-dd-hh-mm', a title (using the `#title'
  37 ;; directive) plus whatever normal content is desired.
  38 ;;
  39 ;; The date directive is not used directly by (py)blosxom or this
  40 ;; program.  You need to find two additional items to make use of this
  41 ;; feature.
  42 ;;
  43 ;;  1. A script to gather date directives from the entire blog tree
  44 ;;     into a single file.  The file must associate a blog entry with
  45 ;;     a date.
  46 ;;
  47 ;;  2. A plugin for (py)blosxom that reads this file.
  48 ;;
  49 ;; These 2 things are provided for pyblosxom in the contrib/pyblosxom
  50 ;; subdirectory.  `getstamps.py' provides the 1st service, while
  51 ;; `hardcodedates.py' provides the second service.  Eventually it is
  52 ;; hoped that a blosxom plugin and script will be found/written.
  53 ;;
  54 ;; Generating a project description
  55 ;; --------------------------------
  56 ;;
  57 ;; Muse-blosxom has some helper functions to make specifying
  58 ;; muse-blosxom projects a lot easier.  An example follows.
  59 ;;
  60 ;; (setq muse-project-alist
  61 ;;       `(("blog"
  62 ;;          (,@(muse-blosxom-project-alist-dirs "~/path/to/blog-entries")
  63 ;;           :default "index")
  64 ;;          ,@(muse-blosxom-project-alist-entry "~/path/to/blog-entries"
  65 ;;                                              "~/public_html/blog"
  66 ;;                                              "blosxom-xhtml")
  67 ;;         )))
  68 ;;
  69 ;; Note that we need a backtick instead of a single quote on the
  70 ;; second line of this example.
  71 ;;
  72 ;; Creating new blog entries
  73 ;; -------------------------
  74 ;;
  75 ;; There is a function called `muse-blosxom-new-entry' that will
  76 ;; automate the process of making a new blog entry.  To make use of
  77 ;; it, do the following.
  78 ;;
  79 ;;  - Customize `muse-blosxom-base-directory' to the location that
  80 ;;    your blog entries are stored.
  81 ;;
  82 ;;  - Assign the `muse-blosxom-new-entry' function to a key sequence.
  83 ;;    I use the following code to assign this function to `C-c p l'.
  84 ;;
  85 ;;    (global-set-key "\C-cpl" 'muse-blosxom-new-entry)
  86 ;;
  87 ;;  - You should create your directory structure ahead of time under
  88 ;;    your base directory.  These directories, which correspond with
  89 ;;    category names, may be nested.
  90 ;;
  91 ;;  - When you enter this key sequence, you will be prompted for the
  92 ;;    category of your entry and its title.  Upon entering this
  93 ;;    information, a new file will be created that corresponds with
  94 ;;    the title, but in lowercase letters and having special
  95 ;;    characters converted to underscores.  The title and date
  96 ;;    directives will be inserted automatically.
  97
  98 ;;; Contributors:
  99
 100 ;; Gary Vaughan (gary AT gnu DOT org) is the original author of
 101 ;; `emacs-wiki-blosxom.el', which is the ancestor of this file.
 102 ;;
 103 ;; Brad Collins (brad AT chenla DOT org) ported this file to Muse.
 104 ;;
 105 ;; Michael Olson (mwolson AT gnu DOT org) further adapted this file to
 106 ;; Muse and continues to maintain it.
 107 ;;
 108 ;; Björn Lindström (bkhl AT elektrubadur DOT se) made many valuable
 109 ;; suggestions.
 110
 111 ;;; Code:
 112
 113 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 114 ;;
 115 ;; Muse Blosxom Publishing
 116 ;;
 117 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 118
 119 (require 'muse-project)
 120 (require 'muse-publish)
 121 (require 'muse-html)
 122
 123 (defgroup muse-blosxom nil
 124   "Options controlling the behavior of Muse Blosxom publishing.
 125 See `muse-blosxom' for more information."
 126   :group 'muse-publish)
 127
 128 (defcustom muse-blosxom-extension ".txt"
 129   "Default file extension for publishing Blosxom files."
 130   :type 'string
 131   :group 'muse-blosxom)
 132
 133 (defcustom muse-blosxom-header
 134   "<lisp>(muse-publishing-directive \"title\")</lisp>\n"
 135   "Header used for publishing Blosxom files.  This may be text or a filename."
 136   :type 'string
 137   :group 'muse-blosxom)
 138
 139 (defcustom muse-blosxom-footer ""
 140   "Footer used for publishing Blosxom files.  This may be text or a filename."
 141   :type 'string
 142   :group 'muse-blosxom)
 143
 144 (defcustom muse-blosxom-base-directory "~/Blog"
 145   "Base directory of blog entries.
 146 This is the top-level directory where your Muse blog entries may be found."
 147   :type 'directory
 148   :group 'muse-blosxom)
 149
 150 ;; Maintain (published-file . date) alist, which will later be written
 151 ;; to a timestamps file; not implemented yet.
 152
 153 (defvar muse-blosxom-page-date-alist nil)
 154
 155 (defun muse-blosxom-update-page-date-alist ()
 156   "Add a date entry to `muse-blosxom-page-date-alist' for this page."
 157   ;; Make current file be relative to base directory
 158   (let ((rel-file
 159          (concat
 160           (file-name-as-directory
 161            (or (muse-publishing-directive "category")
 162                (file-relative-name
 163                 (file-name-directory
 164                  (expand-file-name muse-publishing-current-file))
 165                 (file-truename muse-blosxom-base-directory))))
 166           (file-name-nondirectory muse-publishing-current-file))))
 167     ;; Strip the file extension
 168     (when muse-ignored-extensions-regexp
 169       (setq rel-file (save-match-data
 170                        (and (string-match muse-ignored-extensions-regexp
 171                                           rel-file)
 172                             (replace-match "" t t rel-file)))))
 173     ;; Add to page-date alist
 174     (add-to-list
 175      'muse-blosxom-page-date-alist
 176      `(,rel-file . ,(muse-publishing-directive "date")))))
 177
 178 ;; Enter a new blog entry
 179
 180 (defun muse-blosxom-get-categories (&optional base)
 181   "Retrieve all of the categories from a Blosxom project.
 182 The base directory is specified by BASE, and defaults to
 183 `muse-blosxom-base-directory'.
 184
 185 Directories starting with \".\" will be ignored."
 186   (unless base (setq base muse-blosxom-base-directory))
 187   (when (and (file-directory-p base)
 188              (not (string-match muse-project-ignore-regexp base)))
 189     (let (list dir)
 190       (dolist (file (directory-files base t "^[^.]"))
 191         (when (and (file-directory-p file)
 192                    (not (string-match muse-project-ignore-regexp file)))
 193           (setq dir (file-name-nondirectory file))
 194           (push dir list)
 195           (nconc list (mapcar #'(lambda (item)
 196                                   (concat dir "/" item))
 197                               (muse-blosxom-get-categories file)))))
 198       list)))
 199
 200 (defun muse-blosxom-title-to-file (title)
 201   "Derive a file name from the given TITLE.
 202
 203 Feel free to overwrite this if you have a different concept of what
 204 should be allowed in a filename."
 205   (muse-replace-regexp-in-string (concat "[^-." muse-regexp-alnum "]")
 206                                  "_" (downcase title)))
 207
 208 (defun muse-blosxom-new-entry (category title)
 209   "Start a new blog entry with given CATEGORY.
 210 The filename of the blog entry is derived from TITLE.
 211 The page will be initialized with the current date and TITLE."
 212   (interactive
 213    (list
 214     (completing-read "Category: "
 215                      (mapcar 'list (muse-blosxom-get-categories)))
 216     (read-string "Title: ")))
 217   (let ((file (muse-blosxom-title-to-file title)))
 218     (muse-project-find-file
 219      file "blosxom" nil
 220      (concat (directory-file-name muse-blosxom-base-directory)
 221              "/" category)))
 222   (goto-char (point-min))
 223   (insert "#date " (format-time-string "%4Y-%2m-%2d-%2H-%2M")
 224           "\n#category " category
 225           "\n#title " title
 226           "\n\n")
 227   (forward-line 2))
 228
 229 ;; Make it easier to specify the muse-project-alist entry
 230
 231 (defun muse-blosxom-project-alist-entry (entry-dir output-dir style)
 232   "Return a list of styles to use when publishing a muse-blosxom project.
 233 ENTRY-DIR is where your Muse blog entries are kept.
 234 OUTPUT-DIR is where these entries are published.
 235 STYLE is the publishing style to use.
 236
 237 For an example of the use of this function, see
 238 `examples/mwolson/muse-init.el' from the Muse distribution."
 239   (cons `(:base ,style :path ,(expand-file-name output-dir)
 240                 :include ,(concat "/" (file-name-nondirectory entry-dir)
 241                                   "/[^/]+$"))
 242         (mapcar (lambda (dir);
 243                   `(:base ,style
 244                           :path ,(expand-file-name dir output-dir)
 245                           :include ,(concat "/" dir "/")))
 246                 (muse-blosxom-get-categories entry-dir))))
 247
 248 (defun muse-blosxom-project-alist-dirs (entry-dir)
 249   "Return a list of directories to use when publishing a muse-blosxom project.
 250 ENTRY-DIR is where your Muse blog entries are kept.
 251
 252 For an example of the use of this function, see
 253 `examples/mwolson/muse-init.el' from the Muse distribution."
 254   (cons (expand-file-name entry-dir)
 255         (mapcar (lambda (dir) (expand-file-name dir entry-dir))
 256                 (muse-blosxom-get-categories entry-dir))))
 257
 258 ;; Register the Blosxom Publisher
 259
 260 (unless (assoc "blosxom-html" muse-publishing-styles)
 261   (muse-derive-style "blosxom-html" "html"
 262                      :suffix    'muse-blosxom-extension
 263                      :header    'muse-blosxom-header
 264                      :footer    'muse-blosxom-footer
 265                      :after     'muse-blosxom-update-page-date-alist)
 266
 267   (muse-derive-style "blosxom-xhtml" "xhtml"
 268                      :suffix    'muse-blosxom-extension
 269                      :header    'muse-blosxom-header
 270                      :footer    'muse-blosxom-footer
 271                      :after     'muse-blosxom-update-page-date-alist))
 272
 273 (provide 'muse-blosxom)
 274
 275 ;;; muse-blosxom.el ends here