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 program is free software; you can redistribute it and/or modify
   9 ;; it under the terms of the GNU General Public License as published by
  10 ;; the Free Software Foundation, either version 3 of the License, or
  11 ;; (at your option) any later version.
  12
  13 ;; This program is distributed in the hope that it will be useful,
  14 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 ;; GNU General Public License for more details.
  17
  18 ;; You should have received a copy of the GNU General Public License
  19 ;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
  20
  21 ;;; Commentary:
  22
  23 ;; This library implements an S5 Presentation back-end for the Org
  24 ;; generic exporter.
  25
  26 ;; Installation
  27 ;; ------------
  28 ;; Get the s5 scripts from
  29 ;;    http://meyerweb.com/eric/tools/s5/
  30 ;; (Note that the default s5 version is set for using the alpha, 1.2a2.
  31 ;; Copy the ui dir to somewhere reachable from your published presentation
  32 ;; The default (`org-s5-ui-url') is set to "ui" (e.g., in the
  33 ;; same directory as the html file).
  34
  35 ;; Usage
  36 ;; -----
  37 ;; Follow the general instructions at the above website. To generate
  38 ;; incremental builds, you can set the HTML_CONTAINER_CLASS on an
  39 ;; object to "incremental" to make it build. If you want an outline to
  40 ;; build, set the :INCREMENTAL property on the parent headline.
  41
  42 ;; To test it, run:
  43 ;;
  44 ;;   M-x org-s5-export-as-html
  45 ;;
  46 ;; in an Org mode buffer.  See ox.el and ox-html.el for more details
  47 ;; on how this exporter works.
  48
  49 (require 'ox-html)
  50
  51 (org-export-define-derived-backend s5 html
  52   :menu-entry
  53   (?s "Export to S5 HTML Presentation"
  54       ((?H "To temporary buffer" org-s5-export-as-html)
  55        (?h "To file" org-s5-export-to-html)
  56        (?o "To file and open"
  57            (lambda (a s v b)
  58              (if a (org-s5-export-to-html t s v b)
  59                (org-open-file (org-s5-export-to-html nil s v b)))))))
  60   :options-alist
  61   ((:html-link-home "HTML_LINK_HOME" nil nil)
  62    (:html-link-up "HTML_LINK_UP" nil nil)
  63    (:html-mathjax "HTML_MATHJAX" nil "" space)
  64    (:html-postamble nil "html-postamble" nil t)
  65    (:html-preamble nil "html-preamble" nil t)
  66    (:html-style-extra "HTML_STYLE" nil org-html-style-extra newline)
  67    (:html-style-include-default "HTML_INCLUDE_DEFAULT" nil nil)
  68    (:html-style-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 org-s5-control-visibility))
  74   :translate-alist
  75   ((headline . org-s5-headline)
  76    (plain-list . org-s5-plain-list)
  77    (inner-template . org-s5-inner-template)
  78    (template . org-s5-template)))
  79
  80 (defgroup org-export-s5 nil
  81   "Options for exporting Org mode files to S5 HTML Presentations."
  82   :tag "Org Export S5"
  83   :group 'org-export-html)
  84
  85 (defcustom org-s5-version "1.2a2"
  86   "Version of s5 being used (for version metadata.) Defaults to
  87 s5 v2 alpha 2.
  88 Can be overridden with S5_VERSION."
  89   :group 'org-export-s5
  90   :type 'string)
  91
  92 (defcustom org-s5-theme-file nil
  93 "Url to S5 theme (slides.css) file. Can be overriden with the
  94 S5_THEME_FILE property. If nil, defaults to
  95 `org-s5-ui-url'/default/slides.css. If it starts with anything but
  96 \"http\" or \"/\", it is used as-is. Otherwise the link in generated
  97 relative to `org-s5-ui-url'.
  98 The links for all other required stylesheets and scripts will be
  99 generated relative to `org-s5-ui-url'/default."
 100   :group 'org-export-s5
 101   :type 'string)
 102
 103 (defcustom org-s5-ui-url "ui"
 104   "Base url to directory containing S5 \"default\" subdirectory
 105 and the \"s5-notes.html\" file.
 106 Can be overriden with the S5_UI_URL property."
 107   :group 'org-export-s5
 108   :type 'string)
 109
 110 (defcustom org-s5-default-view 'slideshow
 111   "Setting for \"defaultView\" meta info."
 112   :group 'org-export-s5
 113   :type '(choice (const slideshow) (const outline)))
 114
 115 (defcustom org-s5-control-visibility 'hidden
 116   "Setting for \"controlVis\" meta info."
 117   :group 'org-export-s5
 118   :type '(choice (const hidden) (const visibile)))
 119
 120 (defcustom org-s5-footer-template
 121   "<div id=\"footer\">
 122 <h1>%author - %title</h1>
 123 </div>"
 124   "Format template to specify footer div. Completed using
 125 `org-fill-template'.
 126 Optional keys include %author, %email, %file, %title and %date.
 127 Note that the div id must be \"footer\"."
 128   :group 'org-export-s5
 129   :type 'string)
 130
 131 (defcustom org-s5-header-template "<div id=\"header\"></div>"
 132   "Format template to specify footer div. Completed using
 133 `org-fill-template'.
 134 Optional keys include %author, %email, %file, %title and %date.
 135 Note that the div id must be \"header\"."
 136   :group 'org-export-s5
 137   :type 'string)
 138
 139 (defcustom org-s5-title-page-template
 140   "<div class=\"slide title-page\">
 141 <h1>%title</h1>
 142 <h1>%author</h1>
 143 <h1>%email</h1>
 144 <h1>%date</h1>
 145 </div>"
 146   "Format template to specify title page div. Completed using
 147 `org-fill-template'.
 148 Optional keys include %author, %email, %file, %title and %date.
 149 Note that the wrapper div must include the class \"slide\"."
 150   :group 'org-export-s5
 151   :type 'string)
 152
 153
 154 (defun org-s5--format-toc-headline (headline info)
 155   "Return an appropriate table of contents entry for HEADLINE.
 156 Note that (currently) the S5 exporter does not support deep links,
 157 so the table of contents is not \"active\".
 158 INFO is a plist used as a communication channel."
 159   (let* ((headline-number (org-export-get-headline-number headline info))
 160          (section-number
 161           (and (not (org-export-low-level-p headline info))
 162                (org-export-numbered-headline-p headline info)
 163                (concat (mapconcat 'number-to-string headline-number ".") ". ")))
 164          (tags (and (eq (plist-get info :with-tags) t)
 165                     (org-export-get-tags headline info))))
 166     (concat section-number
 167             (org-export-data
 168              (org-export-get-alt-title headline info) info)
 169             (and tags "&nbsp;&nbsp;&nbsp;") (org-html--tags tags))))
 170
 171 (defun org-s5-toc (depth info)
 172   (let* ((headlines (org-export-collect-headlines info depth))
 173          (toc-entries
 174           (mapcar (lambda (headline)
 175                     (cons (org-s5--format-toc-headline headline info)
 176                           (org-export-get-relative-level headline info)))
 177                   (org-export-collect-headlines info depth))))
 178     (when toc-entries
 179       (concat
 180        "<div id=\"table-of-contents\" class=\"slide\">\n"
 181        (format "<h1>%s</h1>\n"
 182                (org-html--translate "Table of Contents" info))
 183        "<div id=\"text-table-of-contents\">"
 184        (org-html--toc-text toc-entries)
 185        "</div>\n"
 186        "</div>\n"))))
 187
 188 (defun org-s5--build-style (info)
 189   (let* ((dir (plist-get info :s5-ui-url))
 190          (theme (or (plist-get info :s5-theme-file) "default/slides.css")))
 191     (mapconcat
 192      'identity
 193      (list
 194       "<!-- style sheet links -->"
 195       (mapconcat
 196        (lambda (list)
 197          (format
 198           (concat
 199            "<link rel='stylesheet' href='%s/default/%s' type='text/css'"
 200            " media='%s' id='%s' />")
 201           dir (nth 0 list) (nth 1 list) (nth 2 list)))
 202        (list
 203         '("outline.css" "screen" "outlineStyle")
 204         '("print.css" "print" "slidePrint")
 205         '("opera.css" "projection" "operaFix")) "\n")
 206       (format (concat
 207                "<link rel='stylesheet' href='%s' type='text/css'"
 208                " media='screen' id='slideProj' />")
 209               (if (string-match-p "^\\(http\\|/\\)" theme) theme
 210                 (concat dir "/" theme)))
 211       "<!-- S5 JS -->"
 212       (concat
 213        "<script src='" dir
 214        "/default/slides.js' type='text/javascript'></script>")) "\n")))
 215
 216 (defun org-s5--build-meta-info (info)
 217   (concat
 218    (org-html--build-meta-info info)
 219    (format "<meta name=\"version\" content=\"S5 %s\" />\n"
 220            (plist-get info :s5-version))
 221    (format "<meta name='defaultView' content='%s' />\n"
 222            (plist-get info :s5-default-view))
 223    (format "<meta name='controlVis' content='%s' />"
 224            (plist-get info :s5-control-visibility))))
 225
 226 (defun org-s5-headline (headline contents info)
 227   (let ((org-html-toplevel-hlevel 1)
 228         (class (or (org-element-property :HTML_CONTAINER_CLASS headline) ""))
 229         (level (org-export-get-relative-level headline info)))
 230     (when (and (= 1 level) (not (string-match-p "\\<slide\\>" class)))
 231       (org-element-put-property headline :HTML_CONTAINER_CLASS (concat class " slide")))
 232     (org-html-headline headline contents info)))
 233
 234 (defun org-s5-plain-list (plain-list contents info)
 235   "Transcode a PLAIN-LIST element from Org to HTML.
 236 CONTENTS is the contents of the list.  INFO is a plist holding
 237 contextual information.
 238 If a containing headline has the property :INCREMENTAL,
 239 then the \"incremental\" class will be added to the to the list,
 240 which will make the list into a \"build\"."
 241   (let* ((type (org-element-property :type plain-list))
 242         (tag (case type
 243                (ordered "ol")
 244                (unordered "ul")
 245                (descriptive "dl"))))
 246     (format "%s\n%s%s"
 247             (format
 248              "<%s class='org-%s%s'>" tag tag
 249              (if (org-export-get-node-property :INCREMENTAL plain-list t)
 250                  " incremental" ""))
 251             contents (org-html-end-plain-list type))))
 252
 253 (defun org-s5-template-alist (info)
 254   `(
 255    ("title"  . ,(car (plist-get info :title)))
 256    ("author" . ,(car (plist-get info :author)))
 257    ("email"  . ,(plist-get info :email))
 258    ("date"   . ,(nth 0 (plist-get info :date)))
 259    ("file"   . ,(plist-get info :input-file))))
 260
 261 (defun org-s5-inner-template (contents info)
 262   "Return body of document string after HTML conversion.
 263 CONTENTS is the transcoded contents string.  INFO is a plist
 264 holding export options."
 265   (concat contents "\n"))
 266
 267 (defun org-s5-template (contents info)
 268   "Return complete document string after HTML conversion.
 269 CONTENTS is the transcoded contents string.  INFO is a plist
 270 holding export options."
 271   (mapconcat
 272    'identity
 273    (list
 274     "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Strict//EN\"
 275         \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd\">"
 276     (format "<html xmlns=\"http://www.w3.org/1999/xhtml\" lang=\"%s\" xml:lang=\"%s\">"
 277             (plist-get info :language) (plist-get info :language))
 278     "<head>"
 279     (org-s5--build-meta-info info)
 280     (org-s5--build-style info)
 281     (org-html--build-style info)
 282     (org-html--build-mathjax-config info)
 283     "</head>"
 284     "<body>"
 285     "<div class=\"layout\">"
 286     "<div id=\"controls\"><!-- no edit --></div>"
 287     "<div id=\"currentSlide\"><!-- no edit --></div>"
 288     (org-fill-template
 289      org-s5-header-template (org-s5-template-alist info))
 290     (org-fill-template
 291      org-s5-footer-template (org-s5-template-alist info))
 292     "</div>"
 293     (format "<div id=\"%s\" class=\"presentation\">" (nth 1 org-html-divs))
 294     ;; title page
 295     (org-fill-template
 296      org-s5-title-page-template (org-s5-template-alist info))
 297     ;; table of contents.
 298     (let ((depth (plist-get info :with-toc)))
 299       (when depth (org-s5-toc depth info)))
 300     contents
 301     "</div>"
 302     "</body>"
 303     "</html>\n") "\n"))
 304
 305 (defun org-s5-export-as-html
 306   (&optional async subtreep visible-only body-only ext-plist)
 307   "Export current buffer to an HTML buffer.
 308
 309 If narrowing is active in the current buffer, only export its
 310 narrowed part.
 311
 312 If a region is active, export that region.
 313
 314 A non-nil optional argument ASYNC means the process should happen
 315 asynchronously.  The resulting buffer should be accessible
 316 through the `org-export-stack' interface.
 317
 318 When optional argument SUBTREEP is non-nil, export the sub-tree
 319 at point, extracting information from the headline properties
 320 first.
 321
 322 When optional argument VISIBLE-ONLY is non-nil, don't export
 323 contents of hidden elements.
 324
 325 When optional argument BODY-ONLY is non-nil, only write code
 326 between \"<body>\" and \"</body>\" tags.
 327
 328 EXT-PLIST, when provided, is a property list with external
 329 parameters overriding Org default settings, but still inferior to
 330 file-local settings.
 331
 332 Export is done in a buffer named \"*Org S5 Export*\", which
 333 will be displayed when `org-export-show-temporary-export-buffer'
 334 is non-nil."
 335   (interactive)
 336   (if async
 337       (org-export-async-start
 338           (lambda (output)
 339             (with-current-buffer (get-buffer-create "*Org S5 Export*")
 340               (erase-buffer)
 341               (insert output)
 342               (goto-char (point-min))
 343               (nxml-mode)
 344               (org-export-add-to-stack (current-buffer) 's5)))
 345         `(org-export-as 's5 ,subtreep ,visible-only ,body-only ',ext-plist))
 346     (let ((outbuf (org-export-to-buffer
 347                    's5 "*Org S5 Export*"
 348                    subtreep visible-only body-only ext-plist)))
 349       ;; Set major mode.
 350       (with-current-buffer outbuf (nxml-mode))
 351       (when org-export-show-temporary-export-buffer
 352         (switch-to-buffer-other-window outbuf)))))
 353
 354 (defun org-s5-export-to-html
 355   (&optional async subtreep visible-only body-only ext-plist)
 356   "Export current buffer to a S5 HTML file.
 357
 358 If narrowing is active in the current buffer, only export its
 359 narrowed part.
 360
 361 If a region is active, export that region.
 362
 363 A non-nil optional argument ASYNC means the process should happen
 364 asynchronously.  The resulting file should be accessible through
 365 the `org-export-stack' interface.
 366
 367 When optional argument SUBTREEP is non-nil, export the sub-tree
 368 at point, extracting information from the headline properties
 369 first.
 370
 371 When optional argument VISIBLE-ONLY is non-nil, don't export
 372 contents of hidden elements.
 373
 374 When optional argument BODY-ONLY is non-nil, only write code
 375 between \"<body>\" and \"</body>\" tags.
 376
 377 EXT-PLIST, when provided, is a property list with external
 378 parameters overriding Org default settings, but still inferior to
 379 file-local settings.
 380
 381 Return output file's name."
 382   (interactive)
 383   (let* ((extension (concat "." org-html-extension))
 384          (file (org-export-output-file-name extension subtreep))
 385          (org-export-coding-system org-html-coding-system))
 386     (if async
 387         (org-export-async-start
 388             (lambda (f) (org-export-add-to-stack f 's5))
 389           (let ((org-export-coding-system org-html-coding-system))
 390             `(expand-file-name
 391               (org-export-to-file
 392                's5 ,file ,subtreep ,visible-only ,body-only ',ext-plist))))
 393       (let ((org-export-coding-system org-html-coding-system))
 394         (org-export-to-file
 395          's5 file subtreep visible-only body-only ext-plist)))))
 396
 397 (defun org-s5-publish-to-html (plist filename pub-dir)
 398   "Publish an org file to S5 HTML Presentation.
 399
 400 FILENAME is the filename of the Org file to be published.  PLIST
 401 is the property list for the given project.  PUB-DIR is the
 402 publishing directory.
 403
 404 Return output file name."
 405   (org-publish-org-to 's5 filename ".html" plist pub-dir))
 406
 407 (provide 'ox-s5)