Fix build failure for muse-ikiwiki.
[muse-el.git] / lisp / muse-blosxom.el
blob78038d703e1e30bb7e4163ba8a72ee1eccb78a99
1 ;;; muse-blosxom.el --- publish a document tree for serving by (py)Blosxom
3 ;; Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009, 2010
4 ;; Free Software Foundation, Inc.
6 ;; Author: Michael Olson <mwolson@gnu.org>
7 ;; Date: Wed, 23 March 2005
9 ;; This file is part of Emacs Muse. It is not part of GNU Emacs.
11 ;; Emacs Muse is free software; you can redistribute it and/or modify
12 ;; it under the terms of the GNU General Public License as published
13 ;; by the Free Software Foundation; either version 3, or (at your
14 ;; option) any later version.
16 ;; Emacs Muse is distributed in the hope that it will be useful, but
17 ;; WITHOUT ANY WARRANTY; without even the implied warranty of
18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 ;; General Public License for more details.
21 ;; You should have received a copy of the GNU General Public License
22 ;; along with Emacs Muse; 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.
26 ;;; Commentary:
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.
32 ;; Serving entries with (py)blosxom
33 ;; --------------------------------
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.
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.
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.
47 ;; 2. A plugin for (py)blosxom that reads this file.
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.
54 ;; Alternately, the pyblosxom metadate plugin may be used. On the
55 ;; plus side, there is no need to run a script to gather the date. On
56 ;; the downside, each entry is read twice rather than once when the
57 ;; page is rendered. Set the value of muse-blosxom-use-metadate to
58 ;; non-nil to enable adding a #postdate directive to all published
59 ;; files. You can do this by:
61 ;; M-x customize-variable RET muse-blosxom-use-metadate RET
63 ;; With the metadate plugin installed in pyblosxom, the date set in
64 ;; this directive will be used instead of the file's modification
65 ;; time. The plugin is included with Muse at
66 ;; contrib/pyblosxom/metadate.py.
68 ;; Generating a Muse project entry
69 ;; -------------------------------
71 ;; Muse-blosxom has some helper functions to make specifying
72 ;; muse-blosxom projects a lot easier. An example follows.
74 ;; (setq muse-project-alist
75 ;; `(("blog"
76 ;; (,@(muse-project-alist-dirs "~/path/to/blog-entries")
77 ;; :default "index")
78 ;; ,@(muse-project-alist-styles "~/path/to/blog-entries"
79 ;; "~/public_html/blog"
80 ;; "blosxom-xhtml")
81 ;; )))
83 ;; Note that we need a backtick instead of a single quote on the
84 ;; second line of this example.
86 ;; Creating new blog entries
87 ;; -------------------------
89 ;; There is a function called `muse-blosxom-new-entry' that will
90 ;; automate the process of making a new blog entry. To make use of
91 ;; it, do the following.
93 ;; - Customize `muse-blosxom-base-directory' to the location that
94 ;; your blog entries are stored.
96 ;; - Assign the `muse-blosxom-new-entry' function to a key sequence.
97 ;; I use the following code to assign this function to `C-c p l'.
99 ;; (global-set-key "\C-cpl" 'muse-blosxom-new-entry)
101 ;; - You should create your directory structure ahead of time under
102 ;; your base directory. These directories, which correspond with
103 ;; category names, may be nested.
105 ;; - When you enter this key sequence, you will be prompted for the
106 ;; category of your entry and its title. Upon entering this
107 ;; information, a new file will be created that corresponds with
108 ;; the title, but in lowercase letters and having special
109 ;; characters converted to underscores. The title and date
110 ;; directives will be inserted automatically.
112 ;; Using tags
113 ;; ----------
115 ;; If you wish to keep all of your blog entries in one directory and
116 ;; use tags to classify your entries, set `muse-blosxom-use-tags' to
117 ;; non-nil.
119 ;; For this to work, you will need to be using the PyBlosxom plugin at
120 ;; http://pyblosxom.sourceforge.net/blog/registry/meta/Tags.
122 ;;; Contributors:
124 ;; Gary Vaughan (gary AT gnu DOT org) is the original author of
125 ;; `emacs-wiki-blosxom.el', which is the ancestor of this file.
127 ;; Brad Collins (brad AT chenla DOT org) ported this file to Muse.
129 ;; Björn Lindström (bkhl AT elektrubadur DOT se) made many valuable
130 ;; suggestions.
132 ;; Sasha Kovar (sasha AT arcocene DOT org) fixed
133 ;; muse-blosxom-new-entry when using tags and also implemented support
134 ;; for the #postdate directive.
136 ;;; Code:
138 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
140 ;; Muse Blosxom Publishing
142 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
144 (require 'muse-project)
145 (require 'muse-publish)
146 (require 'muse-html)
148 (defgroup muse-blosxom nil
149 "Options controlling the behavior of Muse Blosxom publishing.
150 See `muse-blosxom' for more information."
151 :group 'muse-publish)
153 (defcustom muse-blosxom-extension ".txt"
154 "Default file extension for publishing Blosxom files."
155 :type 'string
156 :group 'muse-blosxom)
158 (defcustom muse-blosxom-header
159 "<lisp>(concat (muse-publishing-directive \"title\") \"\\n\"
160 (when muse-blosxom-use-metadate
161 (let ((date (muse-publishing-directive \"date\")))
162 (when date (concat \"#postdate \"
163 (muse-blosxom-format-date date) \"\\n\"))))
164 (when muse-blosxom-use-tags
165 (let ((tags (muse-publishing-directive \"tags\")))
166 (when tags (concat \"#tags \" tags \"\\n\")))))</lisp>"
167 "Header used for publishing Blosxom files. This may be text or a filename."
168 :type 'string
169 :group 'muse-blosxom)
171 (defcustom muse-blosxom-footer ""
172 "Footer used for publishing Blosxom files. This may be text or a filename."
173 :type 'string
174 :group 'muse-blosxom)
176 (defcustom muse-blosxom-base-directory "~/Blog"
177 "Base directory of blog entries.
178 This is the top-level directory where your Muse blog entries may be found."
179 :type 'directory
180 :group 'muse-blosxom)
182 (defcustom muse-blosxom-use-tags nil
183 "Determine whether or not to enable use of the #tags directive.
185 If you wish to keep all of your blog entries in one directory and
186 use tags to classify your entries, set `muse-blosxom-use-tags' to
187 non-nil.
189 For this to work, you will need to be using the PyBlosxom plugin
190 at http://pyblosxom.sourceforge.net/blog/registry/meta/Tags."
191 :type 'boolean
192 :group 'muse-blosxom)
194 (defcustom muse-blosxom-use-metadate nil
195 "Determine whether or not to use the #postdate directive.
197 If non-nil, published entries include the original date (as specified
198 in the muse #date line) which can be read by the metadate PyBlosxom
199 plugin.
201 For this to work, you will need to be using the PyBlosxom plugin
202 at http://pyblosxom.sourceforge.net/blog/registry/date/metadate."
203 :type 'boolean
204 :group 'muse-blosxom)
206 ;; Maintain (published-file . date) alist, which will later be written
207 ;; to a timestamps file; not implemented yet.
209 (defvar muse-blosxom-page-date-alist nil)
211 (defun muse-blosxom-update-page-date-alist ()
212 "Add a date entry to `muse-blosxom-page-date-alist' for this page."
213 (when muse-publishing-current-file
214 ;; Make current file be relative to base directory
215 (let ((rel-file
216 (concat
217 (file-name-as-directory
218 (or (muse-publishing-directive "category")
219 (file-relative-name
220 (file-name-directory
221 (expand-file-name muse-publishing-current-file))
222 (file-truename muse-blosxom-base-directory))))
223 (file-name-nondirectory muse-publishing-current-file))))
224 ;; Strip the file extension
225 (when muse-ignored-extensions-regexp
226 (setq rel-file (save-match-data
227 (and (string-match muse-ignored-extensions-regexp
228 rel-file)
229 (replace-match "" t t rel-file)))))
230 ;; Add to page-date alist
231 (add-to-list
232 'muse-blosxom-page-date-alist
233 `(,rel-file . ,(muse-publishing-directive "date"))))))
235 ;; Enter a new blog entry
237 (defun muse-blosxom-title-to-file (title)
238 "Derive a file name from the given TITLE.
240 Feel free to overwrite this if you have a different concept of what
241 should be allowed in a filename."
242 (muse-replace-regexp-in-string (concat "[^-." muse-regexp-alnum "]")
243 "_" (downcase title)))
245 (defun muse-blosxom-format-date (date)
246 "Convert a date string to PyBlosxom metadate plugin format."
247 (apply #'format "%s-%s-%s %s:%s" (split-string date "-")))
249 ;;;###autoload
250 (defun muse-blosxom-new-entry (category title)
251 "Start a new blog entry with given CATEGORY.
252 The filename of the blog entry is derived from TITLE.
253 The page will be initialized with the current date and TITLE."
254 (interactive
255 (list
256 (if muse-blosxom-use-tags
257 (let ((tag "foo")
258 (tags nil))
259 (while (progn (setq tag (read-string "Tag (RET to continue): "))
260 (not (string= tag "")))
261 (add-to-list 'tags tag t))
262 tags)
263 (funcall muse-completing-read-function
264 "Category: "
265 (mapcar 'list (muse-project-recurse-directory
266 muse-blosxom-base-directory))))
267 (read-string "Title: ")))
268 (let ((file (muse-blosxom-title-to-file title)))
269 (muse-project-find-file
270 file "blosxom" nil
271 (if muse-blosxom-use-tags
272 (directory-file-name muse-blosxom-base-directory)
273 (concat (directory-file-name muse-blosxom-base-directory)
274 "/" category))))
275 (goto-char (point-min))
276 (insert "#date " (format-time-string "%Y-%m-%d-%H-%M")
277 "\n#title " title)
278 (if muse-blosxom-use-tags
279 (if (> (length category) 0)
280 (insert (concat "\n#tags " (mapconcat #'identity category ","))))
281 (unless (string= category "")
282 (insert (concat "\n#category " category))))
283 (insert "\n\n")
284 (forward-line 2))
286 ;;; Register the Muse Blosxom Publisher
288 (muse-derive-style "blosxom-html" "html"
289 :suffix 'muse-blosxom-extension
290 :link-suffix 'muse-html-extension
291 :header 'muse-blosxom-header
292 :footer 'muse-blosxom-footer
293 :after 'muse-blosxom-update-page-date-alist
294 :browser 'find-file)
296 (muse-derive-style "blosxom-xhtml" "xhtml"
297 :suffix 'muse-blosxom-extension
298 :link-suffix 'muse-xhtml-extension
299 :header 'muse-blosxom-header
300 :footer 'muse-blosxom-footer
301 :after 'muse-blosxom-update-page-date-alist
302 :browser 'find-file)
304 (provide 'muse-blosxom)
306 ;;; muse-blosxom.el ends here