#+TITLE: JIRA Backend for Org Export Engine #+AUTHOR: Stig Brautaset #+OPTIONS: f:t #+PROPERTY: header-args:emacs-lisp :tangle yes :results silent * Introduction I got tired of exporting Org mode to Markdown and pasting _that_ into this [[http://j2m.fokkezb.nl][Markdown to JIRA]] translator, so I'm attempting to write an Org to JIRA export backend. *This will most likely* only be as complete as I need it to be. I feel I tend to use a limited subset of Org's markup, and this backend will likely only support that subset---unless I get some contributions. The master source is in =ox-jira.org=, and the code sections are /tangled/ (i.e. extracted) into =ox-jira.el= from it. * Header First come some [[http://www.gnu.org/software/emacs/manual/html_node/elisp/Library-Headers.html][conventional headers]] that libraries tend to include. Cask requires them. Use =:padline no= to avoid starting the tangled file with a blank line. #+BEGIN_SRC emacs-lisp :padline no ;;; ox-jira.el --- JIRA Backend for Org Export Engine ;; Copyright (C) 2016-2020 Stig Brautaset ;; Author: Stig Brautaset ;; Version: 0.1-SNAPSHOT #+END_SRC Define the keywords that can be used to find this package with =finder-by-keyword= (=C-h p=). #+BEGIN_SRC emacs-lisp :padline no ;; Keywords: outlines, hypermedia, wp ;; Homepage: https://github.com/stig/ox-jira.el #+END_SRC Require Org version 8.3 or above, as that introduces the export backend system we use. #+BEGIN_SRC emacs-lisp :padline no ;; Package-Requires: ((org "8.3")) ;; This file is NOT part of GNU Emacs. #+END_SRC I prefer the MIT license because it is short enough to read without toilet or tea breaks, and I /think/ I can actually wrap my head around it. (And I feel it's important to understand the license of your choice.) However, given I've cribbed copiously from =ox-latex.el= I will use the GPL for this work. #+BEGIN_SRC emacs-lisp ;; This program is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by ;; the Free Software Foundation, either version 3 of the License, or ;; (at your option) any later version. ;; This program is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. ;; You should have received a copy of the GNU General Public License ;; along with this program. If not, see . #+END_SRC Now a section describing what the package /does/. This is important for MELPA and package.el. It is largely copy-pasted from the README. #+BEGIN_SRC emacs-lisp ;;; Commentary: ;; This module plugs into the regular Org Export Engine and transforms Org ;; files to JIRA markup for pasting into JIRA tickets & comments. ;; In an Org buffer, hit `C-c C-e j j' to bring up *Org Export Dispatcher* ;; and export it as a JIRA buffer. I usually use `C-x h' to mark the whole ;; buffer, then `M-w' to save it to the kill ring (and global pasteboard) for ;; pasting into JIRA issues. #+END_SRC Lastly a special marker to denote that we're done with the header section and starting the actual code now. #+BEGIN_SRC emacs-lisp ;;; Code: #+END_SRC * Code Alright! We're done with the introduction. This section contains the actual code of our package. I'm excited! ** Require libraries The first thing our code needs to do is require the libraries we need. I cargo-culted most of this from =ox-latex.el=. #+BEGIN_SRC emacs-lisp (eval-when-compile (require 'cl-lib)) (require 'ox) (require 'ox-publish) (require 'subr-x) #+END_SRC ** User-Configurable options For really long source snippets or sections of logfiles JIRA supports showing a preview, and /collapsing/ the rest. How much to preview before collapsing the rest is up to individual taste, so let's make it configurable. #+begin_src emacs-lisp ;;; User Configurable Options (defgroup ox-jira-export nil "Options specific to JIRA export back-end." :tag "Org Export JIRA" :group 'org-export :version "24.4" :package-version '(ox-jira . "0.1")) #+end_src *** Long source snippets #+begin_src emacs-lisp (defcustom ox-jira-src-collapse-threshold 30 "Minimum number of lines in a src block to set collapse=true in JIRA/Confluence {code} block." :group 'ox-export-jira :type '(integer)) #+end_src *** Supported languages JIRA supports formatting for these languages: #+begin_src emacs-lisp (defcustom ox-jira-src-supported-languages '("actionscript" "ada" "applescript" "c" "c#" "c++" "css" "erlang" "go" "groovy" "html" "haskell" "json" "java" "javascript" "lua" "nyan" "objc" "php" "perl" "python" "r" "ruby" "sql" "scala" "swift" "visualbasic" "xml" "yaml" "bash") "Supported languages for syntax highlighting." :group 'ox-export-jira :type '(list)) #+end_src *** Override export heading levels You can pass options to the org-exporter backend. #+begin_src emacs-lisp (defcustom ox-jira-override-headline-offset nil "Use this to override the (default) relative headline levels. If you want to have the headings *real* heading level in the Jira output when you export a subsection, use `0' here. If you think the headings in Jira are too big by default, you could set this to `2' to start headings at level 3." :group 'ox-export-jira :type 'integer) #+end_src ** Define Backend This is the entry point of our package. The first argument is the name of our backend. The second is a map between element types[fn:1] to export and the transcode functions to handle them. These are defined in the next section. Finally it tells the Org export backend how to create a menu entry for us. #+BEGIN_SRC emacs-lisp ;;; Defining Backend (org-export-define-backend 'jira '((babel-call . (lambda (&rest args) (ox-jira--not-implemented 'babel-call))) (body . (lambda (&rest args) (ox-jira--not-implemented 'body))) (bold . ox-jira-bold) (center-block . (lambda (&rest args) (ox-jira--not-implemented 'center-block))) (clock . (lambda (&rest args) (ox-jira--not-implemented 'clock))) (code . ox-jira-code) (diary-sexpexample-block . (lambda (&rest args) (ox-jira--not-implemented 'diary-sexpexample-block))) (drawer . (lambda (&rest args) (ox-jira--not-implemented 'drawer))) (dynamic-block . (lambda (&rest args) (ox-jira--not-implemented 'dynamic-block))) (entity . (lambda (&rest args) (ox-jira--not-implemented 'entity))) (example-block . ox-jira-example-block) (export-block . (lambda (&rest args) (ox-jira--not-implemented 'export-block))) (export-snippet . (lambda (&rest args) (ox-jira--not-implemented 'export-snippet))) (final-output . (lambda (&rest args) (ox-jira--not-implemented 'final-output))) (fixed-width . ox-jira-fixed-width) (footnote-definition . ox-jira-footnote-definition) (footnote-reference . ox-jira-footnote-reference) (headline . ox-jira-headline) (horizontal-rule . ox-jira-horizontal-rule) (inline-babel-call . (lambda (&rest args) (ox-jira--not-implemented 'inline-babel-call))) (inline-src-block . (lambda (&rest args) (ox-jira--not-implemented 'inline-src-block))) (inlinetask . (lambda (&rest args) (ox-jira--not-implemented 'inlinetask))) (italic . ox-jira-italic) (item . ox-jira-item) (keyword . (lambda (&rest args) "")) (latex-environment . (lambda (&rest args) (ox-jira--not-implemented 'latex-environment))) (latex-fragment . (lambda (&rest args) (ox-jira--not-implemented 'latex-fragment))) (line-break . (lambda (&rest args) (ox-jira--not-implemented 'line-break))) (link . ox-jira-link) (node-property . (lambda (&rest args) (ox-jira--not-implemented 'node-property))) (options . (lambda (&rest args) (ox-jira--not-implemented 'options))) (paragraph . ox-jira-paragraph) (parse-tree . (lambda (&rest args) (ox-jira--not-implemented 'parse-tree))) (plain-list . ox-jira-plain-list) (plain-text . ox-jira-plain-text) (planning . (lambda (&rest args) (ox-jira--not-implemented 'planning))) (property-drawer . (lambda (&rest args) (ox-jira--not-implemented 'property-drawer))) (quote-block . ox-jira-quote-block) (radio-target . (lambda (&rest args) (ox-jira--not-implemented 'radio-target))) (section . ox-jira-section) (special-block . (lambda (&rest args) (ox-jira--not-implemented 'special-block))) (src-block . ox-jira-src-block) (statistics-cookie . ox-jira-statistics-cookie) (strike-through . ox-jira-strike-through) (subscript . ox-jira-subscript) (superscript . ox-jira-superscript) (table . ox-jira-table) (table-cell . ox-jira-table-cell) (table-row . ox-jira-table-row) (target . (lambda (&rest args) (ox-jira--not-implemented 'target))) (timestamp . ox-jira-timestamp) (underline . ox-jira-underline) (verbatim . ox-jira-verbatim) (verse-block . (lambda (&rest args) (ox-jira--not-implemented 'verse-block)))) :filters-alist '((:filter-parse-tree . ox-jira-fix-multi-paragraph-items)) :options-alist '((:src-collapse-threshold nil nil ox-jira-src-collapse-threshold)) :menu-entry '(?j "Export to JIRA" ((?j "As JIRA buffer" ox-jira-export-as-jira)))) #+END_SRC Note that at the ~options-alist~ at the end of that backend definition we add our config option. ** Internal helpers #+BEGIN_SRC emacs-lisp ;;; Internal Helpers #+END_SRC Because I'm adding support for things as I find I need it rather than all in one go, let's put a big fat red marker in for things we have not implemented yet, to avoid missing it. #+BEGIN_SRC emacs-lisp (defun ox-jira--not-implemented (element-type) "Replace anything we don't handle yet with a big red marker." (format "{color:red}Element of type '%s' not implemented!{color}" element-type)) #+END_SRC Super^script and sub_script I often want at the end of words, with no whitespace immediately before it. Unfortunately JIRA doesn't support that, so we have to fake it. This function makes simple text transforms "embeddable" by preceding them with an empty anchor. This is admittedly a bit of a hack, but I haven't found anything better. #+BEGIN_SRC emacs-lisp (defun ox-jira--text-transform-embeddable (transform-char contents) (concat "{anchor}" transform-char contents transform-char)) #+END_SRC ** Filters #+BEGIN_SRC emacs-lisp ;;; Filters #+END_SRC Org support a single blank line between items in a list, but if we export like that JIRA interprets it as multiple consecutive lists; which is never what I want. We can fix this by removing the "post-blank" after =items= (and =paragraphs= inside =items=) using a filter. #+BEGIN_SRC emacs-lisp (defun ox-jira-fix-multi-paragraph-items (tree backend info) "Remove extra blank line between paragraphs in plain-list items. TREE is the parse tree being exported. BACKEND is the export back-end used. INFO is a plist used as a communication channel. Assume BACKEND is `jira'." (org-element-map tree '(item paragraph src-block) (lambda (e) (org-element-put-property e :post-blank (if (or (eq (org-element-type e) 'item) (eq (org-element-type (org-element-property :parent e)) 'item)) 0 1)))) ;; Return updated tree. tree) #+END_SRC ** Transcode Functions These functions do the actual translation to JIRA format. For this section I've used Atlassian's [[https://jira.atlassian.com/secure/WikiRendererHelpAction.jspa?section=all][Text Formatting Notation Help]] page as a reference. #+BEGIN_SRC emacs-lisp ;;; Transcode functions #+END_SRC *** Bold #+BEGIN_SRC emacs-lisp (defun ox-jira-bold (bold contents info) "Transcode BOLD from Org to JIRA. CONTENTS is the text with bold markup. INFO is a plist holding contextual information." (format "*%s*" contents)) #+END_SRC *** Code For CODE elements we cannot use the contents, as it is always nil. #+BEGIN_SRC emacs-lisp (defun ox-jira-code (code _contents info) "Transcode a CODE object from Org to JIRA. CONTENTS is nil. INFO is a plist used as a communication channel." (format "{{%s}}" (org-element-property :value code))) #+END_SRC *** Example block I often use this for log lines etc. Let's use the JIRA ={noformat}= tags for it. #+BEGIN_SRC emacs-lisp (defun ox-jira-example-block (example-block contents info) "Transcode an EXAMPLE-BLOCK element from Org to Jira. CONTENTS is nil. INFO is a plist holding contextual information." (when (org-string-nw-p (org-element-property :value example-block)) (format "{noformat}\n%s{noformat}" (org-export-format-code-default example-block info)))) #+END_SRC *** Fixed-width block I often use this for short snippets of log lines etc. Let's use the JIRA ={noformat}= tags for it. #+BEGIN_SRC emacs-lisp (defun ox-jira-fixed-width (fixed-width contents info) "Transcode an FIXED-WIDTH element from Org to Jira. CONTENTS is nil. INFO is a plist holding contextual information." (format "{noformat}\n%s{noformat}" (org-remove-indentation (org-element-property :value fixed-width)))) #+END_SRC *** Footnotes Footnotes have two parts: the reference, and the definition. #+BEGIN_SRC emacs-lisp (defun ox-jira--footnote-anchor (element) (let ((label (org-element-property :label element))) (replace-regexp-in-string ":" "" label))) (defun ox-jira--footnote-ref (anchor) (replace-regexp-in-string "fn" "" anchor)) (defun ox-jira-footnote-reference (footnote-reference contents info) "Transcode an FOOTNOTE-REFERENCE element from Org to Jira. CONTENTS is nil. INFO is a plist holding contextual information." (let* ((anchor (ox-jira--footnote-anchor footnote-reference)) (ref (ox-jira--footnote-ref anchor))) (format "{anchor:fnr%s}[^%s^|#fn%s]" anchor ref anchor))) (defun ox-jira-footnote-definition (footnote-definition contents info) "Transcode an FOOTNOTE-DEFINITION element from Org to Jira. CONTENTS is nil. INFO is a plist holding contextual information." (let* ((anchor (ox-jira--footnote-anchor footnote-definition)) (ref (ox-jira--footnote-ref anchor))) (format "{anchor:fn%s}[^%s^|#fnr%s] %s" anchor ref anchor contents))) #+END_SRC *** Headline Headlines are a little bit more complex. I'm not even attempting to support TODO labels and meta-information, just the straight-up text. It would be nice to support the six standard levels of headlines JIRA offers though. Since the headline level is /relative/ rather than absolute, if the exporter sees a =** second level= heading before it's seen a =* first level= then the =** second level= will think it's a top-level heading. That's a bit weird, but there you go. #+BEGIN_SRC emacs-lisp (defun ox-jira-headline (headline contents info) "Transcode a HEADLINE element from Org to JIRA. CONTENTS is the contents of the headline, as a string. INFO is the plist used as a communication channel." (let* ((headline-info (if (eql ox-jira-override-headline-offset nil) info (plist-put nil :headline-offset ox-jira-override-headline-offset))) (level (org-export-get-relative-level headline headline-info)) (title (org-export-data-with-backend (org-element-property :title headline) 'jira info)) (todo (and (plist-get info :with-todo-keywords) (let ((todo (org-element-property :todo-keyword headline))) (and todo (org-export-data todo info))))) (todo-type (and todo (org-element-property :todo-type headline))) (todo-text (if todo (format "{color:%s}{{%s}}{color} " (if (eq todo-type 'done) "lightgreen" "red") todo) "")) (tags (and (plist-get info :with-tags) (org-export-get-tags headline info))) (tags-text (if tags (format " {color:blue}{{:%s:}}{color}" (string-join tags ":")) ""))) (concat (format "h%d. %s%s%s\n" level todo-text title tags-text) contents))) #+END_SRC *** Horizontal Rule #+BEGIN_SRC emacs-lisp (defun ox-jira-horizontal-rule (horizontal-rule contents info) "Transcode a HORIZONTAL-RULE element from Org to JIRA." "----\n") #+END_SRC *** Italic #+BEGIN_SRC emacs-lisp (defun ox-jira-italic (italic contents info) "Transcode ITALIC from Org to JIRA. CONTENTS is the text with italic markup. INFO is a plist holding contextual information." (format "_%s_" contents)) #+END_SRC *** Item :PROPERTIES: :ID: E66B524A-F8C8-413B-9E65-401F74818ED4 :END: A list item. The JIRA format for nested lists follows. (You can also mix ordered and unordered lists.) : * item : ** sub-item : ** sub-item 2 : * item 2 The item element itself does not know what type it is: that is an attribute of its parent, a plain-list element. We need to walk the path of alternating plain-list and item nodes until there are no more, and extract their type. The type list is used to create a bullet string. JIRA doesn't really have support for definition lists, so we fake it with a bullet list and some bold text for the term. #+BEGIN_SRC emacs-lisp (defun ox-jira--list-type-path (item) (when (and item (eq 'item (org-element-type item))) (let* ((list (org-element-property :parent item)) (list-type (org-element-property :type list))) (cons list-type (ox-jira--list-type-path (org-element-property :parent list)))))) (defun ox-jira--bullet-string (list-type-path) (apply 'string (mapcar (lambda (x) (if (eq x 'ordered) ?# ?*)) list-type-path))) (defun ox-jira-item (item contents info) "Transcode ITEM from Org to JIRA. CONTENTS is the text with item markup. INFO is a plist holding contextual information." (let* ((list-type-path (ox-jira--list-type-path item)) (bullet-string (ox-jira--bullet-string (reverse list-type-path))) (tag (let ((tag (org-element-property :tag item))) (when tag (org-export-data tag info)))) (checkbox (cl-case (org-element-property :checkbox item) (on "(/)") (off "(x)") (trans "(i)")))) (concat bullet-string " " (when checkbox (concat checkbox " ")) (when tag (format "*%s*: " tag)) contents))) #+END_SRC *** Link JIRA supports many types of links. I don't expect to support them all, but we must make a token effort. A lot of this code is cribbed from =ox-latex.el=. #+BEGIN_SRC emacs-lisp (defun ox-jira-link (link desc info) "Transcode a LINK object from Org to JIRA. DESC is the description part of the link, or the empty string. INFO is a plist holding contextual information. See `org-export-data'." (let* ((type (org-element-property :type link)) (raw-path (org-element-property :path link)) (desc (and (not (string= desc "")) desc)) (path (cond ((member type '("http" "https" "ftp" "mailto" "doi")) (concat type ":" raw-path)) ((string-prefix-p "~accountid" raw-path) raw-path) ((string= type "file") (org-export-file-uri raw-path)) ((string= type "custom-id") (if desc (concat "#" desc) (concat "#" raw-path))) ((string-prefix-p "*" raw-path) (concat "#" (seq-subseq raw-path 1))) ((org-export-custom-protocol-maybe link desc 'jira info)) (t raw-path)))) (cond ;; Link with description ((and path desc) (format "[%s|%s]" desc path)) ;; Link without description (path (format "[%s]" path)) ;; Link with only description?! (t desc)))) #+END_SRC *** Underline #+BEGIN_SRC emacs-lisp (defun ox-jira-underline (underline contents info) "Transcode UNDERLINE from Org to JIRA. CONTENTS is the text with underline markup. INFO is a plist holding contextual information." (format "+%s+" contents)) #+END_SRC *** Verbatim #+BEGIN_SRC emacs-lisp (defun ox-jira-verbatim (verbatim _contents info) "Transcode a VERBATIM object from Org to Jira. CONTENTS is nil. INFO is a plist used as a communication channel." (format "{{%s}}" (org-element-property :value verbatim))) #+END_SRC *** Paragraph One of the most annoying aspects of JIRA markup is its broken handling of line breaks; any newlines in the source becomes hard linebreaks in the rendered output. Let's fix that! What we need to do is replace any /internal/ newlines (i.e. any not at the end of the string) with a space. Regexes to the rescue! I used [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Regexp-Backslash.html#Regexp-Backslash][this reference]] to help me with this function. #+BEGIN_SRC emacs-lisp (defun ox-jira-paragraph (paragraph contents info) "Transcode a PARAGRAPH element from Org to JIRA. CONTENTS is the contents of the paragraph, as a string. INFO is the plist used as a communication channel." (replace-regexp-in-string "\n\\([^\']\\)" " \\1" contents)) #+END_SRC *** Plain lists I make a lot of lists. Let's make sure we handle them! This is simple, since all the complexity is in the code for each [[id:E66B524A-F8C8-413B-9E65-401F74818ED4][item]] in the list. #+BEGIN_SRC emacs-lisp (defun ox-jira-plain-list (plain-list contents info) "Transcode PLAIN-LIST from Org to JIRA. CONTENTS is the text with plain-list markup. INFO is a plist holding contextual information." contents) #+END_SRC *** Plain text This is text with no markup, but we have to escape certain characters to avoid tripping up JIRA. In particular: - ={= :: Introduces macros - =[= :: Introduces links #+BEGIN_SRC emacs-lisp (defun ox-jira-plain-text (text info) "Transcode TEXT from Org to JIRA. TEXT is the string to transcode. INFO is a plist holding contextual information." (replace-regexp-in-string "\\([[{]\\)" '(lambda (p) (format "\\\\%s" p)) text)) #+END_SRC *** Section Paragraphs are grouped into sections. I've not found any mention in the Org documentation, but it appears to be essential for any export to happen. I've essentially cribbed this from =ox-latex.el=. #+BEGIN_SRC emacs-lisp (defun ox-jira-section (section contents info) "Transcode a SECTION element from Org to JIRA. CONTENTS is the contents of the section, as a string. INFO is the plist used as a communication channel." contents) #+END_SRC *** Source code block If language is not member of =ox-jira-src-supported-languages=, =none=, will be used which I imagine will be a bit like ={noformat}=. #+BEGIN_SRC emacs-lisp (defun ox-jira-src-block (src-block contents info) "Transcode a SRC-BLOCK element from Org to Jira. CONTENTS holds the contents of the src-block. INFO is a plist holding contextual information." (when (org-string-nw-p (org-element-property :value src-block)) (let* ((title (apply #'concat (org-export-get-caption src-block))) (lang (org-element-property :language src-block)) (lang (if (member lang ox-jira-src-supported-languages) lang "none")) (code (org-export-format-code-default src-block info)) (collapse (if (< (plist-get info :src-collapse-threshold) (org-count-lines code)) "true" "false"))) (concat (format "{code:title=%s|language=%s|collapse=%s}" title lang collapse) code "{code}")))) #+END_SRC *** Subscript #+BEGIN_SRC emacs-lisp (defun ox-jira-subscript (subscript contents info) "Transcode SUBSCRIPT from Org to JIRA. CONTENTS is the text with subscript markup. INFO is a plist holding contextual information." (ox-jira--text-transform-embeddable "~" contents)) #+END_SRC *** Superscript #+BEGIN_SRC emacs-lisp (defun ox-jira-superscript (superscript contents info) "Transcode SUPERSCRIPT from Org to JIRA. CONTENTS is the text with superscript markup. INFO is a plist holding contextual information." (ox-jira--text-transform-embeddable "^" contents)) #+END_SRC *** Table Org's table editor is one of the many reasons to use Org; it is excellent. Org and JIRA's tables are quite similar. Where Org marks tables up like this: : | Name | Score | : |--------+-------| : | Ashley | 2 | : | Alex | 3 | Jira uses the following format: : || Name || Score || : | Ashley | 2 | : | Alex | 3 | Tables are complex beasts. I only hope to support simple ones. Looks like most of the logic will live in the row and cell transcoding functions. #+BEGIN_SRC emacs-lisp (defun ox-jira-table (table contents info) "Transcode a TABLE element from Org to JIRA. CONTENTS holds the contents of the table. INFO is a plist holding contextual information." contents) #+END_SRC We only want to output =standard= rows, not horizontal lines. I'm not sure if detection of header rows belong here or in the cells. #+BEGIN_SRC emacs-lisp (defun ox-jira-table-row (table-row contents info) "Transcode a TABLE-ROW element from Org to JIRA. CONTENTS holds the contents of the table-row. INFO is a plist holding contextual information." (when (eq 'standard (org-element-property :type table-row)) (format "%s\n" contents))) #+END_SRC The cell itself does not know if it is a header cell or not, so we have to ask its containing row if it is the first row, and the table if it has a header row at all. If those things are true, make the cell a header cell. #+BEGIN_SRC emacs-lisp (defun ox-jira-table-cell (table-cell contents info) "Transcode a TABLE-CELL element from Org to JIRA. CONTENTS holds the contents of the table-cell. INFO is a plist holding contextual information." (let* ((row (org-element-property :parent table-cell)) (table (org-element-property :parent row)) (has-header (org-export-table-has-header-p table info)) (group (org-export-table-row-group row info)) (is-header (and has-header (eq 1 group))) (sep (if is-header "||" "|"))) (format "%s %s %s" sep (if contents contents "") (if (org-export-last-sibling-p table-cell info) sep "")))) #+END_SRC *** Statistics Cookie This is updated to show progress of subsequent list of check boxes. #+BEGIN_SRC emacs-lisp (defun ox-jira-statistics-cookie (statistics-cookie _contents _info) "Transcode a STATISTICS-COOKIE object from Org to JIRA. CONTENTS is nil. INFO is a plist holding contextual information." (format "\\%s" (org-element-property :value statistics-cookie))) #+END_SRC *** Strike-Through JIRA call this "deleted text". In my opinion this is rather silly because it is obviously there. Org is at least logical in calling it for what it is. I suppose JIRA is trying to be semantic here, but outside a diff you rather want to look in the revision log for deleted text rather than have it clutter up things. Still, it's simple to support, so we might as well do it. #+BEGIN_SRC emacs-lisp (defun ox-jira-strike-through (strike-through contents info) "Transcode STRIKE-THROUGH from Org to JIRA. CONTENTS is the text with strike-through markup. INFO is a plist holding contextual information." (format "-%s-" contents)) #+END_SRC *** Quote block #+BEGIN_SRC emacs-lisp (defun ox-jira-quote-block (quote-block contents info) "Transcode a QUOTE-BLOCK element from Org to Jira. CONTENTS holds the contents of the block. INFO is a plist holding contextual information." (format "{quote}\n%s{quote}" contents)) #+END_SRC *** Timestamp #+begin_src emacs-lisp (defun ox-jira-timestamp (timestamp _contents info) "Transcode a TIMESTAMP object from Org to JIRA. CONTENTS is nil. INFO is a plist holding contextual information." (let ((value (org-timestamp-translate timestamp)) (fmt (cl-case (org-element-property :type timestamp) ((active active-range) "_%s_") ((inactive inactive-range) "_\\%s_") (otherwise "_%s_")))) (format fmt value))) #+end_src ** End-user functions This is our main export function. This can be called interactively, for example from the Org export dispatcher. #+BEGIN_SRC emacs-lisp ;;;###autoload (defun ox-jira-export-as-jira (&optional async subtreep visible-only body-only ext-plist) "Export current buffer as a Jira buffer. If narrowing is active in the current buffer, only export its narrowed part. If a region is active, export that region. A non-nil optional argument ASYNC means the process should happen asynchronously. The resulting buffer should be accessible through the `org-export-stack' interface. When optional argument SUBTREEP is non-nil, export the sub-tree at point, extracting information from the headline properties first. When optional argument VISIBLE-ONLY is non-nil, don't export contents of hidden elements. When optional argument BODY-ONLY is non-nil, omit header stuff. (e.g. AUTHOR and TITLE.) EXT-PLIST, when provided, is a property list with external parameters overriding Org default settings, but still inferior to file-local settings. Export is done in a buffer named \"*Org JIRA Export*\", which will be displayed when `org-export-show-temporary-export-buffer' is non-nil." (interactive) (org-export-to-buffer 'jira "*Org JIRA Export*" async subtreep visible-only body-only ext-plist)) #+END_SRC ** Provide Announce that =ox-jira= is a feature of the current Emacs. #+BEGIN_SRC emacs-lisp (provide 'ox-jira) #+END_SRC * Footer Now we need to put and end to this malarky. There's a magic comment for that too. It looks like this: #+BEGIN_SRC emacs-lisp ;;; ox-jira.el ends here #+END_SRC All that does is help people figure out if a file has been truncated. If they see that comment, they know they don't have just half the file. Weird, huh? * Footnotes [fn:1] I got this list of elements from http://orgmode.org/manual/Advanced-configuration.html