contrib/lisp/ox-confluence.el

   1 ;;; ox-confluence --- Confluence Wiki Back-End for Org Export Engine
   2
   3 ;; Copyright (C) 2012, 2014 Sébastien Delafond
   4
   5 ;; Author: Sébastien Delafond <sdelafond@gmail.com>
   6 ;; Keywords: outlines, confluence, wiki
   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 GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
  22
  23 ;;; Commentary:
  24 ;;
  25 ;; ox-confluence.el lets you convert Org files to confluence files
  26 ;; using the ox.el export engine.
  27 ;;
  28 ;; Put this file into your load-path and the following into your ~/.emacs:
  29 ;;       (require 'ox-confluence)
  30 ;;
  31 ;; Export Org files to confluence:
  32 ;; M-x org-confluence-export-as-confluence RET
  33 ;;
  34 ;;; Code:
  35
  36 (require 'ox)
  37 (require 'ox-ascii)
  38
  39 ;; Define the backend itself
  40 (org-export-define-derived-backend 'confluence 'ascii
  41   :translate-alist '((bold . org-confluence-bold)
  42                      (example-block . org-confluence-example-block)
  43                      (fixed-width . org-confluence-fixed-width)
  44                      (footnote-definition . org-confluence-empty)
  45                      (footnote-reference . org-confluence-empty)
  46                      (headline . org-confluence-headline)
  47                      (italic . org-confluence-italic)
  48                      (item . org-confluence-item)
  49                      (link . org-confluence-link)
  50                      (paragraph . org-confluence-paragraph)
  51                      (property-drawer . org-confluence-property-drawer)
  52                      (section . org-confluence-section)
  53                      (src-block . org-confluence-src-block)
  54                      (strike-through . org-confluence-strike-through)
  55                      (table . org-confluence-table)
  56                      (table-cell . org-confluence-table-cell)
  57                      (table-row . org-confluence-table-row)
  58                      (template . org-confluence-template)
  59                      (timestamp . org-confluence-timestamp)
  60                      (underline . org-confluence-underline)))
  61
  62 (defcustom org-confluence-lang-alist
  63   '(("sh" . "bash"))
  64   "Map from org-babel language name to confluence wiki language name"
  65   :type '(alist :key-type string :value-type string))
  66
  67 ;; All the functions we use
  68 (defun org-confluence-bold (bold contents info)
  69   (format "*%s*" contents))
  70
  71 (defun org-confluence-empty (empty contents info)
  72   "")
  73
  74 (defun org-confluence-example-block (example-block contents info)
  75   ;; FIXME: provide a user-controlled variable for theme
  76   (let ((content (org-export-format-code-default example-block info)))
  77     (org-confluence--block "none" "Confluence" content)))
  78
  79 (defun org-confluence-italic (italic contents info)
  80   (format "_%s_" contents))
  81
  82 (defun org-confluence-item (item contents info)
  83   (concat (make-string (1+ (org-confluence--li-depth item)) ?\-)
  84           " "
  85           (org-trim contents)))
  86
  87 (defun org-confluence-fixed-width (fixed-width contents info)
  88   (format "\{\{%s\}\}" contents))
  89
  90 (defun org-confluence-headline (headline contents info)
  91   (let* ((low-level-rank (org-export-low-level-p headline info))
  92          (text (org-export-data (org-element-property :title headline)
  93                                 info))
  94          (todo (org-export-data (org-element-property :todo-keyword headline)
  95                                 info))
  96          (level (org-export-get-relative-level headline info))
  97          (todo-text (if (or (not (plist-get info :with-todo-keywords))
  98                             (string= todo ""))
  99                         ""
 100                       (format "*{{%s}}* " todo))))
 101     ;; Else: Standard headline.
 102     (format "h%s. %s%s\n%s" level todo-text text
 103             (if (org-string-nw-p contents) contents ""))))
 104
 105 (defun org-confluence-link (link desc info)
 106   (let ((raw-link (org-element-property :raw-link link)))
 107     (concat "["
 108             (when (org-string-nw-p desc) (format "%s|" desc))
 109             (cond
 110              ((string-match "^confluence:" raw-link)
 111               (replace-regexp-in-string "^confluence:" "" raw-link))
 112              (t
 113               raw-link))
 114             "]")))
 115
 116 (defun org-confluence-paragraph (paragraph contents info)
 117   "Transcode PARAGRAPH element for Confluence.
 118 CONTENTS is the paragraph contents.  INFO is a plist used as
 119 a communication channel."
 120   contents)
 121
 122 (defun org-confluence-property-drawer (property-drawer contents info)
 123   (and (org-string-nw-p contents)
 124        (format "\{\{%s\}\}" contents)))
 125
 126 (defun org-confluence-section (section contents info)
 127   contents)
 128
 129 (defun org-confluence-src-block (src-block contents info)
 130   ;; FIXME: provide a user-controlled variable for theme
 131   (let* ((lang (org-element-property :language src-block))
 132          (language (or (cdr (assoc lang org-confluence-lang-alist)) lang))
 133          (content (org-export-format-code-default src-block info)))
 134     (org-confluence--block language "Emacs" content)))
 135
 136 (defun org-confluence-strike-through (strike-through contents info)
 137   (format "-%s-" contents))
 138
 139 (defun org-confluence-table (table contents info)
 140   contents)
 141
 142 (defun org-confluence-table-row  (table-row contents info)
 143   (concat
 144    (if (org-string-nw-p contents) (format "|%s" contents)
 145      "")
 146    (when (org-export-table-row-ends-header-p table-row info)
 147      "|")))
 148
 149 (defun org-confluence-table-cell  (table-cell contents info)
 150   (let ((table-row (org-export-get-parent table-cell)))
 151     (concat (and (org-export-table-row-starts-header-p table-row info) "|")
 152             (if (= (length contents) 0) " " contents)
 153             "|")))
 154
 155 (defun org-confluence-template (contents info)
 156   (let ((depth (plist-get info :with-toc)))
 157     (concat (when depth "\{toc\}\n\n") contents)))
 158
 159 (defun org-confluence-timestamp (timestamp _contents _info)
 160   "Transcode a TIMESTAMP object from Org to Confluence.
 161 CONTENTS and INFO are ignored."
 162   (let ((translated (org-timestamp-translate timestamp)))
 163     (if (string-prefix-p "[" translated)
 164         (concat "(" (substring translated 1 -1) ")")
 165       translated)))
 166
 167 (defun org-confluence-underline (underline contents info)
 168   (format "+%s+" contents))
 169
 170 (defun org-confluence--block (language theme contents)
 171   (concat "\{code:theme=" theme
 172           (when language (format "|language=%s" language))
 173           "}\n"
 174           contents
 175           "\{code\}\n"))
 176
 177 (defun org-confluence--li-depth (item)
 178   "Return depth of a list item; -1 means not a list item"
 179   ;; FIXME check whether it's worth it to cache depth
 180   ;;       (it gets recalculated quite a few times while
 181   ;;       traversing a list)
 182   (let ((depth -1)
 183         (tag))
 184     (while (and item
 185                 (setq tag (car item))
 186                 (or (eq tag 'item) ; list items interleave with plain-list
 187                     (eq tag 'plain-list)))
 188       (when (eq tag 'item)
 189         (incf depth))
 190       (setq item (org-export-get-parent item)))
 191     depth))
 192
 193 ;; main interactive entrypoint
 194 (defun org-confluence-export-as-confluence
 195   (&optional async subtreep visible-only body-only ext-plist)
 196   "Export current buffer to a text buffer.
 197
 198 If narrowing is active in the current buffer, only export its
 199 narrowed part.
 200
 201 If a region is active, export that region.
 202
 203 A non-nil optional argument ASYNC means the process should happen
 204 asynchronously.  The resulting buffer should be accessible
 205 through the `org-export-stack' interface.
 206
 207 When optional argument SUBTREEP is non-nil, export the sub-tree
 208 at point, extracting information from the headline properties
 209 first.
 210
 211 When optional argument VISIBLE-ONLY is non-nil, don't export
 212 contents of hidden elements.
 213
 214 When optional argument BODY-ONLY is non-nil, strip title, table
 215 of contents and footnote definitions from output.
 216
 217 EXT-PLIST, when provided, is a property list with external
 218 parameters overriding Org default settings, but still inferior to
 219 file-local settings.
 220
 221 Export is done in a buffer named \"*Org CONFLUENCE Export*\", which
 222 will be displayed when `org-export-show-temporary-export-buffer'
 223 is non-nil."
 224   (interactive)
 225   (org-export-to-buffer 'confluence "*org CONFLUENCE Export*"
 226     async subtreep visible-only body-only ext-plist (lambda () (text-mode))))
 227
 228 (provide 'ox-confluence)