diff options
| author | Stig Brautaset <stig@brautaset.org> | 2020-02-18 09:44:00 +0000 |
|---|---|---|
| committer | Stig Brautaset <stig@brautaset.org> | 2020-02-18 22:55:38 +0000 |
| commit | cbbb17f58ddcb5af1d5fd8e8f8cc437a80483ffe (patch) | |
| tree | 18d7dfffb6f12c0f6332e7048f062eddd293fe55 | |
| parent | c953cc6695858f9e5505b1aeff5354d50cfeaf5b (diff) | |
Add back the ox-jira.org document
Still haven't updated it with all the changes added to ox-jira.el, so
it's not the master source yet.
| -rw-r--r-- | ox-jira.org | 750 |
1 files changed, 750 insertions, 0 deletions
diff --git a/ox-jira.org b/ox-jira.org new file mode 100644 index 0000000..e7f2ae1 --- /dev/null +++ b/ox-jira.org @@ -0,0 +1,750 @@ +#+TITLE: JIRA Backend for Org Export Engine +#+AUTHOR: Stig Brautaset +#+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 Stig Brautaset + + ;; Author: Stig Brautaset <stig@brautaset.org> + ;; 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 <http://www.gnu.org/licenses/>. +#+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. +This is cargo-culted from =ox-latex.el=. + +#+BEGIN_SRC emacs-lisp + (eval-when-compile (require 'cl)) + (require 'ox) + (require 'ox-publish) +#+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 + (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 . (lambda (&rest args) (ox-jira--not-implemented '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)) + :menu-entry + '(?j "Export to JIRA" + ((?j "As JIRA buffer" ox-jira-export-as-jira)))) +#+END_SRC + +** 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:back%s}[^%s^|#%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:%s}[^%s^|#back%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* ((level (org-export-get-relative-level headline info)) + (title (org-export-data-with-backend + (org-element-property :title headline) + 'jira info))) + (concat + (format "h%d. %s\n" level title) + 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 (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= type "file") + (org-export-file-uri raw-path)) + (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 + +JIRA supports formatting for these languages: actionscript, html, +java, javascript, sql, xhtml, xml. If none of them fits, we can use +=none=, 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* ((lang (org-element-property :language src-block)) + (lang (if (member lang '("actionscript" "html" "java" "javascript" "sql" "xhtml" "xml")) lang)) + (code (org-export-format-code-default src-block info))) + (concat + (if lang + (format "{code:%s}" lang) + "{code}") + 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 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 + +** 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 + (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 |
