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    (template . org-s5-template)))
  78
  79 (defgroup org-export-s5 nil
  80   "Options for exporting Org mode files to S5 HTML Presentations."
  81   :tag "Org Export S5"
  82   :group 'org-export-html)
  83
  84 (defcustom org-s5-version "1.2a2"
  85   "Version of s5 being used (for version metadata.) Defaults to
  86 s5 v2 alpha 2.
  87 Can be overridden with S5_VERSION."
  88   :group 'org-export-s5
  89   :type 'string)
  90
  91 (defcustom org-s5-theme-file nil
  92 "Url to S5 theme (slides.css) file. Can be overriden with the
  93 S5_THEME_FILE property. If nil, defaults to
  94 `org-s5-ui-url'/default/slides.css. If it starts with anything but
  95 \"http\" or \"/\", it is used as-is. Otherwise the link in generated
  96 relative to `org-s5-ui-url'.
  97 The links for all other required stylesheets and scripts will be
  98 generated relative to `org-s5-ui-url'/default."
  99   :group 'org-export-s5
 100   :type 'string)
 101
 102 (defcustom org-s5-ui-url "ui"
 103   "Base url to directory containing S5 \"default\" subdirectory
 104 and the \"s5-notes.html\" file.
 105 Can be overriden with the S5_UI_URL property."
 106   :group 'org-export-s5
 107   :type 'string)
 108
 109 (defcustom org-s5-default-view 'slideshow
 110   "Setting for \"defaultView\" meta info."
 111   :group 'org-export-s5
 112   :type '(choice (const slideshow) (const outline)))
 113
 114 (defcustom org-s5-control-visibility 'hidden
 115   "Setting for \"controlVis\" meta info."
 116   :group 'org-export-s5
 117   :type '(choice (const hidden) (const visibile)))
 118
 119 (defcustom org-s5-footer-template
 120   "<div id=\"footer\">
 121 <h1>%author - %title</h1>
 122 </div>"
 123   "Format template to specify footer div. Completed using
 124 `org-fill-template'.
 125 Optional keys include %author, %email, %file, %title and %date.
 126 Note that the div id must be \"footer\"."
 127   :group 'org-export-s5
 128   :type 'string)
 129
 130 (defcustom org-s5-header-template "<div id=\"header\"></div>"
 131   "Format template to specify footer div. Completed using
 132 `org-fill-template'.
 133 Optional keys include %author, %email, %file, %title and %date.
 134 Note that the div id must be \"header\"."
 135   :group 'org-export-s5
 136   :type 'string)
 137
 138 (defcustom org-s5-title-page-template
 139   "<div class=\"slide title-page\">
 140 <h1>%title</h1>
 141 <h1>%author</h1>
 142 <h1>%email</h1>
 143 <h1>%date</h1>
 144 </div>"
 145   "Format template to specify title page div. Completed using
 146 `org-fill-template'.
 147 Optional keys include %author, %email, %file, %title and %date.
 148 Note that the wrapper div must include the class \"slide\"."
 149   :group 'org-export-s5
 150   :type 'string)
 151
 152
 153 (defun org-s5-toc (depth info)
 154   (let* ((headlines (org-export-collect-headlines info depth))
 155          (toc-entries
 156           (loop for headline in headlines collect
 157                 (list (org-html-format-headline--wrap
 158                        headline info 'org-html-format-toc-headline)
 159                       (org-export-get-relative-level headline info)))))
 160     (when toc-entries
 161       (concat
 162        "<div id=\"table-of-contents\" class=\"slide\">\n"
 163        (format "<h1>%s</h1>\n"
 164                (org-html--translate "Table of Contents" info))
 165        "<div id=\"text-table-of-contents\">"
 166        (org-html-toc-text toc-entries)
 167        "</div>\n"
 168        "</div>\n"))))
 169
 170 (defun org-s5--build-style (info)
 171   (let* ((dir (plist-get info :s5-ui-url))
 172          (theme (or (plist-get info :s5-theme-file) "default/slides.css")))
 173     (mapconcat
 174      'identity
 175      (list
 176       "<!-- style sheet links -->"
 177       (mapconcat
 178        (lambda (list)
 179          (format
 180           (concat
 181            "<link rel='stylesheet' href='%s/default/%s' type='text/css'"
 182            " media='%s' id='%s' />")
 183           dir (nth 0 list) (nth 1 list) (nth 2 list)))
 184        (list
 185         '("outline.css" "screen" "outlineStyle")
 186         '("print.css" "print" "slidePrint")
 187         '("opera.css" "projection" "operaFix")) "\n")
 188       (format (concat
 189                "<link rel='stylesheet' href='%s' type='text/css'"
 190                " media='screen' id='slideProj' />")
 191               (if (string-match-p "^\\(http\\|/\\)" theme) theme
 192                 (concat dir "/" theme)))
 193       "<!-- S5 JS -->"
 194       (concat
 195        "<script src='" dir
 196        "/default/slides.js' type='text/javascript'></script>")) "\n")))
 197
 198 (defun org-s5--build-meta-info (info)
 199   (concat
 200    (org-html--build-meta-info info)
 201    (format "<meta name=\"version\" content=\"S5 %s\" />\n"
 202            (plist-get info :s5-version))
 203    (format "<meta name='defaultView' content='%s' />\n"
 204            (plist-get info :s5-default-view))
 205    (format "<meta name='controlVis' content='%s' />"
 206            (plist-get info :s5-control-visibility))))
 207
 208 (defun org-s5-headline (headline contents info)
 209   (let ((org-html-toplevel-hlevel 1)
 210         (class (or (org-element-property :HTML_CONTAINER_CLASS headline) ""))
 211         (level (org-export-get-relative-level headline info)))
 212     (when (and (= 1 level) (not (string-match-p "\\<slide\\>" class)))
 213       (org-element-put-property headline :HTML_CONTAINER_CLASS (concat class " slide")))
 214     (org-html-headline headline contents info)))
 215
 216 (defun org-s5-plain-list (plain-list contents info)
 217   "Transcode a PLAIN-LIST element from Org to HTML.
 218 CONTENTS is the contents of the list.  INFO is a plist holding
 219 contextual information.
 220 If a containing headline has the property :INCREMENTAL,
 221 then the \"incremental\" class will be added to the to the list,
 222 which will make the list into a \"build\"."
 223   (let* ((type (org-element-property :type plain-list))
 224         (tag (case type
 225                (ordered "ol")
 226                (unordered "ul")
 227                (descriptive "dl"))))
 228     (format "%s\n%s%s"
 229             (format
 230              "<%s class='org-%s%s'>" tag tag
 231              (if (org-export-get-node-property :INCREMENTAL plain-list t)
 232                  " incremental" ""))
 233             contents (org-html-end-plain-list type))))
 234
 235 (defun org-s5-template-alist (info)
 236   `(
 237    ("title"  . ,(car (plist-get info :title)))
 238    ("author" . ,(car (plist-get info :author)))
 239    ("email"  . ,(plist-get info :email))
 240    ("date"   . ,(nth 0 (plist-get info :date)))
 241    ("file"   . ,(plist-get info :input-file))))
 242
 243 (defun org-s5-template (contents info)
 244   "Return complete document string after HTML conversion.
 245 CONTENTS is the transcoded contents string.  INFO is a plist
 246 holding export options."
 247   (mapconcat
 248    'identity
 249    (list
 250     "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Strict//EN\"
 251         \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd\">"
 252     (format "<html xmlns=\"http://www.w3.org/1999/xhtml\" lang=\"%s\" xml:lang=\"%s\">"
 253             (plist-get info :language) (plist-get info :language))
 254     "<head>"
 255     (org-s5--build-meta-info info)
 256     (org-s5--build-style info)
 257     (org-html--build-style info)
 258     (org-html--build-mathjax-config info)
 259     "</head>"
 260     "<body>"
 261     "<div class=\"layout\">"
 262     "<div id=\"controls\"><!-- no edit --></div>"
 263     "<div id=\"currentSlide\"><!-- no edit --></div>"
 264     (org-fill-template
 265      org-s5-header-template (org-s5-template-alist info))
 266     (org-fill-template
 267      org-s5-footer-template (org-s5-template-alist info))
 268     "</div>"
 269     (format "<div id=\"%s\" class=\"presentation\">" (nth 1 org-html-divs))
 270     ;; title page
 271     (org-fill-template
 272      org-s5-title-page-template (org-s5-template-alist info))
 273     (let ((depth (plist-get info :with-toc)))
 274       (when depth (org-s5-toc depth info)))
 275     contents
 276     "</div>"
 277     "</body>"
 278     "</html>\n") "\n"))
 279
 280 (defun org-s5-export-as-html
 281   (&optional async subtreep visible-only body-only ext-plist)
 282   "Export current buffer to an HTML buffer.
 283
 284 If narrowing is active in the current buffer, only export its
 285 narrowed part.
 286
 287 If a region is active, export that region.
 288
 289 A non-nil optional argument ASYNC means the process should happen
 290 asynchronously.  The resulting buffer should be accessible
 291 through the `org-export-stack' interface.
 292
 293 When optional argument SUBTREEP is non-nil, export the sub-tree
 294 at point, extracting information from the headline properties
 295 first.
 296
 297 When optional argument VISIBLE-ONLY is non-nil, don't export
 298 contents of hidden elements.
 299
 300 When optional argument BODY-ONLY is non-nil, only write code
 301 between \"<body>\" and \"</body>\" tags.
 302
 303 EXT-PLIST, when provided, is a property list with external
 304 parameters overriding Org default settings, but still inferior to
 305 file-local settings.
 306
 307 Export is done in a buffer named \"*Org S5 Export*\", which
 308 will be displayed when `org-export-show-temporary-export-buffer'
 309 is non-nil."
 310   (interactive)
 311   (if async
 312       (org-export-async-start
 313           (lambda (output)
 314             (with-current-buffer (get-buffer-create "*Org S5 Export*")
 315               (erase-buffer)
 316               (insert output)
 317               (goto-char (point-min))
 318               (nxml-mode)
 319               (org-export-add-to-stack (current-buffer) 's5)))
 320         `(org-export-as 's5 ,subtreep ,visible-only ,body-only ',ext-plist))
 321     (let ((outbuf (org-export-to-buffer
 322                    's5 "*Org S5 Export*"
 323                    subtreep visible-only body-only ext-plist)))
 324       ;; Set major mode.
 325       (with-current-buffer outbuf (nxml-mode))
 326       (when org-export-show-temporary-export-buffer
 327         (switch-to-buffer-other-window outbuf)))))
 328
 329 (defun org-s5-export-to-html
 330   (&optional async subtreep visible-only body-only ext-plist)
 331   "Export current buffer to a S5 HTML file.
 332
 333 If narrowing is active in the current buffer, only export its
 334 narrowed part.
 335
 336 If a region is active, export that region.
 337
 338 A non-nil optional argument ASYNC means the process should happen
 339 asynchronously.  The resulting file should be accessible through
 340 the `org-export-stack' interface.
 341
 342 When optional argument SUBTREEP is non-nil, export the sub-tree
 343 at point, extracting information from the headline properties
 344 first.
 345
 346 When optional argument VISIBLE-ONLY is non-nil, don't export
 347 contents of hidden elements.
 348
 349 When optional argument BODY-ONLY is non-nil, only write code
 350 between \"<body>\" and \"</body>\" tags.
 351
 352 EXT-PLIST, when provided, is a property list with external
 353 parameters overriding Org default settings, but still inferior to
 354 file-local settings.
 355
 356 Return output file's name."
 357   (interactive)
 358   (let* ((extension (concat "." org-html-extension))
 359          (file (org-export-output-file-name extension subtreep))
 360          (org-export-coding-system org-html-coding-system))
 361     (if async
 362         (org-export-async-start
 363             (lambda (f) (org-export-add-to-stack f 's5))
 364           (let ((org-export-coding-system org-html-coding-system))
 365             `(expand-file-name
 366               (org-export-to-file
 367                's5 ,file ,subtreep ,visible-only ,body-only ',ext-plist))))
 368       (let ((org-export-coding-system org-html-coding-system))
 369         (org-export-to-file
 370          's5 file subtreep visible-only body-only ext-plist)))))
 371
 372 (defun org-s5-publish-to-html (plist filename pub-dir)
 373   "Publish an org file to S5 HTML Presentation.
 374
 375 FILENAME is the filename of the Org file to be published.  PLIST
 376 is the property list for the given project.  PUB-DIR is the
 377 publishing directory.
 378
 379 Return output file name."
 380   (org-publish-org-to 's5 filename ".html" plist pub-dir))
 381
 382 (provide 'ox-s5)