contrib/lisp/ox-s5.el

   1 ;;; ox-s5.el --- S5 Presentation Back-End for Org Export Engine
   2
   3 ;; Copyright (C) 2011-2013  Rick Frankel
   4
   5 ;; Author: Rick Frankel <emacs at rickster dot com>
   6 ;; Keywords: outlines, hypermedia, S5, wp
   7
   8 ;; This file is not part of GNU Emacs.
   9
  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.
  14
  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.
  19
  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/>.
  22
  23 ;;; Commentary:
  24
  25 ;; This library implements an S5 Presentation back-end for the Org
  26 ;; generic exporter.
  27
  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).
  36
  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.
  43
  44 ;; To test it, run:
  45 ;;
  46 ;;   M-x org-s5-export-as-html
  47 ;;
  48 ;; in an Org mode buffer.  See ox.el and ox-html.el for more details
  49 ;; on how this exporter works.
  50
  51 (require 'ox-html)
  52
  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)))
  80
  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)
  85
  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)
  92
  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)
 103
 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)
 110
 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)))
 115
 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)))
 120
 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.
 129
 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.
 133
 134 Note that changing the preamble or postamble will break the
 135 core S5 stylesheets.")
 136
 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.
 140
 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.
 144
 145 Setting the S5_POSTAMBLE option -- or the :s5-postamble in publishing
 146 projects -- will take precedence over this variable.
 147
 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)")))
 154
 155 (defcustom org-s5-preamble "&#x20;"
 156   "Peamble inserted into the S5 layout section.
 157
 158 When set to a string, use this string as the preamble.
 159
 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.
 163
 164 Setting S5_PREAMBLE option -- or the :s5-preamble in publishing
 165 projects -- will take precedence over this variable.
 166
 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)")))
 173
 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.
 182
 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)
 188
 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))))
 205
 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))))))
 223
 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")))
 251
 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))))
 261
 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)))
 269
 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))))
 288
 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"))
 294
 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       (plist-get info :html-doctype)
 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")))
 340
 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.
 344
 345 If narrowing is active in the current buffer, only export its
 346 narrowed part.
 347
 348 If a region is active, export that region.
 349
 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.
 353
 354 When optional argument SUBTREEP is non-nil, export the sub-tree
 355 at point, extracting information from the headline properties
 356 first.
 357
 358 When optional argument VISIBLE-ONLY is non-nil, don't export
 359 contents of hidden elements.
 360
 361 When optional argument BODY-ONLY is non-nil, only write code
 362 between \"<body>\" and \"</body>\" tags.
 363
 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.
 367
 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   (if async
 373       (org-export-async-start
 374           (lambda (output)
 375             (with-current-buffer (get-buffer-create "*Org S5 Export*")
 376               (erase-buffer)
 377               (insert output)
 378               (goto-char (point-min))
 379               (nxml-mode)
 380               (org-export-add-to-stack (current-buffer) 's5)))
 381         `(org-export-as 's5 ,subtreep ,visible-only ,body-only ',ext-plist))
 382     (let ((outbuf (org-export-to-buffer
 383                    's5 "*Org S5 Export*"
 384                    subtreep visible-only body-only ext-plist)))
 385       ;; Set major mode.
 386       (with-current-buffer outbuf (nxml-mode))
 387       (when org-export-show-temporary-export-buffer
 388         (switch-to-buffer-other-window outbuf)))))
 389
 390 (defun org-s5-export-to-html
 391   (&optional async subtreep visible-only body-only ext-plist)
 392   "Export current buffer to a S5 HTML file.
 393
 394 If narrowing is active in the current buffer, only export its
 395 narrowed part.
 396
 397 If a region is active, export that region.
 398
 399 A non-nil optional argument ASYNC means the process should happen
 400 asynchronously.  The resulting file should be accessible through
 401 the `org-export-stack' interface.
 402
 403 When optional argument SUBTREEP is non-nil, export the sub-tree
 404 at point, extracting information from the headline properties
 405 first.
 406
 407 When optional argument VISIBLE-ONLY is non-nil, don't export
 408 contents of hidden elements.
 409
 410 When optional argument BODY-ONLY is non-nil, only write code
 411 between \"<body>\" and \"</body>\" tags.
 412
 413 EXT-PLIST, when provided, is a property list with external
 414 parameters overriding Org default settings, but still inferior to
 415 file-local settings.
 416
 417 Return output file's name."
 418   (interactive)
 419   (let* ((extension (concat "." org-html-extension))
 420          (file (org-export-output-file-name extension subtreep))
 421          (org-export-coding-system org-html-coding-system))
 422     (if async
 423         (org-export-async-start
 424             (lambda (f) (org-export-add-to-stack f 's5))
 425           (let ((org-export-coding-system org-html-coding-system))
 426             `(expand-file-name
 427               (org-export-to-file
 428                's5 ,file ,subtreep ,visible-only ,body-only ',ext-plist))))
 429       (let ((org-export-coding-system org-html-coding-system))
 430         (org-export-to-file
 431          's5 file subtreep visible-only body-only ext-plist)))))
 432
 433 (defun org-s5-publish-to-html (plist filename pub-dir)
 434   "Publish an org file to S5 HTML Presentation.
 435
 436 FILENAME is the filename of the Org file to be published.  PLIST
 437 is the property list for the given project.  PUB-DIR is the
 438 publishing directory.
 439
 440 Return output file name."
 441   (org-publish-org-to 's5 filename ".html" plist pub-dir))
 442
 443 (provide 'ox-s5)
 444
 445 ;;; ox-s5.el ends here