Update copyright years again.
[org-mode.git] / contrib / lisp / ox-s5.el
blob19937223de91f91bb0c7ff281c9ac09602fb2352
1 ;;; ox-s5.el --- S5 Presentation Back-End for Org Export Engine
3 ;; Copyright (C) 2011-2014 Rick Frankel
5 ;; Author: Rick Frankel <emacs at rickster dot com>
6 ;; Keywords: outlines, hypermedia, S5, wp
8 ;; This file is not part of GNU Emacs.
10 ;; This program 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 ;; This program 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 this program. If not, see <http://www.gnu.org/licenses/>.
23 ;;; Commentary:
25 ;; This library implements an S5 Presentation back-end for the Org
26 ;; generic exporter.
28 ;; Installation
29 ;; ------------
30 ;; Get the s5 scripts from
31 ;; http://meyerweb.com/eric/tools/s5/
32 ;; (Note that the default s5 version is set for using the alpha, 1.2a2.
33 ;; Copy the ui dir to somewhere reachable from your published presentation
34 ;; The default (`org-s5-ui-url') is set to "ui" (e.g., in the
35 ;; same directory as the html file).
37 ;; Usage
38 ;; -----
39 ;; Follow the general instructions at the above website. To generate
40 ;; incremental builds, you can set the HTML_CONTAINER_CLASS on an
41 ;; object to "incremental" to make it build. If you want an outline to
42 ;; build, set the :INCREMENTAL property on the parent headline.
44 ;; To test it, run:
46 ;; M-x org-s5-export-as-html
48 ;; in an Org mode buffer. See ox.el and ox-html.el for more details
49 ;; on how this exporter works.
51 (require 'ox-html)
53 (org-export-define-derived-backend 's5 'html
54 :menu-entry
55 '(?s "Export to S5 HTML Presentation"
56 ((?H "To temporary buffer" org-s5-export-as-html)
57 (?h "To file" org-s5-export-to-html)
58 (?o "To file and open"
59 (lambda (a s v b)
60 (if a (org-s5-export-to-html t s v b)
61 (org-open-file (org-s5-export-to-html nil s v b)))))))
62 :options-alist
63 '((:html-link-home "HTML_LINK_HOME" nil nil)
64 (:html-link-up "HTML_LINK_UP" nil nil)
65 (:s5-postamble "S5_POSTAMBLE" nil org-s5-postamble newline)
66 (:s5-preamble "S5_PREAMBLE" nil org-s5-preamble newline)
67 (:html-head-include-default-style "HTML_INCLUDE_DEFAULT_STYLE" nil nil)
68 (:html-head-include-scripts "HTML_INCLUDE_SCRIPTS" nil nil)
69 (:s5-version "S5_VERSION" nil org-s5-version)
70 (:s5-theme-file "S5_THEME_FILE" nil org-s5-theme-file)
71 (:s5-ui-url "S5_UI_URL" nil org-s5-ui-url)
72 (:s5-default-view "S5_DEFAULT_VIEW" nil org-s5-default-view)
73 (:s5-control-visibility "S5_CONTROL_VISIBILITY" nil
74 org-s5-control-visibility))
75 :translate-alist
76 '((headline . org-s5-headline)
77 (plain-list . org-s5-plain-list)
78 (inner-template . org-s5-inner-template)
79 (template . org-s5-template)))
81 (defgroup org-export-s5 nil
82 "Options for exporting Org mode files to S5 HTML Presentations."
83 :tag "Org Export S5"
84 :group 'org-export-html)
86 (defcustom org-s5-version "1.2a2"
87 "Version of s5 being used (for version metadata.) Defaults to
88 s5 v2 alpha 2.
89 Can be overridden with S5_VERSION."
90 :group 'org-export-s5
91 :type 'string)
93 (defcustom org-s5-theme-file nil
94 "Url to S5 theme (slides.css) file. Can be overriden with the
95 S5_THEME_FILE property. If nil, defaults to
96 `org-s5-ui-url'/default/slides.css. If it starts with anything but
97 \"http\" or \"/\", it is used as-is. Otherwise the link in generated
98 relative to `org-s5-ui-url'.
99 The links for all other required stylesheets and scripts will be
100 generated relative to `org-s5-ui-url'/default."
101 :group 'org-export-s5
102 :type 'string)
104 (defcustom org-s5-ui-url "ui"
105 "Base url to directory containing S5 \"default\" subdirectory
106 and the \"s5-notes.html\" file.
107 Can be overriden with the S5_UI_URL property."
108 :group 'org-export-s5
109 :type 'string)
111 (defcustom org-s5-default-view 'slideshow
112 "Setting for \"defaultView\" meta info."
113 :group 'org-export-s5
114 :type '(choice (const slideshow) (const outline)))
116 (defcustom org-s5-control-visibility 'hidden
117 "Setting for \"controlVis\" meta info."
118 :group 'org-export-s5
119 :type '(choice (const hidden) (const visibile)))
121 (defvar org-s5--divs
122 '((preamble "div" "header")
123 (content "div" "content")
124 (postamble "div" "footer"))
125 "Alist of the three section elements for HTML export.
126 The car of each entry is one of 'preamble, 'content or 'postamble.
127 The cdrs of each entry are the ELEMENT_TYPE and ID for each
128 section of the exported document.
130 If you set `org-html-container-element' to \"li\", \"ol\" will be
131 uses as the content ELEMENT_TYPE, generating an XOXO format
132 slideshow.
134 Note that changing the preamble or postamble will break the
135 core S5 stylesheets.")
137 (defcustom org-s5-postamble "<h1>%a - %t</h1>"
138 "Preamble inserted into the S5 layout section.
139 When set to a string, use this string as the postamble.
141 When set to a function, apply this function and insert the
142 returned string. The function takes the property list of export
143 options as its only argument.
145 Setting the S5_POSTAMBLE option -- or the :s5-postamble in publishing
146 projects -- will take precedence over this variable.
148 Note that the default css styling will break if this is set to nil
149 or an empty string."
150 :group 'org-export-s5
151 :type '(choice (const :tag "No postamble" "&#x20;")
152 (string :tag "Custom formatting string")
153 (function :tag "Function (must return a string)")))
155 (defcustom org-s5-preamble "&#x20;"
156 "Peamble inserted into the S5 layout section.
158 When set to a string, use this string as the preamble.
160 When set to a function, apply this function and insert the
161 returned string. The function takes the property list of export
162 options as its only argument.
164 Setting S5_PREAMBLE option -- or the :s5-preamble in publishing
165 projects -- will take precedence over this variable.
167 Note that the default css styling will break if this is set to nil
168 or an empty string."
169 :group 'org-export-s5
170 :type '(choice (const :tag "No preamble" "&#x20;")
171 (string :tag "Custom formatting string")
172 (function :tag "Function (must return a string)")))
174 (defcustom org-s5-title-slide-template
175 "<h1>%t</h1>
176 <h2>%a</h2>
177 <h2>%e</h2>
178 <h2>%d</h2>"
179 "Format template to specify title page section.
180 See `org-html-postamble-format' for the valid elements which
181 can be included.
183 It will be wrapped in the element defined in the :html-container
184 property, and defaults to the value of `org-html-container-element',
185 and have the id \"title-slide\"."
186 :group 'org-export-s5
187 :type 'string)
189 (defun org-s5--format-toc-headline (headline info)
190 "Return an appropriate table of contents entry for HEADLINE.
191 Note that (currently) the S5 exporter does not support deep links,
192 so the table of contents is not \"active\".
193 INFO is a plist used as a communication channel."
194 (let* ((headline-number (org-export-get-headline-number headline info))
195 (section-number
196 (and (not (org-export-low-level-p headline info))
197 (org-export-numbered-headline-p headline info)
198 (concat (mapconcat 'number-to-string headline-number ".") ". ")))
199 (tags (and (eq (plist-get info :with-tags) t)
200 (org-export-get-tags headline info))))
201 (concat section-number
202 (org-export-data
203 (org-export-get-alt-title headline info) info)
204 (and tags "&nbsp;&nbsp;&nbsp;") (org-html--tags tags))))
206 (defun org-s5-toc (depth info)
207 (let* ((headlines (org-export-collect-headlines info depth))
208 (toc-entries
209 (mapcar (lambda (headline)
210 (cons (org-s5--format-toc-headline headline info)
211 (org-export-get-relative-level headline info)))
212 (org-export-collect-headlines info depth))))
213 (when toc-entries
214 (concat
215 (format "<%s id='table-of-contents' class='slide'>\n"
216 (plist-get info :html-container))
217 (format "<h1>%s</h1>\n"
218 (org-html--translate "Table of Contents" info))
219 "<div id=\"text-table-of-contents\">"
220 (org-html--toc-text toc-entries)
221 "</div>\n"
222 (format "</%s>\n" (plist-get info :html-container))))))
224 (defun org-s5--build-head (info)
225 (let* ((dir (plist-get info :s5-ui-url))
226 (theme (or (plist-get info :s5-theme-file) "default/slides.css")))
227 (mapconcat
228 'identity
229 (list
230 "<!-- style sheet links -->"
231 (mapconcat
232 (lambda (list)
233 (format
234 (concat
235 "<link rel='stylesheet' href='%s/default/%s' type='text/css'"
236 " media='%s' id='%s' />")
237 dir (nth 0 list) (nth 1 list) (nth 2 list)))
238 (list
239 '("outline.css" "screen" "outlineStyle")
240 '("print.css" "print" "slidePrint")
241 '("opera.css" "projection" "operaFix")) "\n")
242 (format (concat
243 "<link rel='stylesheet' href='%s' type='text/css'"
244 " media='screen' id='slideProj' />")
245 (if (string-match-p "^\\(http\\|/\\)" theme) theme
246 (concat dir "/" theme)))
247 "<!-- S5 JS -->"
248 (concat
249 "<script src='" dir
250 "/default/slides.js' type='text/javascript'></script>")) "\n")))
252 (defun org-s5--build-meta-info (info)
253 (concat
254 (org-html--build-meta-info info)
255 (format "<meta name=\"version\" content=\"S5 %s\" />\n"
256 (plist-get info :s5-version))
257 (format "<meta name='defaultView' content='%s' />\n"
258 (plist-get info :s5-default-view))
259 (format "<meta name='controlVis' content='%s' />"
260 (plist-get info :s5-control-visibility))))
262 (defun org-s5-headline (headline contents info)
263 (let ((org-html-toplevel-hlevel 1)
264 (class (or (org-element-property :HTML_CONTAINER_CLASS headline) ""))
265 (level (org-export-get-relative-level headline info)))
266 (when (and (= 1 level) (not (string-match-p "\\<slide\\>" class)))
267 (org-element-put-property headline :HTML_CONTAINER_CLASS (concat class " slide")))
268 (org-html-headline headline contents info)))
270 (defun org-s5-plain-list (plain-list contents info)
271 "Transcode a PLAIN-LIST element from Org to HTML.
272 CONTENTS is the contents of the list. INFO is a plist holding
273 contextual information.
274 If a containing headline has the property :INCREMENTAL,
275 then the \"incremental\" class will be added to the to the list,
276 which will make the list into a \"build\"."
277 (let* ((type (org-element-property :type plain-list))
278 (tag (case type
279 (ordered "ol")
280 (unordered "ul")
281 (descriptive "dl"))))
282 (format "%s\n%s%s"
283 (format
284 "<%s class='org-%s%s'>" tag tag
285 (if (org-export-get-node-property :INCREMENTAL plain-list t)
286 " incremental" ""))
287 contents (org-html-end-plain-list type))))
289 (defun org-s5-inner-template (contents info)
290 "Return body of document string after HTML conversion.
291 CONTENTS is the transcoded contents string. INFO is a plist
292 holding export options."
293 (concat contents "\n"))
295 (defun org-s5-template (contents info)
296 "Return complete document string after HTML conversion.
297 CONTENTS is the transcoded contents string. INFO is a plist
298 holding export options."
299 (let ((org-html-divs
300 (if (equal (plist-get info :html-container) "li")
301 (append '((content "ol" "content")) org-s5--divs)
302 org-s5--divs))
303 (info (plist-put
304 (plist-put info :html-preamble (plist-get info :s5-preamble))
305 :html-postamble (plist-get info :s5-postamble))))
306 (mapconcat
307 'identity
308 (list
309 (org-html-doctype info)
310 (format "<html xmlns=\"http://www.w3.org/1999/xhtml\" lang=\"%s\" xml:lang=\"%s\">"
311 (plist-get info :language) (plist-get info :language))
312 "<head>"
313 (org-s5--build-meta-info info)
314 (org-s5--build-head info)
315 (org-html--build-head info)
316 (org-html--build-mathjax-config info)
317 "</head>"
318 "<body>"
319 "<div class=\"layout\">"
320 "<div id=\"controls\"><!-- no edit --></div>"
321 "<div id=\"currentSlide\"><!-- no edit --></div>"
322 (org-html--build-pre/postamble 'preamble info)
323 (org-html--build-pre/postamble 'postamble info)
324 "</div>"
325 (format "<%s id=\"%s\" class=\"presentation\">"
326 (nth 1 (assq 'content org-html-divs))
327 (nth 2 (assq 'content org-html-divs)))
328 ;; title page
329 (format "<%s id='title-slide' class='slide'>"
330 (plist-get info :html-container))
331 (format-spec org-s5-title-slide-template (org-html-format-spec info))
332 (format "</%s>" (plist-get info :html-container))
333 ;; table of contents.
334 (let ((depth (plist-get info :with-toc)))
335 (when depth (org-s5-toc depth info)))
336 contents
337 (format "</%s>" (nth 1 (assq 'content org-html-divs)))
338 "</body>"
339 "</html>\n") "\n")))
341 (defun org-s5-export-as-html
342 (&optional async subtreep visible-only body-only ext-plist)
343 "Export current buffer to an HTML buffer.
345 If narrowing is active in the current buffer, only export its
346 narrowed part.
348 If a region is active, export that region.
350 A non-nil optional argument ASYNC means the process should happen
351 asynchronously. The resulting buffer should be accessible
352 through the `org-export-stack' interface.
354 When optional argument SUBTREEP is non-nil, export the sub-tree
355 at point, extracting information from the headline properties
356 first.
358 When optional argument VISIBLE-ONLY is non-nil, don't export
359 contents of hidden elements.
361 When optional argument BODY-ONLY is non-nil, only write code
362 between \"<body>\" and \"</body>\" tags.
364 EXT-PLIST, when provided, is a property list with external
365 parameters overriding Org default settings, but still inferior to
366 file-local settings.
368 Export is done in a buffer named \"*Org S5 Export*\", which
369 will be displayed when `org-export-show-temporary-export-buffer'
370 is non-nil."
371 (interactive)
372 (org-export-to-buffer 's5 "*Org S5 Export*"
373 async subtreep visible-only body-only ext-plist (lambda () (nxml-mode))))
375 (defun org-s5-export-to-html
376 (&optional async subtreep visible-only body-only ext-plist)
377 "Export current buffer to a S5 HTML file.
379 If narrowing is active in the current buffer, only export its
380 narrowed part.
382 If a region is active, export that region.
384 A non-nil optional argument ASYNC means the process should happen
385 asynchronously. The resulting file should be accessible through
386 the `org-export-stack' interface.
388 When optional argument SUBTREEP is non-nil, export the sub-tree
389 at point, extracting information from the headline properties
390 first.
392 When optional argument VISIBLE-ONLY is non-nil, don't export
393 contents of hidden elements.
395 When optional argument BODY-ONLY is non-nil, only write code
396 between \"<body>\" and \"</body>\" tags.
398 EXT-PLIST, when provided, is a property list with external
399 parameters overriding Org default settings, but still inferior to
400 file-local settings.
402 Return output file's name."
403 (interactive)
404 (let* ((extension (concat "." org-html-extension))
405 (file (org-export-output-file-name extension subtreep))
406 (org-export-coding-system org-html-coding-system))
407 (org-export-to-file 's5 file
408 async subtreep visible-only body-only ext-plist)))
410 (defun org-s5-publish-to-html (plist filename pub-dir)
411 "Publish an org file to S5 HTML Presentation.
413 FILENAME is the filename of the Org file to be published. PLIST
414 is the property list for the given project. PUB-DIR is the
415 publishing directory.
417 Return output file name."
418 (org-publish-org-to 's5 filename ".html" plist pub-dir))
420 (provide 'ox-s5)
422 ;;; ox-s5.el ends here