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                      (code . org-confluence-code)
  43                      (example-block . org-confluence-example-block)
  44                      (fixed-width . org-confluence-fixed-width)
  45                      (footnote-definition . org-confluence-empty)
  46                      (footnote-reference . org-confluence-empty)
  47                      (headline . org-confluence-headline)
  48                      (italic . org-confluence-italic)
  49                      (item . org-confluence-item)
  50                      (link . org-confluence-link)
  51                      (paragraph . org-confluence-paragraph)
  52                      (property-drawer . org-confluence-property-drawer)
  53                      (quote-block . org-confluence-quote-block)
  54                      (section . org-confluence-section)
  55                      (src-block . org-confluence-src-block)
  56                      (strike-through . org-confluence-strike-through)
  57                      (table . org-confluence-table)
  58                      (table-cell . org-confluence-table-cell)
  59                      (table-row . org-confluence-table-row)
  60                      (template . org-confluence-template)
  61                      (timestamp . org-confluence-timestamp)
  62                      (underline . org-confluence-underline)
  63                      (verbatim . org-confluence-verbatim)))
  64
  65 (defcustom org-confluence-lang-alist
  66   '(("sh" . "bash"))
  67   "Map from org-babel language name to confluence wiki language name"
  68   :type '(alist :key-type string :value-type string))
  69
  70 ;; All the functions we use
  71 (defun org-confluence-bold (bold contents info)
  72   (format "*%s*" contents))
  73
  74 (defun org-confluence-empty (empty contents info)
  75   "")
  76
  77 (defun org-confluence-example-block (example-block contents info)
  78   ;; FIXME: provide a user-controlled variable for theme
  79   (let ((content (org-export-format-code-default example-block info)))
  80     (org-confluence--block "none" "Confluence" content)))
  81
  82 (defun org-confluence-italic (italic contents info)
  83   (format "_%s_" contents))
  84
  85 (defun org-confluence-item (item contents info)
  86   (let ((list-type (org-element-property :type (org-export-get-parent item))))
  87     (concat
  88      (make-string (1+ (org-confluence--li-depth item))
  89                   (if (eq list-type 'ordered) ?\# ?\-))
  90      " "
  91      (pcase (org-element-property :checkbox item)
  92        (`on "*{{(X)}}* ")
  93        (`off "*{{( )}}* ")
  94        (`trans "*{{(\\-)}}* "))
  95      (when (eq list-type 'descriptive)
  96        (concat "*"
  97                (org-export-data (org-element-property :tag item) info)
  98                "* - "))
  99      (org-trim contents))))
 100
 101 (defun org-confluence-fixed-width (fixed-width contents info)
 102   (org-confluence--block
 103    "none"
 104    "Confluence"
 105    (org-trim (org-element-property :value fixed-width))))
 106
 107 (defun org-confluence-verbatim (verbatim contents info)
 108   (format "\{\{%s\}\}" (org-element-property :value verbatim)))
 109
 110 (defun org-confluence-code (code contents info)
 111   (format "\{\{%s\}\}" (org-element-property :value code)))
 112
 113 (defun org-confluence-headline (headline contents info)
 114   (let* ((low-level-rank (org-export-low-level-p headline info))
 115          (text (org-export-data (org-element-property :title headline)
 116                                 info))
 117          (todo (org-export-data (org-element-property :todo-keyword headline)
 118                                 info))
 119          (level (org-export-get-relative-level headline info))
 120          (todo-text (if (or (not (plist-get info :with-todo-keywords))
 121                             (string= todo ""))
 122                         ""
 123                       (format "*{{%s}}* " todo))))
 124     (format "h%s. %s%s\n%s" level todo-text text
 125             (if (org-string-nw-p contents) contents ""))))
 126
 127 (defun org-confluence-link (link desc info)
 128   (let ((raw-link (org-element-property :raw-link link)))
 129     (concat "["
 130             (when (org-string-nw-p desc) (format "%s|" desc))
 131             (cond
 132              ((string-match "^confluence:" raw-link)
 133               (replace-regexp-in-string "^confluence:" "" raw-link))
 134              (t
 135               raw-link))
 136             "]")))
 137
 138 (defun org-confluence-paragraph (paragraph contents info)
 139   "Transcode PARAGRAPH element for Confluence.
 140 CONTENTS is the paragraph contents.  INFO is a plist used as
 141 a communication channel."
 142   contents)
 143
 144 (defun org-confluence-property-drawer (property-drawer contents info)
 145   (and (org-string-nw-p contents)
 146        (format "\{\{%s\}\}" contents)))
 147
 148 (defun org-confluence-quote-block (quote-block contents info)
 149   (format "{quote}\n%s{quote}" contents))
 150
 151 (defun org-confluence-section (section contents info)
 152   contents)
 153
 154 (defun org-confluence-src-block (src-block contents info)
 155   ;; FIXME: provide a user-controlled variable for theme
 156   (let* ((lang (org-element-property :language src-block))
 157          (language (or (cdr (assoc lang org-confluence-lang-alist)) lang))
 158          (content (org-export-format-code-default src-block info)))
 159     (org-confluence--block language "Emacs" content)))
 160
 161 (defun org-confluence-strike-through (strike-through contents info)
 162   (format "-%s-" contents))
 163
 164 (defun org-confluence-table (table contents info)
 165   contents)
 166
 167 (defun org-confluence-table-row  (table-row contents info)
 168   (concat
 169    (if (org-string-nw-p contents) (format "|%s" contents)
 170      "")
 171    (when (org-export-table-row-ends-header-p table-row info)
 172      "|")))
 173
 174 (defun org-confluence-table-cell  (table-cell contents info)
 175   (let ((table-row (org-export-get-parent table-cell)))
 176     (concat (and (org-export-table-row-starts-header-p table-row info) "|")
 177             (if (= (length contents) 0) " " contents)
 178             "|")))
 179
 180 (defun org-confluence-template (contents info)
 181   (let ((depth (plist-get info :with-toc)))
 182     (concat (when depth "\{toc\}\n\n") contents)))
 183
 184 (defun org-confluence-timestamp (timestamp _contents _info)
 185   "Transcode a TIMESTAMP object from Org to Confluence.
 186 CONTENTS and INFO are ignored."
 187   (let ((translated (org-trim (org-timestamp-translate timestamp))))
 188     (if (string-prefix-p "[" translated)
 189         (concat "(" (substring translated 1 -1) ")")
 190       translated)))
 191
 192 (defun org-confluence-underline (underline contents info)
 193   (format "+%s+" contents))
 194
 195 (defun org-confluence--block (language theme contents)
 196   (concat "\{code:theme=" theme
 197           (when language (format "|language=%s" language))
 198           "}\n"
 199           contents
 200           "\{code\}\n"))
 201
 202 (defun org-confluence--li-depth (item)
 203   "Return depth of a list item; -1 means not a list item"
 204   ;; FIXME check whether it's worth it to cache depth
 205   ;;       (it gets recalculated quite a few times while
 206   ;;       traversing a list)
 207   (let ((depth -1)
 208         (tag))
 209     (while (and item
 210                 (setq tag (car item))
 211                 (or (eq tag 'item) ; list items interleave with plain-list
 212                     (eq tag 'plain-list)))
 213       (when (eq tag 'item)
 214         (cl-incf depth))
 215       (setq item (org-export-get-parent item)))
 216     depth))
 217
 218 ;; main interactive entrypoint
 219 (defun org-confluence-export-as-confluence
 220   (&optional async subtreep visible-only body-only ext-plist)
 221   "Export current buffer to a text buffer.
 222
 223 If narrowing is active in the current buffer, only export its
 224 narrowed part.
 225
 226 If a region is active, export that region.
 227
 228 A non-nil optional argument ASYNC means the process should happen
 229 asynchronously.  The resulting buffer should be accessible
 230 through the `org-export-stack' interface.
 231
 232 When optional argument SUBTREEP is non-nil, export the sub-tree
 233 at point, extracting information from the headline properties
 234 first.
 235
 236 When optional argument VISIBLE-ONLY is non-nil, don't export
 237 contents of hidden elements.
 238
 239 When optional argument BODY-ONLY is non-nil, strip title, table
 240 of contents and footnote definitions from output.
 241
 242 EXT-PLIST, when provided, is a property list with external
 243 parameters overriding Org default settings, but still inferior to
 244 file-local settings.
 245
 246 Export is done in a buffer named \"*Org CONFLUENCE Export*\", which
 247 will be displayed when `org-export-show-temporary-export-buffer'
 248 is non-nil."
 249   (interactive)
 250   (org-export-to-buffer 'confluence "*org CONFLUENCE Export*"
 251     async subtreep visible-only body-only ext-plist (lambda () (text-mode))))
 252
 253 (provide 'ox-confluence)