contrib/lisp/ox-deck.el

   1 ;;; ox-deck.el --- deck.js Presentation Back-End for Org Export Engine
   2
   3 ;; Copyright (C) 2013, 2014  Rick Frankel
   4
   5 ;; Author: Rick Frankel <emacs at rickster dot com>
   6 ;; Keywords: outlines, hypermedia, slideshow
   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 a deck.js presentation back-end for the Org
  26 ;; generic exporter.
  27
  28 ;; Installation
  29 ;; -------------
  30 ;; Get a copy of deck.js from http://imakewebthings.com/deck.js/ or
  31 ;; the gitub repository at https://github.com/imakewebthings/deck.js.
  32 ;;
  33 ;; Add the path to the extracted code to the variable
  34 ;; `org-deck-directories' There are a number of customization in the
  35 ;; org-export-deck group, most of which can be overrriden with buffer
  36 ;; local customization (starting with DECK_.)
  37
  38 ;; See ox.el and ox-html.el for more details on how this exporter
  39 ;; works (it is derived from ox-html.)
  40
  41 (require 'ox-html)
  42 (eval-when-compile (require 'cl))
  43
  44 (org-export-define-derived-backend 'deck 'html
  45   :menu-entry
  46   '(?d "Export to deck.js HTML Presentation"
  47        ((?H "To temporary buffer" org-deck-export-as-html)
  48         (?h "To file" org-deck-export-to-html)
  49         (?o "To file and open"
  50             (lambda (a s v b)
  51               (if a (org-deck-export-to-html t s v b)
  52                 (org-open-file (org-deck-export-to-html nil s v b)))))))
  53   :options-alist
  54   '((:html-link-home "HTML_LINK_HOME" nil nil)
  55     (:html-link-up "HTML_LINK_UP" nil nil)
  56     (:deck-postamble "DECK_POSTAMBLE" nil org-deck-postamble newline)
  57     (:deck-preamble "DECK_PREAMBLE" nil org-deck-preamble newline)
  58     (:html-head-include-default-style "HTML_INCLUDE_DEFAULT_STYLE" "html-style" nil)
  59     (:html-head-include-scripts "HTML_INCLUDE_SCRIPTS" nil nil)
  60     (:deck-base-url "DECK_BASE_URL" nil org-deck-base-url)
  61     (:deck-theme "DECK_THEME" nil org-deck-theme)
  62     (:deck-transition "DECK_TRANSITION" nil org-deck-transition)
  63     (:deck-include-extensions "DECK_INCLUDE_EXTENSIONS" nil
  64                               org-deck-include-extensions split)
  65     (:deck-exclude-extensions "DECK_EXCLUDE_EXTENSIONS" nil
  66                               org-deck-exclude-extensions split))
  67   :translate-alist
  68   '((headline . org-deck-headline)
  69     (inner-template . org-deck-inner-template)
  70     (item . org-deck-item)
  71     (link . org-deck-link)
  72     (template . org-deck-template)))
  73
  74 (defgroup org-export-deck nil
  75   "Options for exporting Org mode files to deck.js HTML Presentations."
  76   :tag "Org Export DECK"
  77   :group 'org-export-html)
  78
  79 (defcustom org-deck-directories '("./deck.js")
  80   "Directories to search for deck.js components (jquery,
  81 modernizr; core, extensions and themes directories.)"
  82   :group 'org-export-deck
  83   :type '(repeat (string :tag "Directory")))
  84
  85 (defun org-deck--cleanup-components (components)
  86   (remove-duplicates
  87    (car (remove 'nil components))
  88    :test (lambda (x y)
  89            (string= (file-name-nondirectory x)
  90                     (file-name-nondirectory y)))))
  91
  92 (defun org-deck--find-extensions ()
  93   "Returns a unique list of all extensions found in
  94 in the extensions directories under `org-deck-directories'"
  95   (org-deck--cleanup-components
  96    (mapcar                              ; extensions under existing dirs
  97     (lambda (dir)
  98       (when (file-directory-p dir) (directory-files dir t "^[^.]")))
  99     (mapcar                           ; possible extension directories
 100      (lambda (x) (expand-file-name "extensions" x))
 101      org-deck-directories))))
 102
 103 (defun org-deck--find-css (type)
 104   "Return a unique list of all the css stylesheets in the themes/TYPE
 105 directories under `org-deck-directories'."
 106   (org-deck--cleanup-components
 107    (mapcar
 108     (lambda (dir)
 109       (let ((css-dir (expand-file-name
 110                       (concat (file-name-as-directory "themes") type) dir)))
 111         (when (file-directory-p css-dir)
 112           (directory-files css-dir t  "\\.css$"))))
 113     org-deck-directories)))
 114
 115 (defun org-deck-list-components ()
 116   "List all available deck extensions, styles and
 117 transitions (with full paths) to a temporary buffer."
 118   (interactive)
 119   (let ((outbuf (get-buffer-create "*deck.js Extensions*")))
 120     (with-current-buffer outbuf
 121       (erase-buffer)
 122       (insert "Extensions\n----------\n")
 123       (insert (mapconcat 'identity (org-deck--find-extensions) "\n"))
 124       (insert "\n\nStyles\n------\n")
 125       (insert (mapconcat 'identity (org-deck--find-css "style") "\n"))
 126       (insert "\n\nTransitions\n----------\n")
 127       (insert (mapconcat 'identity (org-deck--find-css "transition") "\n")))
 128     (switch-to-buffer-other-window outbuf)))
 129
 130 (defcustom org-deck-include-extensions nil
 131   "If non-nil, list of extensions to include instead of all available.
 132 Can be overriden or set with the DECK_INCLUDE_EXTENSIONS property.
 133 During output generation, the extensions found by
 134 `org-deck--find-extensions' are searched for the appropriate
 135 files (scripts and/or stylesheets) to include in the generated
 136 html. The href/src attributes are created relative to `org-deck-base-url'."
 137   :group 'org-export-deck
 138   :type '(repeat (string :tag "Extension")))
 139
 140 (defcustom org-deck-exclude-extensions nil
 141   "If non-nil, list of extensions to exclude.
 142 Can be overriden or set with the DECK_EXCLUDE_EXTENSIONS property."
 143   :group 'org-export-deck
 144   :type '(repeat (string :tag "Extension")))
 145
 146 (defcustom org-deck-theme "swiss.css"
 147   "deck.js theme. Can be overriden with the DECK_THEME property.
 148 If this value contains a path component (\"/\"), it is used as a
 149 literal path (url). Otherwise it is prepended with
 150 `org-deck-base-url'/themes/style/."
 151   :group 'org-export-deck
 152   :type 'string)
 153
 154 (defcustom org-deck-transition "fade.css"
 155   "deck.js transition theme. Can be overriden with the
 156 DECK_TRANSITION property.
 157 If this value contains a path component (\"/\"), it is used as a
 158 literal path (url). Otherwise it is prepended with
 159 `org-deck-base-url'/themes/transition/."
 160   :group 'org-export-deck
 161   :type 'string)
 162
 163 (defcustom org-deck-base-url "deck.js"
 164   "Url prefix to deck.js base directory containing the core, extensions
 165 and themes directories.
 166 Can be overriden with the DECK_BASE_URL property."
 167   :group 'org-export-deck
 168   :type 'string)
 169
 170 (defvar org-deck-pre/postamble-styles
 171   `((both "left: 5px; width: 100%;")
 172     (preamble "position: absolute; top: 10px;")
 173     (postamble ""))
 174   "Alist of css styles for the preamble, postamble and both respectively.
 175 Can be overriden in `org-deck-styles'. See also `org-html-divs'.")
 176
 177 (defcustom org-deck-postamble "<h1>%a - %t</h1>"
 178   "Non-nil means insert a postamble in HTML export.
 179
 180 When set to a string, use this string
 181 as the postamble.  When t, insert a string as defined by the
 182 formatting string in `org-html-postamble-format'.
 183
 184 When set to a function, apply this function and insert the
 185 returned string.  The function takes the property list of export
 186 options as its only argument.
 187
 188 This is included in the document at the bottom of the content
 189 section, and uses the postamble element and id from
 190 `org-html-divs'. The default places the author and presentation
 191 title at the bottom of each slide.
 192
 193 The css styling is controlled by `org-deck-pre/postamble-styles'.
 194
 195 Setting :deck-postamble in publishing projects will take
 196 precedence over this variable."
 197   :group 'org-export-deck
 198   :type '(choice (const :tag "No postamble" nil)
 199                  (const :tag "Default formatting string" t)
 200                  (string :tag "Custom formatting string")
 201                  (function :tag "Function (must return a string)")))
 202
 203 (defcustom org-deck-preamble nil
 204   "Non-nil means insert a preamble in HTML export.
 205
 206 When set to a string, use this string
 207 as the preamble.  When t, insert a string as defined by the
 208 formatting string in `org-html-preamble-format'.
 209
 210 When set to a function, apply this function and insert the
 211 returned string.  The function takes the property list of export
 212 options as its only argument.
 213
 214 This is included in the document at the top of  content section, and
 215 uses the preamble element and id from `org-html-divs'. The css
 216 styling is controlled by `org-deck-pre/postamble-styles'.
 217
 218 Setting :deck-preamble in publishing projects will take
 219 precedence over this variable."
 220   :group 'org-export-deck
 221   :type '(choice (const :tag "No preamble" nil)
 222                  (const :tag "Default formatting string" t)
 223                  (string :tag "Custom formatting string")
 224                  (function :tag "Function (must return a string)")))
 225
 226 (defvar org-deck-toc-styles
 227   (mapconcat
 228    'identity
 229    (list
 230     "#table-of-contents a {color: inherit;}"
 231     "#table-of-contents ul {margin-bottom: 0;}"
 232     "#table-of-contents li {padding: 0;}") "\n")
 233   "Default css styles used for formatting a table of contents slide.
 234 Can be overriden in `org-deck-styles'.
 235 Note that when the headline numbering option is true, a \"list-style: none\"
 236 is automatically added to avoid both numbers and bullets on the toc entries.")
 237
 238 (defcustom org-deck-styles
 239   "
 240 #title-slide h1 {
 241     position: static; padding: 0;
 242     margin-top: 10%;
 243     -webkit-transform: none;
 244     -moz-transform: none;
 245     -ms-transform: none;
 246     -o-transform: none;
 247     transform: none;
 248 }
 249 #title-slide h2 {
 250     text-align: center;
 251     border:none;
 252     padding: 0;
 253     margin: 0;
 254 }"
 255   "Deck specific CSS styles to include in exported html.
 256 Defaults to styles for the title page."
 257   :group 'org-export-deck
 258   :type 'string)
 259
 260 (defcustom org-deck-title-slide-template
 261   "<h1>%t</h1>
 262 <h2>%a</h2>
 263 <h2>%e</h2>
 264 <h2>%d</h2>"
 265   "Format template to specify title page section.
 266 See `org-html-postamble-format' for the valid elements which
 267 can be included.
 268
 269 It will be wrapped in the element defined in the :html-container
 270 property, and defaults to the value of `org-html-container-element',
 271 and have the id \"title-slide\"."
 272   :group 'org-export-deck
 273   :type 'string)
 274
 275 (defun org-deck-toc (depth info)
 276   (concat
 277    (format "<%s id='table-of-contents' class='slide'>\n"
 278            (plist-get info :html-container))
 279    (format "<h2>%s</h2>\n" (org-html--translate "Table of Contents" info))
 280    (org-html--toc-text
 281     (mapcar
 282      (lambda (headline)
 283        (let* ((class (org-element-property :HTML_CONTAINER_CLASS headline))
 284               (section-number
 285                (when
 286                    (and (not (org-export-low-level-p headline info))
 287                         (org-export-numbered-headline-p headline info))
 288                  (concat
 289                   (mapconcat
 290                    'number-to-string
 291                    (org-export-get-headline-number headline info) ".") ". ")))
 292               (title
 293                (concat
 294                 section-number
 295                 (replace-regexp-in-string ; remove any links in headline...
 296                  "</?a[^>]*>" ""
 297                  (org-export-data
 298                   (org-element-property :title headline) info)))))
 299          (cons
 300           (if (and class (string-match-p "\\<slide\\>" class))
 301               (format
 302                "<a href='#outline-container-%s'>%s</a>"
 303                (or (org-element-property :CUSTOM_ID headline)
 304                    (concat
 305                     "sec-"
 306                     (mapconcat
 307                      'number-to-string
 308                      (org-export-get-headline-number headline info) "-")))
 309                title)
 310             title)
 311           (org-export-get-relative-level headline info))))
 312      (org-export-collect-headlines info depth)))
 313    (format "</%s>\n" (plist-get info :html-container))))
 314
 315 (defun org-deck--get-packages (info)
 316   (let ((prefix (concat (plist-get info :deck-base-url) "/"))
 317         (theme (plist-get info :deck-theme))
 318         (transition (plist-get info :deck-transition))
 319         (include (plist-get info :deck-include-extensions))
 320         (exclude (plist-get info :deck-exclude-extensions))
 321         (scripts '()) (sheets '()) (snippets '()))
 322     (add-to-list 'scripts (concat prefix "jquery.min.js"))
 323     (add-to-list 'scripts (concat prefix "core/deck.core.js"))
 324     (add-to-list 'scripts (concat prefix "modernizr.custom.js"))
 325     (add-to-list 'sheets  (concat prefix "core/deck.core.css"))
 326     (mapc
 327      (lambda (extdir)
 328        (let* ((name (file-name-nondirectory extdir))
 329               (dir (file-name-as-directory extdir))
 330               (path (concat prefix "extensions/" name "/"))
 331               (base (format "deck.%s." name)))
 332          (when (and (or (eq nil include) (member name include))
 333                     (not (member name exclude)))
 334            (when (file-exists-p (concat dir base "js"))
 335              (add-to-list 'scripts (concat path base "js")))
 336            (when (file-exists-p (concat dir base "css"))
 337              (add-to-list 'sheets (concat path base "css")))
 338            (when (file-exists-p (concat dir base "html"))
 339              (add-to-list 'snippets (concat dir base "html"))))))
 340      (org-deck--find-extensions))
 341     (if (not (string-match-p "^[[:space:]]*$" theme))
 342         (add-to-list 'sheets
 343                      (if (file-name-directory theme) theme
 344                        (format "%sthemes/style/%s" prefix theme))))
 345     (if (not (string-match-p "^[[:space:]]*$" transition))
 346         (add-to-list
 347          'sheets
 348          (if (file-name-directory transition) transition
 349            (format "%sthemes/transition/%s" prefix transition))))
 350     (list :scripts (nreverse scripts) :sheets (nreverse sheets)
 351           :snippets snippets)))
 352
 353 (defun org-deck-inner-template (contents info)
 354   "Return body of document string after HTML conversion.
 355 CONTENTS is the transcoded contents string.  INFO is a plist
 356 holding export options."
 357   (concat contents "\n"))
 358
 359 (defun org-deck-headline (headline contents info)
 360   (let ((org-html-toplevel-hlevel 2)
 361         (class (or (org-element-property :HTML_CONTAINER_CLASS headline) ""))
 362         (level (org-export-get-relative-level headline info)))
 363     (when (and (= 1 level) (not (string-match-p "\\<slide\\>" class)))
 364       (org-element-put-property headline :HTML_CONTAINER_CLASS (concat class " slide")))
 365     (org-html-headline headline contents info)))
 366
 367 (defun org-deck-item (item contents info)
 368   "Transcode an ITEM element from Org to HTML.
 369 CONTENTS holds the contents of the item.  INFO is a plist holding
 370 contextual information.
 371 If the containing headline has the property :STEP, then
 372 the \"slide\" class will be added to the to the list element,
 373  which will make the list into a \"build\"."
 374   (let ((text (org-html-item item contents info)))
 375     (if (org-export-get-node-property :STEP item t)
 376         (replace-regexp-in-string "^<li>" "<li class='slide'>" text)
 377       text)))
 378
 379 (defun org-deck-link (link desc info)
 380   (replace-regexp-in-string "href=\"#" "href=\"#outline-container-"
 381                             (org-html-link link desc info)))
 382
 383 (defun org-deck-template (contents info)
 384   "Return complete document string after HTML conversion.
 385 CONTENTS is the transcoded contents string.  INFO is a plist
 386 holding export options."
 387   (let ((pkg-info (org-deck--get-packages info))
 388         (org-html--pre/postamble-class "deck-status")
 389         (info (plist-put
 390                (plist-put info :html-preamble (plist-get info :deck-preamble))
 391                :html-postamble (plist-get info :deck-postamble))))
 392     (mapconcat
 393      'identity
 394      (list
 395       (org-html-doctype info)
 396       (let ((lang (plist-get info :language)))
 397         (mapconcat
 398          (lambda (x)
 399            (apply
 400             'format
 401             "<!--%s <html %s lang='%s' xmlns='http://www.w3.org/1999/xhtml'> %s<![endif]-->"
 402             x))
 403          (list `("[if lt IE 7]>" "class='no-js ie6'" ,lang "")
 404                `("[if IE 7]>" "class='no-js ie7'" ,lang "")
 405                `("[if IE 8]>" "class='no-js ie8'" ,lang "")
 406                `("[if gt IE 8]><!-->" "" ,lang "<!--")) "\n"))
 407       "<head>"
 408       (org-deck--build-meta-info info)
 409       (mapconcat
 410        (lambda (sheet)
 411          (format
 412           "<link rel='stylesheet' href='%s' type='text/css' />" sheet))
 413        (plist-get pkg-info :sheets) "\n")
 414       (mapconcat
 415        (lambda (script)
 416          (format
 417           "<script src='%s' type='text/javascript'></script>" script))
 418        (plist-get pkg-info :scripts) "\n")
 419       (org-html--build-mathjax-config info)
 420       "<script type='text/javascript'>"
 421       "  $(document).ready(function () { $.deck('.slide'); });"
 422       "</script>"
 423       (org-html--build-head info)
 424       "<style type='text/css'>"
 425       org-deck-toc-styles
 426       (when (plist-get info :section-numbers)
 427         "#table-of-contents ul li {list-style-type: none;}")
 428       (format "#%s, #%s {%s}"
 429               (nth 2 (assq 'preamble org-html-divs))
 430               (nth 2 (assq 'postamble org-html-divs))
 431               (nth 1 (assq 'both org-deck-pre/postamble-styles)))
 432       (format "#%s {%s}"
 433               (nth 2 (assq 'preamble org-html-divs))
 434               (nth 1 (assq 'preamble org-deck-pre/postamble-styles)))
 435       (format "#%s {%s}"
 436               (nth 2 (assq 'postamble org-html-divs))
 437               (nth 1 (assq 'postamble org-deck-pre/postamble-styles)))
 438       org-deck-styles
 439       "</style>"
 440       "</head>"
 441       "<body>"
 442       (format "<%s id='%s' class='deck-container'>"
 443               (nth 1 (assq 'content org-html-divs))
 444               (nth 2 (assq 'content org-html-divs)))
 445       (org-html--build-pre/postamble 'preamble info)
 446       ;; title page
 447       (format "<%s id='title-slide' class='slide'>"
 448               (plist-get info :html-container))
 449       (format-spec org-deck-title-slide-template (org-html-format-spec info))
 450       (format "</%s>" (plist-get info :html-container))
 451       ;; toc page
 452       (let ((depth (plist-get info :with-toc)))
 453         (when depth (org-deck-toc depth info)))
 454       contents
 455       (mapconcat
 456        (lambda (snippet)
 457          (with-temp-buffer (insert-file-contents snippet)
 458                            (buffer-string)))
 459        (plist-get pkg-info :snippets) "\n")
 460       (org-html--build-pre/postamble 'postamble info)
 461       (format "</%s>" (nth 1 (assq 'content org-html-divs)))
 462       "</body>"
 463       "</html>\n") "\n")))
 464
 465 (defun org-deck--build-meta-info (info)
 466   "Return meta tags for exported document.
 467 INFO is a plist used as a communication channel."
 468   (let* ((title (org-export-data (plist-get info :title) info))
 469          (author (and (plist-get info :with-author)
 470                       (let ((auth (plist-get info :author)))
 471                         (and auth (org-export-data auth info)))))
 472          (date (and (plist-get info :with-date)
 473                     (let ((date (org-export-get-date info)))
 474                       (and date (org-export-data date info)))))
 475          (description (plist-get info :description))
 476          (keywords (plist-get info :keywords)))
 477     (mapconcat
 478      'identity
 479      (list
 480       (format "<title>%s</title>" title)
 481       (format "<meta http-equiv='Content-Type' content='text/html; charset=%s'/>"
 482               (or (and org-html-coding-system
 483                        (fboundp 'coding-system-get)
 484                        (coding-system-get
 485                         org-html-coding-system 'mime-charset))
 486                   "iso-8859-1"))
 487       (mapconcat
 488        (lambda (attr)
 489          (when (< 0 (length (car attr)))
 490            (format "<meta name='%s' content='%s'/>\n"
 491                    (nth 1 attr) (car attr))))
 492        (list '("Org-mode" "generator")
 493              `(,author "author")
 494              `(,description "description")
 495              `(,keywords "keywords")) "")) "\n")))
 496 (defun org-deck-export-as-html
 497   (&optional async subtreep visible-only body-only ext-plist)
 498   "Export current buffer to an HTML buffer.
 499
 500 If narrowing is active in the current buffer, only export its
 501 narrowed part.
 502
 503 If a region is active, export that region.
 504
 505 A non-nil optional argument ASYNC means the process should happen
 506 asynchronously.  The resulting buffer should be accessible
 507 through the `org-export-stack' interface.
 508
 509 When optional argument SUBTREEP is non-nil, export the sub-tree
 510 at point, extracting information from the headline properties
 511 first.
 512
 513 When optional argument VISIBLE-ONLY is non-nil, don't export
 514 contents of hidden elements.
 515
 516 When optional argument BODY-ONLY is non-nil, only write code
 517 between \"<body>\" and \"</body>\" tags.
 518
 519 EXT-PLIST, when provided, is a property list with external
 520 parameters overriding Org default settings, but still inferior to
 521 file-local settings.
 522
 523 Export is done in a buffer named \"*Org deck.js Export*\", which
 524 will be displayed when `org-export-show-temporary-export-buffer'
 525 is non-nil."
 526   (interactive)
 527   (org-export-to-buffer 'deck "*Org deck.js Export*"
 528     async subtreep visible-only body-only ext-plist (lambda () (nxml-mode))))
 529
 530 (defun org-deck-export-to-html
 531   (&optional async subtreep visible-only body-only ext-plist)
 532   "Export current buffer to a deck.js HTML file.
 533
 534 If narrowing is active in the current buffer, only export its
 535 narrowed part.
 536
 537 If a region is active, export that region.
 538
 539 A non-nil optional argument ASYNC means the process should happen
 540 asynchronously.  The resulting file should be accessible through
 541 the `org-export-stack' interface.
 542
 543 When optional argument SUBTREEP is non-nil, export the sub-tree
 544 at point, extracting information from the headline properties
 545 first.
 546
 547 When optional argument VISIBLE-ONLY is non-nil, don't export
 548 contents of hidden elements.
 549
 550 When optional argument BODY-ONLY is non-nil, only write code
 551 between \"<body>\" and \"</body>\" tags.
 552
 553 EXT-PLIST, when provided, is a property list with external
 554 parameters overriding Org default settings, but still inferior to
 555 file-local settings.
 556
 557 Return output file's name."
 558   (interactive)
 559   (let* ((extension (concat "." org-html-extension))
 560          (file (org-export-output-file-name extension subtreep))
 561          (org-export-coding-system org-html-coding-system))
 562     (org-export-to-file 'deck file
 563       async subtreep visible-only body-only ext-plist)))
 564
 565 (defun org-deck-publish-to-html (plist filename pub-dir)
 566   "Publish an org file to deck.js HTML Presentation.
 567 FILENAME is the filename of the Org file to be published.  PLIST
 568 is the property list for the given project.  PUB-DIR is the
 569 publishing directory. Returns output file name."
 570   (org-publish-org-to 'deck filename ".html" plist pub-dir))
 571
 572 (provide 'ox-deck)
 573
 574 ;;; ox-deck.el ends here