1 ;;; org-e-publish.el --- publish related org-mode files as a website
2 ;; Copyright (C) 2006-2012 Free Software Foundation, Inc.
4 ;; Author: David O'Toole <dto@gnu.org>
5 ;; Maintainer: Carsten Dominik <carsten DOT dominik AT gmail DOT com>
6 ;; Keywords: hypermedia, outlines, wp
8 ;; This file is not part of GNU Emacs.
10 ;; GNU Emacs is free software: you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation, either version 3 of the License, or
13 ;; (at your option) any later version.
15 ;; GNU Emacs is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 ;; GNU General Public License for more details.
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
25 ;; This program allow configurable publishing of related sets of
26 ;; Org mode files as a complete website.
28 ;; org-e-publish.el can do the following:
30 ;; + Publish all one's Org files to HTML or PDF
31 ;; + Upload HTML, images, attachments and other files to a web server
32 ;; + Exclude selected private pages from publishing
33 ;; + Publish a clickable sitemap of pages
34 ;; + Manage local timestamps for publishing only changed files
35 ;; + Accept plugin functions to extend range of publishable content
37 ;; Documentation for publishing is in the manual.
41 (eval-when-compile (require 'cl
))
42 (require 'format-spec
)
45 (declare-function org-e-latex-compile
"org-e-latex" (texfile))
50 (defvar org-e-publish-initial-buffer nil
51 "The buffer `org-e-publish' has been called from.")
53 (defvar org-e-publish-temp-files nil
54 "Temporary list of files to be published.")
56 ;; Here, so you find the variable right before it's used the first time:
57 (defvar org-e-publish-cache nil
58 "This will cache timestamps and titles for files in publishing projects.
59 Blocks could hash sha1 values here.")
61 (defgroup org-e-publish nil
62 "Options for publishing a set of Org-mode and related files."
66 (defcustom org-e-publish-project-alist nil
67 "Association list to control publishing behavior.
68 Each element of the alist is a publishing 'project.' The CAR of
69 each element is a string, uniquely identifying the project. The
70 CDR of each element is in one of the following forms:
72 1. A well-formed property list with an even number of elements,
73 alternating keys and values, specifying parameters for the
76 \(:property value :property value ... )
78 2. A meta-project definition, specifying of a list of
81 \(:components \(\"project-1\" \"project-2\" ...))
83 When the CDR of an element of org-e-publish-project-alist is in
84 this second form, the elements of the list after `:components'
85 are taken to be components of the project, which group together
86 files requiring different publishing options. When you publish
87 such a project with \\[org-e-publish], the components all
90 When a property is given a value in
91 `org-e-publish-project-alist', its setting overrides the value of
92 the corresponding user variable \(if any) during publishing.
93 However, options set within a file override everything.
95 Most properties are optional, but some should always be set:
99 Directory containing publishing source files.
103 Extension \(without the dot!) of source files. This can be
104 a regular expression. If not given, \"org\" will be used as
107 `:publishing-directory'
109 Directory \(possibly remote) where output files will be
112 The `:exclude' property may be used to prevent certain files from
113 being published. Its value may be a string or regexp matching
114 file names you don't want to be published.
116 The `:include' property may be used to include extra files. Its
117 value may be a list of filenames to include. The filenames are
118 considered relative to the base directory.
120 When both `:include' and `:exclude' properties are given values,
121 the exclusion step happens first.
123 One special property controls which back-end function to use for
124 publishing files in the project. This can be used to extend the
125 set of file types publishable by `org-e-publish', as well as the
126 set of output formats.
128 `:publishing-function'
130 Function to publish file. The default is
131 `org-e-publish-org-to-ascii', but other values are possible.
132 May also be a list of functions, in which case each function
133 in the list is invoked in turn.
135 Another property allows you to insert code that prepares
136 a project for publishing. For example, you could call GNU Make
137 on a certain makefile, to ensure published files are built up to
140 `:preparation-function'
142 Function to be called before publishing this project. This
143 may also be a list of functions.
145 `:completion-function'
147 Function to be called after publishing this project. This
148 may also be a list of functions.
150 Some properties control details of the Org publishing process,
151 and are equivalent to the corresponding user variables listed in
152 the right column. Back-end specific properties may also be
153 included. See the back-end documentation for more information.
155 :author `user-full-name'
156 :creator `org-export-creator-string'
157 :email `user-mail-address'
158 :exclude-tags `org-export-exclude-tags'
159 :headline-levels `org-export-headline-levels'
160 :language `org-export-default-language'
161 :preserve-breaks `org-export-preserve-breaks'
162 :section-numbers `org-export-with-section-numbers'
163 :select-tags `org-export-select-tags'
164 :time-stamp-file `org-export-time-stamp-file'
165 :with-archived-trees `org-export-with-archived-trees'
166 :with-author `org-export-with-author'
167 :with-creator `org-export-with-creator'
168 :with-drawers `org-export-with-drawers'
169 :with-email `org-export-with-email'
170 :with-emphasize `org-export-with-emphasize'
171 :with-entities `org-export-with-entities'
172 :with-fixed-width `org-export-with-fixed-width'
173 :with-footnotes `org-export-with-footnotes'
174 :with-priority `org-export-with-priority'
175 :with-special-strings `org-export-with-special-strings'
176 :with-sub-superscript `org-export-with-sub-superscripts'
177 :with-toc `org-export-with-toc'
178 :with-tables `org-export-with-tables'
179 :with-tags `org-export-with-tags'
180 :with-tasks `org-export-with-tasks'
181 :with-timestamps `org-export-with-timestamps'
182 :with-todo-keywords `org-export-with-todo-keywords'
184 The following properties may be used to control publishing of
185 a site-map of files or summary page for a given project.
189 Whether to publish a site-map during
190 `org-e-publish-current-project' or `org-e-publish-all'.
194 Filename for output of sitemap. Defaults to \"sitemap.org\".
198 Title of site-map page. Defaults to name of file.
202 Plugin function to use for generation of site-map. Defaults to
203 `org-e-publish-org-sitemap', which generates a plain list of
204 links to all files in the project.
208 Can be `list' \(site-map is just an itemized list of the
209 titles of the files involved) or `tree' \(the directory
210 structure of the source files is reflected in the site-map).
213 `:sitemap-sans-extension'
215 Remove extension from site-map's file-names. Useful to have
216 cool URIs \(see http://www.w3.org/Provider/Style/URI).
219 If you create a site-map file, adjust the sorting like this:
221 `:sitemap-sort-folders'
223 Where folders should appear in the site-map. Set this to
224 `first' \(default) or `last' to display folders first or
225 last, respectively. Any other value will mix files and
228 `:sitemap-sort-files'
230 The site map is normally sorted alphabetically. You can
231 change this behaviour setting this to `anti-chronologically',
232 `chronologically', or nil.
234 `:sitemap-ignore-case'
236 Should sorting be case-sensitive? Default nil.
238 The following properties control the creation of a concept index.
242 Create a concept index.
244 Other properties affecting publication.
248 Set this to t to publish only the body of the documents."
249 :group
'org-e-publish
252 (defcustom org-e-publish-use-timestamps-flag t
253 "Non-nil means use timestamp checking to publish only changed files.
254 When nil, do no timestamp checking and always publish all files."
255 :group
'org-e-publish
258 (defcustom org-e-publish-timestamp-directory
259 (convert-standard-filename "~/.org-timestamps/")
260 "Name of directory in which to store publishing timestamps."
261 :group
'org-e-publish
264 (defcustom org-e-publish-list-skipped-files t
265 "Non-nil means show message about files *not* published."
266 :group
'org-e-publish
269 (defcustom org-e-publish-sitemap-sort-files
'alphabetically
270 "Method to sort files in site-maps.
271 Possible values are `alphabetically', `chronologically',
272 `anti-chronologically' and nil.
274 If `alphabetically', files will be sorted alphabetically. If
275 `chronologically', files will be sorted with older modification
276 time first. If `anti-chronologically', files will be sorted with
277 newer modification time first. nil won't sort files.
279 You can overwrite this default per project in your
280 `org-e-publish-project-alist', using `:sitemap-sort-files'."
281 :group
'org-e-publish
284 (defcustom org-e-publish-sitemap-sort-folders
'first
285 "A symbol, denoting if folders are sorted first in sitemaps.
286 Possible values are `first', `last', and nil.
287 If `first', folders will be sorted before files.
288 If `last', folders are sorted to the end after the files.
289 Any other value will not mix files and folders.
291 You can overwrite this default per project in your
292 `org-e-publish-project-alist', using `:sitemap-sort-folders'."
293 :group
'org-e-publish
296 (defcustom org-e-publish-sitemap-sort-ignore-case nil
297 "Non-nil when site-map sorting should ignore case.
299 You can overwrite this default per project in your
300 `org-e-publish-project-alist', using `:sitemap-ignore-case'."
301 :group
'org-e-publish
304 (defcustom org-e-publish-sitemap-date-format
"%Y-%m-%d"
305 "Format for `format-time-string' which is used to print a date
307 :group
'org-e-publish
310 (defcustom org-e-publish-sitemap-file-entry-format
"%t"
311 "Format string for site-map file entry.
312 You could use brackets to delimit on what part the link will be.
316 %d is the date formatted using `org-e-publish-sitemap-date-format'."
317 :group
'org-e-publish
322 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
323 ;;; Timestamp-related functions
325 (defun org-e-publish-timestamp-filename (filename &optional pub-dir pub-func
)
326 "Return path to timestamp file for filename FILENAME."
327 (setq filename
(concat filename
"::" (or pub-dir
"") "::"
328 (format "%s" (or pub-func
""))))
329 (concat "X" (if (fboundp 'sha1
) (sha1 filename
) (md5 filename
))))
331 (defun org-e-publish-needed-p
332 (filename &optional pub-dir pub-func true-pub-dir base-dir
)
333 "Non-nil if FILENAME should be published in PUB-DIR using PUB-FUNC.
334 TRUE-PUB-DIR is where the file will truly end up. Currently we
335 are not using this - maybe it can eventually be used to check if
336 the file is present at the target location, and how old it is.
337 Right now we cannot do this, because we do not know under what
338 file name the file will be stored - the publishing function can
339 still decide about that independently."
340 (let ((rtn (if (not org-e-publish-use-timestamps-flag
) t
341 (org-e-publish-cache-file-needs-publishing
342 filename pub-dir pub-func base-dir
))))
343 (if rtn
(message "Publishing file %s using `%s'" filename pub-func
)
344 (when org-e-publish-list-skipped-files
345 (message "Skipping unmodified file %s" filename
)))
348 (defun org-e-publish-update-timestamp
349 (filename &optional pub-dir pub-func base-dir
)
350 "Update publishing timestamp for file FILENAME.
351 If there is no timestamp, create one."
352 (let ((key (org-e-publish-timestamp-filename filename pub-dir pub-func
))
353 (stamp (org-e-publish-cache-ctime-of-src filename
)))
354 (org-e-publish-cache-set key stamp
)))
356 (defun org-e-publish-remove-all-timestamps ()
357 "Remove all files in the timestamp directory."
358 (let ((dir org-e-publish-timestamp-directory
)
360 (when (and (file-exists-p dir
) (file-directory-p dir
))
361 (mapc 'delete-file
(directory-files dir
'full
"[^.]\\'"))
362 (org-e-publish-reset-cache))))
366 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
367 ;;; Getting project information out of `org-e-publish-project-alist'
369 (defun org-e-publish-expand-projects (projects-alist)
370 "Expand projects in PROJECTS-ALIST.
371 This splices all the components into the list."
372 (let ((rest projects-alist
) rtn p components
)
373 (while (setq p
(pop rest
))
374 (if (setq components
(plist-get (cdr p
) :components
))
376 (mapcar (lambda (x) (assoc x org-e-publish-project-alist
))
380 (nreverse (delete-dups (delq nil rtn
)))))
382 (defvar org-sitemap-sort-files
)
383 (defvar org-sitemap-sort-folders
)
384 (defvar org-sitemap-ignore-case
)
385 (defvar org-sitemap-requested
)
386 (defvar org-sitemap-date-format
)
387 (defvar org-sitemap-file-entry-format
)
388 (defun org-e-publish-compare-directory-files (a b
)
389 "Predicate for `sort', that sorts folders and files for sitemap."
391 (when (or org-sitemap-sort-files org-sitemap-sort-folders
)
392 ;; First we sort files:
393 (when org-sitemap-sort-files
394 (case org-sitemap-sort-files
396 (let* ((adir (file-directory-p a
))
397 (aorg (and (string-match "\\.org$" a
) (not adir
)))
398 (bdir (file-directory-p b
))
399 (borg (and (string-match "\\.org$" b
) (not bdir
)))
400 (A (if aorg
(concat (file-name-directory a
)
401 (org-e-publish-find-title a
)) a
))
402 (B (if borg
(concat (file-name-directory b
)
403 (org-e-publish-find-title b
)) b
)))
404 (setq retval
(if org-sitemap-ignore-case
405 (not (string-lessp (upcase B
) (upcase A
)))
406 (not (string-lessp B A
))))))
407 ((anti-chronologically chronologically
)
408 (let* ((adate (org-e-publish-find-date a
))
409 (bdate (org-e-publish-find-date b
))
410 (A (+ (lsh (car adate
) 16) (cadr adate
)))
411 (B (+ (lsh (car bdate
) 16) (cadr bdate
))))
413 (if (eq org-sitemap-sort-files
'chronologically
) (<= A B
)
415 ;; Directory-wise wins:
416 (when org-sitemap-sort-folders
417 ;; a is directory, b not:
419 ((and (file-directory-p a
) (not (file-directory-p b
)))
420 (setq retval
(equal org-sitemap-sort-folders
'first
)))
421 ;; a is not a directory, but b is:
422 ((and (not (file-directory-p a
)) (file-directory-p b
))
423 (setq retval
(equal org-sitemap-sort-folders
'last
))))))
426 (defun org-e-publish-get-base-files-1
427 (base-dir &optional recurse match skip-file skip-dir
)
428 "Set `org-e-publish-temp-files' with files from BASE-DIR directory.
429 If RECURSE is non-nil, check BASE-DIR recursively. If MATCH is
430 non-nil, restrict this list to the files matching the regexp
431 MATCH. If SKIP-FILE is non-nil, skip file matching the regexp
432 SKIP-FILE. If SKIP-DIR is non-nil, don't check directories
433 matching the regexp SKIP-DIR when recursing through BASE-DIR."
435 (let ((fd-p (file-directory-p f
))
436 (fnd (file-name-nondirectory f
)))
437 (if (and fd-p recurse
438 (not (string-match "^\\.+$" fnd
))
439 (if skip-dir
(not (string-match skip-dir fnd
)) t
))
440 (org-e-publish-get-base-files-1
441 f recurse match skip-file skip-dir
)
442 (unless (or fd-p
;; this is a directory
443 (and skip-file
(string-match skip-file fnd
))
444 (not (file-exists-p (file-truename f
)))
445 (not (string-match match fnd
)))
447 (pushnew f org-e-publish-temp-files
)))))
448 (if org-sitemap-requested
449 (sort (directory-files base-dir t
(unless recurse match
))
450 'org-e-publish-compare-directory-files
)
451 (directory-files base-dir t
(unless recurse match
)))))
453 (defun org-e-publish-get-base-files (project &optional exclude-regexp
)
454 "Return a list of all files in PROJECT.
455 If EXCLUDE-REGEXP is set, this will be used to filter out
457 (let* ((project-plist (cdr project
))
458 (base-dir (file-name-as-directory
459 (plist-get project-plist
:base-directory
)))
460 (include-list (plist-get project-plist
:include
))
461 (recurse (plist-get project-plist
:recursive
))
462 (extension (or (plist-get project-plist
:base-extension
) "org"))
463 ;; sitemap-... variables are dynamically scoped for
464 ;; org-e-publish-compare-directory-files:
465 (org-sitemap-requested
466 (plist-get project-plist
:auto-sitemap
))
468 (or (plist-get project-plist
:sitemap-filename
) "sitemap.org"))
469 (org-sitemap-sort-folders
470 (if (plist-member project-plist
:sitemap-sort-folders
)
471 (plist-get project-plist
:sitemap-sort-folders
)
472 org-e-publish-sitemap-sort-folders
))
473 (org-sitemap-sort-files
474 (cond ((plist-member project-plist
:sitemap-sort-files
)
475 (plist-get project-plist
:sitemap-sort-files
))
476 ;; For backward compatibility:
477 ((plist-member project-plist
:sitemap-alphabetically
)
478 (if (plist-get project-plist
:sitemap-alphabetically
)
479 'alphabetically nil
))
480 (t org-e-publish-sitemap-sort-files
)))
481 (org-sitemap-ignore-case
482 (if (plist-member project-plist
:sitemap-ignore-case
)
483 (plist-get project-plist
:sitemap-ignore-case
)
484 org-e-publish-sitemap-sort-ignore-case
))
485 (match (if (eq extension
'any
) "^[^\\.]"
486 (concat "^[^\\.].*\\.\\(" extension
"\\)$"))))
487 ;; Make sure `org-sitemap-sort-folders' has an accepted value
488 (unless (memq org-sitemap-sort-folders
'(first last
))
489 (setq org-sitemap-sort-folders nil
))
491 (setq org-e-publish-temp-files nil
)
492 (if org-sitemap-requested
493 (pushnew (expand-file-name (concat base-dir sitemap-filename
))
494 org-e-publish-temp-files
))
495 (org-e-publish-get-base-files-1 base-dir recurse match
496 ;; FIXME distinguish exclude regexp
497 ;; for skip-file and skip-dir?
498 exclude-regexp exclude-regexp
)
501 (expand-file-name (concat base-dir f
))
502 org-e-publish-temp-files
))
504 org-e-publish-temp-files
))
506 (defun org-e-publish-get-project-from-filename (filename &optional up
)
507 "Return the project that FILENAME belongs to."
508 (let* ((filename (expand-file-name filename
))
512 (dolist (prj org-e-publish-project-alist
)
513 (unless (plist-get (cdr prj
) :components
)
514 ;; [[info:org:Selecting%20files]] shows how this is supposed to work:
515 (let* ((r (plist-get (cdr prj
) :recursive
))
516 (b (expand-file-name (file-name-as-directory
517 (plist-get (cdr prj
) :base-directory
))))
518 (x (or (plist-get (cdr prj
) :base-extension
) "org"))
519 (e (plist-get (cdr prj
) :exclude
))
520 (i (plist-get (cdr prj
) :include
))
521 (xm (concat "^" b
(if r
".+" "[^/]+") "\\.\\(" x
"\\)$")))
525 (mapcar (lambda (file)
526 (expand-file-name file b
))
528 (and (not (and e
(string-match e filename
)))
529 (string-match xm filename
)))
530 (setq project-name
(car prj
))
531 (throw 'p-found project-name
))))))
533 (dolist (prj org-e-publish-project-alist
)
534 (if (member project-name
(plist-get (cdr prj
) :components
))
535 (setq project-name
(car prj
)))))
536 (assoc project-name org-e-publish-project-alist
)))
540 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
541 ;;; Pluggable publishing back-end functions
543 (defun org-e-publish-org-to (backend filename extension plist pub-dir
)
544 "Publish an Org file to a specified back-end.
546 BACKEND is a symbol representing the back-end used for
547 transcoding. FILENAME is the filename of the Org file to be
548 published. EXTENSION is the extension used for the output
549 string, with the leading dot. PLIST is the property list for the
550 given project. PUB-DIR is the publishing directory.
552 Return output file name."
553 (unless (file-exists-p pub-dir
) (make-directory pub-dir t
))
554 ;; Check if a buffer visiting FILENAME is already open.
555 (let* ((visitingp (find-buffer-visiting filename
))
556 (work-buffer (or visitingp
(find-file-noselect filename
))))
557 (prog1 (with-current-buffer work-buffer
559 (org-export-output-file-name extension nil pub-dir
))
560 (body-p (plist-get plist
:body-only
)))
562 backend output-file nil nil body-p
563 ;; Install `org-e-publish-collect-index' in parse tree
564 ;; filters. It isn't dependent on `:makeindex', since
565 ;; we want to keep it up-to-date in cache anyway.
567 plist
`(:filter-parse-tree
568 (org-e-publish-collect-index
569 ,@(plist-get plist
:filter-parse-tree
)))))))
570 ;; Remove opened buffer in the process.
571 (unless visitingp
(kill-buffer work-buffer
)))))
573 (defvar project-plist
)
574 (defun org-e-publish-org-to-latex (plist filename pub-dir
)
575 "Publish an Org file to LaTeX.
577 FILENAME is the filename of the Org file to be published. PLIST
578 is the property list for the given project. PUB-DIR is the
579 publishing directory.
581 Return output file name."
582 (require 'org-e-latex nil t
)
583 (org-e-publish-org-to 'e-latex filename
".tex" plist pub-dir
))
585 (defun org-e-publish-org-to-pdf (plist filename pub-dir
)
586 "Publish an Org file to PDF \(via LaTeX).
588 FILENAME is the filename of the Org file to be published. PLIST
589 is the property list for the given project. PUB-DIR is the
590 publishing directory.
592 Return output file name."
593 (require 'org-e-latex nil t
)
594 ;; Unlike to `org-e-publish-org-to-latex', PDF file is generated in
595 ;; base directory and then moved to publishing directory.
596 (org-e-publish-attachment
599 (org-e-publish-org-to
600 'e-latex filename
".tex" plist
(plist-get plist
:base-directory
)))
603 (defun org-e-publish-org-to-html (plist filename pub-dir
)
604 "Publish an org file to HTML.
606 FILENAME is the filename of the Org file to be published. PLIST
607 is the property list for the given project. PUB-DIR is the
608 publishing directory.
610 Return output file name."
611 (require 'org-e-html nil t
)
612 (org-e-publish-org-to 'e-html filename
".html" plist pub-dir
))
614 ;; TODO: Not implemented yet.
615 ;; (defun org-e-publish-org-to-org (plist filename pub-dir)
616 ;; "Publish an org file to HTML.
618 ;; FILENAME is the filename of the Org file to be published. PLIST
619 ;; is the property list for the given project. PUB-DIR is the
620 ;; publishing directory.
622 ;; Return output file name."
623 ;; (org-e-publish-org-to "org" plist filename pub-dir))
625 (defun org-e-publish-org-to-ascii (plist filename pub-dir
)
626 "Publish an Org file to ASCII.
628 FILENAME is the filename of the Org file to be published. PLIST
629 is the property list for the given project. PUB-DIR is the
630 publishing directory.
632 Return output file name."
633 (require 'org-e-ascii nil t
)
634 (org-e-publish-org-to
635 'e-ascii filename
".txt" `(:ascii-charset ascii
,@plist
) pub-dir
))
637 (defun org-e-publish-org-to-latin1 (plist filename pub-dir
)
638 "Publish an Org file to Latin-1.
640 FILENAME is the filename of the Org file to be published. PLIST
641 is the property list for the given project. PUB-DIR is the
642 publishing directory.
644 Return output file name."
645 (org-e-publish-org-to
646 'e-ascii filename
".txt" `(:ascii-charset latin1
,@plist
) pub-dir
))
648 (defun org-e-publish-org-to-utf8 (plist filename pub-dir
)
649 "Publish an org file to UTF-8.
651 FILENAME is the filename of the Org file to be published. PLIST
652 is the property list for the given project. PUB-DIR is the
653 publishing directory.
655 Return output file name."
656 (org-e-publish-org-to
657 'e-ascii filename
".txt" `(:ascii-charset utf-8
,@plist
) pub-dir
))
659 (defun org-e-publish-attachment (plist filename pub-dir
)
660 "Publish a file with no transformation of any kind.
662 FILENAME is the filename of the Org file to be published. PLIST
663 is the property list for the given project. PUB-DIR is the
664 publishing directory.
666 Return output file name."
667 (unless (file-directory-p pub-dir
)
668 (make-directory pub-dir t
))
669 (or (equal (expand-file-name (file-name-directory filename
))
670 (file-name-as-directory (expand-file-name pub-dir
)))
672 (expand-file-name (file-name-nondirectory filename
) pub-dir
)
677 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
678 ;;; Publishing files, sets of files, and indices
680 (defun org-e-publish-file (filename &optional project no-cache
)
681 "Publish file FILENAME from PROJECT.
682 If NO-CACHE is not nil, do not initialize org-e-publish-cache and
683 write it to disk. This is needed, since this function is used to
684 publish single files, when entire projects are published.
685 See `org-e-publish-projects'."
688 (or (org-e-publish-get-project-from-filename filename
)
689 (error "File %s not part of any known project"
690 (abbreviate-file-name filename
)))))
691 (project-plist (cdr project
))
692 (ftname (expand-file-name filename
))
694 (or (plist-get project-plist
:publishing-function
)
695 'org-e-publish-org-to-ascii
))
697 (file-name-as-directory
699 (or (plist-get project-plist
:base-directory
)
700 (error "Project %s does not have :base-directory defined"
703 (file-name-as-directory
705 (or (eval (plist-get project-plist
:publishing-directory
))
706 (error "Project %s does not have :publishing-directory defined"
710 (unless no-cache
(org-e-publish-initialize-cache (car project
)))
715 (and (string-match (regexp-quote base-dir
) ftname
)
716 (substring ftname
(match-end 0))))))
717 (if (listp publishing-function
)
718 ;; allow chain of publishing functions
720 (when (org-e-publish-needed-p
721 filename pub-dir f tmp-pub-dir base-dir
)
722 (funcall f project-plist filename tmp-pub-dir
)
723 (org-e-publish-update-timestamp filename pub-dir f base-dir
)))
725 (when (org-e-publish-needed-p
726 filename pub-dir publishing-function tmp-pub-dir base-dir
)
727 (funcall publishing-function project-plist filename tmp-pub-dir
)
728 (org-e-publish-update-timestamp
729 filename pub-dir publishing-function base-dir
)))
730 (unless no-cache
(org-e-publish-write-cache-file))))
732 (defun org-e-publish-projects (projects)
733 "Publish all files belonging to the PROJECTS alist.
734 If `:auto-sitemap' is set, publish the sitemap too. If
735 `:makeindex' is set, also produce a file theindex.org."
738 ;; Each project uses its own cache file:
739 (org-e-publish-initialize-cache (car project
))
740 (let* ((project-plist (cdr project
))
741 (exclude-regexp (plist-get project-plist
:exclude
))
742 (sitemap-p (plist-get project-plist
:auto-sitemap
))
743 (sitemap-filename (or (plist-get project-plist
:sitemap-filename
)
745 (sitemap-function (or (plist-get project-plist
:sitemap-function
)
746 'org-e-publish-org-sitemap
))
747 (org-sitemap-date-format
748 (or (plist-get project-plist
:sitemap-date-format
)
749 org-e-publish-sitemap-date-format
))
750 (org-sitemap-file-entry-format
751 (or (plist-get project-plist
:sitemap-file-entry-format
)
752 org-e-publish-sitemap-file-entry-format
))
753 (preparation-function
754 (plist-get project-plist
:preparation-function
))
755 (completion-function (plist-get project-plist
:completion-function
))
756 (files (org-e-publish-get-base-files project exclude-regexp
)) file
)
757 (when preparation-function
(run-hooks 'preparation-function
))
758 (if sitemap-p
(funcall sitemap-function project sitemap-filename
))
759 (dolist (file files
) (org-e-publish-file file project t
))
760 (when (plist-get project-plist
:makeindex
)
761 (org-e-publish-index-generate-theindex
762 project
(plist-get project-plist
:base-directory
))
765 "theindex.org" (plist-get project-plist
:base-directory
))
767 (when completion-function
(run-hooks 'completion-function
))
768 (org-e-publish-write-cache-file)))
769 (org-e-publish-expand-projects projects
)))
771 (defun org-e-publish-org-sitemap (project &optional sitemap-filename
)
772 "Create a sitemap of pages in set defined by PROJECT.
773 Optionally set the filename of the sitemap with SITEMAP-FILENAME.
774 Default for SITEMAP-FILENAME is 'sitemap.org'."
775 (let* ((project-plist (cdr project
))
776 (dir (file-name-as-directory
777 (plist-get project-plist
:base-directory
)))
778 (localdir (file-name-directory dir
))
779 (indent-str (make-string 2 ?\
))
780 (exclude-regexp (plist-get project-plist
:exclude
))
782 (org-e-publish-get-base-files project exclude-regexp
)))
783 (sitemap-filename (concat dir
(or sitemap-filename
"sitemap.org")))
784 (sitemap-title (or (plist-get project-plist
:sitemap-title
)
785 (concat "Sitemap for project " (car project
))))
786 (sitemap-style (or (plist-get project-plist
:sitemap-style
)
788 (sitemap-sans-extension
789 (plist-get project-plist
:sitemap-sans-extension
))
790 (visiting (find-buffer-visiting sitemap-filename
))
791 (ifn (file-name-nondirectory sitemap-filename
))
793 (with-current-buffer (setq sitemap-buffer
794 (or visiting
(find-file sitemap-filename
)))
796 (insert (concat "#+TITLE: " sitemap-title
"\n\n"))
797 (while (setq file
(pop files
))
798 (let ((fn (file-name-nondirectory file
))
799 (link (file-relative-name file dir
))
801 (when sitemap-sans-extension
802 (setq link
(file-name-sans-extension link
)))
803 ;; sitemap shouldn't list itself
804 (unless (equal (file-truename sitemap-filename
)
805 (file-truename file
))
806 (if (eq sitemap-style
'list
)
807 (message "Generating list-style sitemap for %s" sitemap-title
)
808 (message "Generating tree-style sitemap for %s" sitemap-title
)
809 (setq localdir
(concat (file-name-as-directory dir
)
810 (file-name-directory link
)))
811 (unless (string= localdir oldlocal
)
812 (if (string= localdir dir
)
813 (setq indent-str
(make-string 2 ?\
))
818 (file-relative-name localdir dir
))) "/"))
820 (old-subdirs (split-string
821 (file-relative-name oldlocal dir
) "/")))
822 (setq indent-str
(make-string 2 ?\
))
823 (while (string= (car old-subdirs
) (car subdirs
))
824 (setq indent-str
(concat indent-str
(make-string 2 ?\
)))
828 (setq subdir
(concat subdir d
"/"))
829 (insert (concat indent-str
" + " d
"\n"))
830 (setq indent-str
(make-string
831 (+ (length indent-str
) 2) ?\
)))))))
832 ;; This is common to 'flat and 'tree
834 (org-e-publish-format-file-entry
835 org-sitemap-file-entry-format file project-plist
))
836 (regexp "\\(.*\\)\\[\\([^][]+\\)\\]\\(.*\\)"))
837 (cond ((string-match-p regexp entry
)
838 (string-match regexp entry
)
839 (insert (concat indent-str
" + " (match-string 1 entry
)
841 (match-string 2 entry
)
842 "]]" (match-string 3 entry
) "\n")))
844 (insert (concat indent-str
" + [[file:" link
"]["
848 (or visiting
(kill-buffer sitemap-buffer
))))
850 (defun org-e-publish-format-file-entry (fmt file project-plist
)
852 `((?t .
,(org-e-publish-find-title file t
))
853 (?d .
,(format-time-string org-sitemap-date-format
854 (org-e-publish-find-date file
)))
855 (?a .
,(or (plist-get project-plist
:author
) user-full-name
)))))
857 (defun org-e-publish-find-title (file &optional reset
)
858 "Find the title of FILE in project."
860 (and (not reset
) (org-e-publish-cache-get-file-property file
:title nil t
))
861 (let* ((visiting (find-buffer-visiting file
))
862 (buffer (or visiting
(find-file-noselect file
)))
864 (with-current-buffer buffer
867 (or (plist-get (org-export-get-environment) :title
)
868 (file-name-nondirectory (file-name-sans-extension file
)))))
869 (unless visiting
(kill-buffer buffer
))
870 (org-e-publish-cache-set-file-property file
:title title
)
873 (defun org-e-publish-find-date (file)
874 "Find the date of FILE in project.
875 If FILE provides a #+date keyword use it else use the file
876 system's modification time.
878 It returns time in `current-time' format."
879 (let* ((visiting (find-buffer-visiting file
))
880 (file-buf (or visiting
(find-file-noselect file nil
)))
882 (with-current-buffer file-buf
884 (org-export--get-inbuffer-options))
886 (unless visiting
(kill-buffer file-buf
))
887 (if date
(org-time-string-to-time date
)
888 (when (file-exists-p file
)
889 (nth 5 (file-attributes file
))))))
893 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
894 ;;; Interactive publishing functions
897 (defalias 'org-e-publish-project
'org-e-publish
)
900 (defun org-e-publish (project &optional force
)
904 (assoc (org-icompleting-read
906 org-e-publish-project-alist nil t
)
907 org-e-publish-project-alist
)
909 (setq org-e-publish-initial-buffer
(current-buffer))
910 (save-window-excursion
911 (let* ((org-e-publish-use-timestamps-flag
912 (if force nil org-e-publish-use-timestamps-flag
)))
913 (org-e-publish-projects
914 (if (stringp project
)
915 ;; If this function is called in batch mode, project is
916 ;; still a string here.
917 (list (assoc project org-e-publish-project-alist
))
921 (defun org-e-publish-all (&optional force
)
922 "Publish all projects.
923 With prefix argument, remove all files in the timestamp
924 directory and force publishing all files."
926 (when force
(org-e-publish-remove-all-timestamps))
927 (save-window-excursion
928 (let ((org-e-publish-use-timestamps-flag
929 (if force nil org-e-publish-use-timestamps-flag
)))
930 (org-e-publish-projects org-e-publish-project-alist
))))
934 (defun org-e-publish-current-file (&optional force
)
935 "Publish the current file.
936 With prefix argument, force publish the file."
938 (save-window-excursion
939 (let ((org-e-publish-use-timestamps-flag
940 (if force nil org-e-publish-use-timestamps-flag
)))
941 (org-e-publish-file (buffer-file-name (buffer-base-buffer))))))
944 (defun org-e-publish-current-project (&optional force
)
945 "Publish the project associated with the current file.
946 With a prefix argument, force publishing of all files in
949 (save-window-excursion
950 (let ((project (org-e-publish-get-project-from-filename
951 (buffer-file-name (buffer-base-buffer)) 'up
))
952 (org-e-publish-use-timestamps-flag
953 (if force nil org-e-publish-use-timestamps-flag
)))
954 (if project
(org-e-publish project
)
955 (error "File %s is not part of any known project"
956 (buffer-file-name (buffer-base-buffer)))))))
962 (defun org-e-publish-collect-index (tree backend info
)
963 "Update index for a file with TREE in cache.
965 BACKEND is the back-end being used for transcoding. INFO is
966 a plist containing publishing options.
968 The index relative to current file is stored as an alist. An
969 association has the following shape: \(TERM FILE-NAME PARENT),
970 where TERM is the indexed term, as a string, FILE-NAME is the
971 original full path of the file where the term in encountered, and
972 PARENT is the headline element containing the original index
974 (org-e-publish-cache-set-file-property
975 (plist-get info
:input-file
) :index
980 (when (string= (downcase (org-element-property :key k
))
982 (let ((index (org-element-property :value k
))
983 (parent (org-export-get-parent-headline k
)))
984 (list index
(plist-get info
:input-file
) parent
))))
986 ;; Return parse-tree to avoid altering output.
989 (defun org-e-publish-index-generate-theindex (project directory
)
990 "Retrieve full index from cache and build \"theindex.org\".
991 PROJECT is the project the index relates to. DIRECTORY is the
992 publishing directory."
993 (let ((all-files (org-e-publish-get-base-files
994 project
(plist-get (cdr project
) :exclude
)))
996 ;; Compile full index.
999 (let ((index (org-e-publish-cache-get-file-property file
:index
)))
1000 (dolist (term index
)
1001 (unless (member term full-index
) (push term full-index
)))))
1003 ;; Sort it alphabetically.
1005 (sort full-index
(lambda (a b
) (string< (downcase (car a
))
1006 (downcase (car b
))))))
1007 ;; Fill "theindex.org".
1009 (insert "#+TITLE: Index\n#+OPTIONS: num:nil author:nil\n")
1010 (let ((current-letter nil
) (last-entry nil
))
1011 (dolist (idx full-index
)
1012 (let* ((entry (org-split-string (car idx
) "!"))
1013 (letter (upcase (substring (car entry
) 0 1)))
1014 ;; Transform file into a path relative to publishing
1016 (file (file-relative-name
1018 (plist-get (cdr project
) :base-directory
))))
1019 ;; Check if another letter has to be inserted.
1020 (unless (string= letter current-letter
)
1021 (insert (format "* %s\n" letter
)))
1022 ;; Compute the first difference between last entry and
1023 ;; current one: it tells the level at which new items
1025 (let* ((rank (loop for n from
0 to
(length entry
)
1026 unless
(equal (nth n entry
) (nth n last-entry
))
1028 (len (length (nthcdr rank entry
))))
1029 ;; For each term after the first difference, create
1030 ;; a new sub-list with the term as body. Moreover,
1031 ;; linkify the last term.
1035 (make-string (* (+ rank n
) 2) ?
) " - "
1036 (if (not (= (1- len
) n
)) (nth (+ rank n
) entry
)
1037 ;; Last term: Link it to TARGET, if possible.
1038 (let ((target (nth 2 idx
)))
1043 ((not target
) (format "file:%s" file
))
1044 ((let ((id (org-element-property :id target
)))
1045 (and id
(format "id:%s" id
))))
1046 ((let ((id (org-element-property :custom-id target
)))
1047 (and id
(format "file:%s::#%s" file id
))))
1048 (t (format "file:%s::*%s" file
1049 (org-element-property :raw-value target
))))
1051 (car (last entry
)))))
1053 (setq current-letter letter last-entry entry
))))
1055 (write-file (expand-file-name "theindex.org" directory
)))))
1059 ;;; Caching functions
1061 (defun org-e-publish-write-cache-file (&optional free-cache
)
1062 "Write `org-e-publish-cache' to file.
1063 If FREE-CACHE, empty the cache."
1064 (unless org-e-publish-cache
1065 (error "`org-e-publish-write-cache-file' called, but no cache present"))
1067 (let ((cache-file (org-e-publish-cache-get ":cache-file:")))
1069 (error "Cannot find cache-file name in `org-e-publish-write-cache-file'"))
1070 (with-temp-file cache-file
1071 (let (print-level print-length
)
1072 (insert "(setq org-e-publish-cache (make-hash-table :test 'equal :weakness nil :size 100))\n")
1073 (maphash (lambda (k v
)
1075 (format (concat "(puthash %S "
1076 (if (or (listp v
) (symbolp v
))
1078 "%S org-e-publish-cache)\n") k v
)))
1079 org-e-publish-cache
)))
1080 (when free-cache
(org-e-publish-reset-cache))))
1082 (defun org-e-publish-initialize-cache (project-name)
1083 "Initialize the projects cache if not initialized yet and return it."
1085 (unless project-name
1086 (error "Cannot initialize `org-e-publish-cache' without projects name in `org-e-publish-initialize-cache'"))
1088 (unless (file-exists-p org-e-publish-timestamp-directory
)
1089 (make-directory org-e-publish-timestamp-directory t
))
1090 (unless (file-directory-p org-e-publish-timestamp-directory
)
1091 (error "Org publish timestamp: %s is not a directory"
1092 org-e-publish-timestamp-directory
))
1094 (unless (and org-e-publish-cache
1095 (string= (org-e-publish-cache-get ":project:") project-name
))
1098 (expand-file-name org-e-publish-timestamp-directory
)
1099 project-name
".cache"))
1100 (cexists (file-exists-p cache-file
)))
1102 (when org-e-publish-cache
(org-e-publish-reset-cache))
1104 (if cexists
(load-file cache-file
)
1105 (setq org-e-publish-cache
1106 (make-hash-table :test
'equal
:weakness nil
:size
100))
1107 (org-e-publish-cache-set ":project:" project-name
)
1108 (org-e-publish-cache-set ":cache-file:" cache-file
))
1109 (unless cexists
(org-e-publish-write-cache-file nil
))))
1110 org-e-publish-cache
)
1112 (defun org-e-publish-reset-cache ()
1113 "Empty org-e-publish-cache and reset it nil."
1114 (message "%s" "Resetting org-e-publish-cache")
1115 (when (hash-table-p org-e-publish-cache
)
1116 (clrhash org-e-publish-cache
))
1117 (setq org-e-publish-cache nil
))
1119 (defun org-e-publish-cache-file-needs-publishing
1120 (filename &optional pub-dir pub-func base-dir
)
1121 "Check the timestamp of the last publishing of FILENAME.
1122 Non-nil if the file needs publishing. The function also checks
1123 if any included files have been more recently published, so that
1124 the file including them will be republished as well."
1125 (unless org-e-publish-cache
1127 "`org-e-publish-cache-file-needs-publishing' called, but no cache present"))
1128 (let* ((case-fold-search t
)
1129 (key (org-e-publish-timestamp-filename filename pub-dir pub-func
))
1130 (pstamp (org-e-publish-cache-get key
))
1131 (visiting (find-buffer-visiting filename
))
1132 included-files-ctime buf
)
1134 (when (equal (file-name-extension filename
) "org")
1135 (setq buf
(find-file (expand-file-name filename
)))
1136 (with-current-buffer buf
1137 (goto-char (point-min))
1138 (while (re-search-forward
1139 "^#\\+INCLUDE:[ \t]+\"\\([^\t\n\r\"]*\\)\"[ \t]*.*$" nil t
)
1140 (let* ((included-file (expand-file-name (match-string 1))))
1141 (add-to-list 'included-files-ctime
1142 (org-e-publish-cache-ctime-of-src included-file
) t
))))
1143 (unless visiting
(kill-buffer buf
)))
1145 (let ((ctime (org-e-publish-cache-ctime-of-src filename
)))
1146 (or (< pstamp ctime
)
1147 (when included-files-ctime
1148 (not (null (delq nil
(mapcar (lambda(ct) (< ctime ct
))
1149 included-files-ctime
))))))))))
1151 (defun org-e-publish-cache-set-file-property
1152 (filename property value
&optional project-name
)
1153 "Set the VALUE for a PROPERTY of file FILENAME in publishing cache to VALUE.
1154 Use cache file of PROJECT-NAME. If the entry does not exist, it
1155 will be created. Return VALUE."
1156 ;; Evtl. load the requested cache file:
1157 (if project-name
(org-e-publish-initialize-cache project-name
))
1158 (let ((pl (org-e-publish-cache-get filename
)))
1159 (if pl
(progn (plist-put pl property value
) value
)
1160 (org-e-publish-cache-get-file-property
1161 filename property value nil project-name
))))
1163 (defun org-e-publish-cache-get-file-property
1164 (filename property
&optional default no-create project-name
)
1165 "Return the value for a PROPERTY of file FILENAME in publishing cache.
1166 Use cache file of PROJECT-NAME. Return the value of that PROPERTY
1167 or DEFAULT, if the value does not yet exist. If the entry will
1168 be created, unless NO-CREATE is not nil."
1169 ;; Evtl. load the requested cache file:
1170 (if project-name
(org-e-publish-initialize-cache project-name
))
1171 (let ((pl (org-e-publish-cache-get filename
)) retval
)
1173 (if (plist-member pl property
)
1174 (setq retval
(plist-get pl property
))
1175 (setq retval default
))
1178 (org-e-publish-cache-set filename
(list property default
)))
1179 (setq retval default
))
1182 (defun org-e-publish-cache-get (key)
1183 "Return the value stored in `org-e-publish-cache' for key KEY.
1184 Returns nil, if no value or nil is found, or the cache does not
1186 (unless org-e-publish-cache
1187 (error "`org-e-publish-cache-get' called, but no cache present"))
1188 (gethash key org-e-publish-cache
))
1190 (defun org-e-publish-cache-set (key value
)
1191 "Store KEY VALUE pair in `org-e-publish-cache'.
1192 Returns value on success, else nil."
1193 (unless org-e-publish-cache
1194 (error "`org-e-publish-cache-set' called, but no cache present"))
1195 (puthash key value org-e-publish-cache
))
1197 (defun org-e-publish-cache-ctime-of-src (file)
1198 "Get the ctime of FILE as an integer."
1199 (let ((attr (file-attributes
1200 (expand-file-name (or (file-symlink-p file
) file
)
1201 (file-name-directory file
)))))
1202 (+ (lsh (car (nth 5 attr
)) 16)
1203 (cadr (nth 5 attr
)))))
1206 (provide 'org-e-publish
)
1208 ;;; org-e-publish.el ends here