ox-freemind.el 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527
  1. ;;; ox-freemind.el --- Freemind Mindmap Back-End for Org Export Engine
  2. ;; Copyright (C) 2013-2018 Free Software Foundation, Inc.
  3. ;; Author: Jambunathan K <kjambunathan at gmail dot com>
  4. ;; Keywords: outlines, hypermedia, calendar, wp
  5. ;; This file is not part of GNU Emacs.
  6. ;; This program is free software: you can redistribute it and/or modify
  7. ;; it under the terms of the GNU General Public License as published by
  8. ;; the Free Software Foundation, either version 3 of the License, or
  9. ;; (at your option) any later version.
  10. ;; This program is distributed in the hope that it will be useful,
  11. ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  12. ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13. ;; GNU General Public License for more details.
  14. ;; You should have received a copy of the GNU General Public License
  15. ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
  16. ;;; Commentary:
  17. ;; This library implements a Freemind Mindmap back-end for Org generic
  18. ;; exporter.
  19. ;; To test it, run:
  20. ;;
  21. ;; M-x org-freemind-export-to-freemind
  22. ;;
  23. ;; in an Org mode buffer. See ox.el for more details on how this
  24. ;; exporter works.
  25. ;;; Code:
  26. ;;; Dependencies
  27. (require 'ox-html)
  28. ;;; Define Back-End
  29. (org-export-define-derived-backend 'freemind 'html
  30. :menu-entry
  31. '(?f "Export to Freemind Mindmap"
  32. ((?f "As Freemind Mindmap file" org-freemind-export-to-freemind)
  33. (?o "As Freemind Mindmap file and open"
  34. (lambda (a s v b)
  35. (if a (org-freemind-export-to-freemind t s v b)
  36. (org-open-file (org-freemind-export-to-freemind nil s v b)))))))
  37. :translate-alist '((headline . org-freemind-headline)
  38. (template . org-freemind-template)
  39. (inner-template . org-freemind-inner-template)
  40. (section . org-freemind-section)
  41. (entity . org-freemind-entity))
  42. :filters-alist '((:filter-options . org-freemind-options-function)
  43. (:filter-final-output . org-freemind-final-function)))
  44. ;;; User Configuration Variables
  45. (defgroup org-export-freemind nil
  46. "Options for exporting Org mode files to Freemind Mindmap."
  47. :tag "Org Export Freemind Mindmap"
  48. :group 'org-export)
  49. (defcustom org-freemind-styles
  50. '((default . "<node>\n</node>")
  51. (0 . "<node COLOR=\"#000000\">\n<font NAME=\"SansSerif\" SIZE=\"20\"/>\n</node>")
  52. (1 . "<node COLOR=\"#0033ff\">\n<edge STYLE=\"sharp_bezier\" WIDTH=\"8\"/>\n<font NAME=\"SansSerif\" SIZE=\"18\"/>\n</node>")
  53. (2 . "<node COLOR=\"#00b439\">\n<edge STYLE=\"bezier\" WIDTH=\"thin\"/>\n<font NAME=\"SansSerif\" SIZE=\"16\"/>\n</node>")
  54. (3 . "<node COLOR=\"#990000\" FOLDED=\"true\">\n<font NAME=\"SansSerif\" SIZE=\"14\"/>\n</node>")
  55. (4 . "<node COLOR=\"#111111\">\n</node>"))
  56. "List of Freemind node styles.
  57. Each entry is of the form (STYLE-NAME . STYLE-SPEC). STYLE-NAME
  58. can be one of an integer (signifying an outline level), a string
  59. or the symbol `default'. STYLE-SPEC, a string, is a Freemind
  60. node style."
  61. :type '(alist :options (default 0 1 2 3)
  62. :key-type (choice :tag "Style tag"
  63. (integer :tag "Outline level")
  64. (const :tag "Default value" default)
  65. (string :tag "Node style"))
  66. :value-type (string :tag "Style spec"))
  67. :group 'org-export-freemind)
  68. (defcustom org-freemind-style-map-function 'org-freemind-style-map--automatic
  69. "Function to map an Org element to it's node style.
  70. The mapping function takes two arguments an Org ELEMENT and INFO.
  71. ELEMENT can be one of the following types - `org-data',
  72. `headline' or `section'. INFO is a plist holding contextual
  73. information during export. The function must return a STYLE-SPEC
  74. to be applied to ELEMENT.
  75. See `org-freemind-style-map--automatic' for a sample style
  76. function. See `org-freemind-styles' for a list of named styles."
  77. :type '(radio
  78. (function-item org-freemind-style-map--automatic)
  79. (function-item org-freemind-style-map--default)
  80. function)
  81. :group 'org-export-freemind)
  82. (defcustom org-freemind-section-format 'note
  83. "Specify how outline sections are to be formatted.
  84. If `inline', append it to the contents of it's heading node. If
  85. `note', attach it as a note to it's heading node. If `node',
  86. attach it as a separate node to it's heading node.
  87. Use `note', if the input Org file contains large sections. Use
  88. `node', if the Org file contains mid-sized sections that need to
  89. stand apart. Otherwise, use `inline'."
  90. :type '(choice
  91. (const :tag "Append to outline title" inline)
  92. (const :tag "Attach as a note" note)
  93. (const :tag "Create a separate node" node))
  94. :group 'org-export-freemind)
  95. ;;;; Debugging
  96. (defcustom org-freemind-pretty-output nil
  97. "Enable this to generate pretty Freemind Mindmap."
  98. :type 'boolean
  99. :group 'org-export-freemind)
  100. ;;; Internal Functions
  101. ;;;; XML Manipulation
  102. (defun org-freemind--serialize (parsed-xml &optional contents)
  103. "Convert PARSED-XML in to XML string.
  104. PARSED-XML is a parse tree as returned by
  105. `libxml-parse-xml-region'. CONTENTS is an optional string.
  106. Ignore CONTENTS, if PARSED-XML is not a sole XML element.
  107. Otherwise, append CONTENTS to the contents of top-level element
  108. in PARSED-XML.
  109. This is an inverse function of `libxml-parse-xml-region'.
  110. For purposes of Freemind export, PARSED-XML is a node style
  111. specification - \"<node ...>...</node>\" - as a parse tree."
  112. (when contents
  113. (assert (symbolp (car parsed-xml))))
  114. (cond
  115. ((null parsed-xml) "")
  116. ((stringp parsed-xml) parsed-xml)
  117. ((symbolp (car parsed-xml))
  118. (let ((attributes (mapconcat
  119. (lambda (av)
  120. (format "%s=\"%s\"" (car av) (cdr av)))
  121. (cadr parsed-xml) " ")))
  122. (if (or (cddr parsed-xml) contents)
  123. (format "\n<%s%s>%s\n</%s>"
  124. (car parsed-xml)
  125. (if (string= attributes "") "" (concat " " attributes))
  126. (concat (org-freemind--serialize (cddr parsed-xml))
  127. contents )
  128. (car parsed-xml))
  129. (format "\n<%s%s/>"
  130. (car parsed-xml)
  131. (if (string= attributes "") "" (concat " " attributes))))))
  132. (t (mapconcat #'org-freemind--serialize parsed-xml ""))))
  133. (defun org-freemind--parse-xml (xml-string)
  134. "Return parse tree for XML-STRING using `libxml-parse-xml-region'.
  135. For purposes of Freemind export, XML-STRING is a node style
  136. specification - \"<node ...>...</node>\" - as a string."
  137. (with-temp-buffer
  138. (insert (or xml-string ""))
  139. (libxml-parse-xml-region (point-min) (point-max))))
  140. ;;;; Style mappers :: Default and Automatic layout
  141. (defun org-freemind-style-map--automatic (element info)
  142. "Return a node style corresponding to relative outline level of ELEMENT.
  143. ELEMENT can be any of the following types - `org-data',
  144. `headline' or `section'. See `org-freemind-styles' for style
  145. mappings of different outline levels."
  146. (let ((style-name
  147. (case (org-element-type element)
  148. (headline
  149. (org-export-get-relative-level element info))
  150. (section
  151. (let ((parent (org-export-get-parent-headline element)))
  152. (if (not parent) 1
  153. (1+ (org-export-get-relative-level parent info)))))
  154. (t 0))))
  155. (or (assoc-default style-name org-freemind-styles)
  156. (assoc-default 'default org-freemind-styles)
  157. "<node></node>")))
  158. (defun org-freemind-style-map--default (element info)
  159. "Return the default style for all ELEMENTs.
  160. ELEMENT can be any of the following types - `org-data',
  161. `headline' or `section'. See `org-freemind-styles' for current
  162. value of default style."
  163. (or (assoc-default 'default org-freemind-styles)
  164. "<node></node>"))
  165. ;;;; Helpers :: Retrieve, apply Freemind styles
  166. (defun org-freemind--get-node-style (element info)
  167. "Return Freemind node style applicable for HEADLINE.
  168. ELEMENT is an Org element of type `org-data', `headline' or
  169. `section'. INFO is a plist holding contextual information."
  170. (unless (fboundp org-freemind-style-map-function)
  171. (setq org-freemind-style-map-function 'org-freemind-style-map--default))
  172. (let ((style (funcall org-freemind-style-map-function element info)))
  173. ;; Sanitize node style.
  174. ;; Loop through the attributes of node element and purge those
  175. ;; attributes that look suspicious. This is an extra bit of work
  176. ;; that allows one to copy verbatim node styles from an existing
  177. ;; Freemind Mindmap file without messing with the exported data.
  178. (let* ((data (org-freemind--parse-xml style))
  179. (attributes (cadr data))
  180. (ignored-attrs '(POSITION FOLDED TEXT CREATED ID
  181. MODIFIED)))
  182. (let (attr)
  183. (while (setq attr (pop ignored-attrs))
  184. (setq attributes (assq-delete-all attr attributes))))
  185. (when data (setcar (cdr data) attributes))
  186. (org-freemind--serialize data))))
  187. (defun org-freemind--build-stylized-node (style-1 style-2 &optional contents)
  188. "Build a Freemind node with style STYLE-1 + STYLE-2 and add CONTENTS to it.
  189. STYLE-1 and STYLE-2 are Freemind node styles as a string.
  190. STYLE-1 is the base node style and STYLE-2 is the overriding
  191. style that takes precedence over STYLE-1. CONTENTS is a string.
  192. Return value is a Freemind node with following properties:
  193. 1. The attributes of \"<node ...> </node>\" element is the union
  194. of corresponding attributes of STYLE-1 and STYLE-2. When
  195. STYLE-1 and STYLE-2 specify values for the same attribute
  196. name, choose the attribute value from STYLE-2.
  197. 2. The children of \"<node ...> </node>\" element is the union of
  198. top-level children of STYLE-1 and STYLE-2 with CONTENTS
  199. appended to it. When STYLE-1 and STYLE-2 share a child
  200. element of same type, the value chosen is that from STYLE-2.
  201. For example, merging with following parameters
  202. STYLE-1 =>
  203. <node COLOR=\"#00b439\" STYLE=\"Bubble\">
  204. <edge STYLE=\"bezier\" WIDTH=\"thin\"/>
  205. <font NAME=\"SansSerif\" SIZE=\"16\"/>
  206. </node>
  207. STYLE-2 =>
  208. <node COLOR=\"#990000\" FOLDED=\"true\">
  209. <font NAME=\"SansSerif\" SIZE=\"14\"/>
  210. </node>
  211. CONTENTS =>
  212. <attribute NAME=\"ORGTAG\" VALUE=\"@home\"/>
  213. will result in following node:
  214. RETURN =>
  215. <node STYLE=\"Bubble\" COLOR=\"#990000\" FOLDED=\"true\">
  216. <edge STYLE=\"bezier\" WIDTH=\"thin\"/>
  217. <font NAME=\"SansSerif\" SIZE=\"14\"/>
  218. <attribute NAME=\"ORGTAG\" VALUE=\"@home\"/>
  219. </node>."
  220. (let* ((data1 (org-freemind--parse-xml (or style-1 "")))
  221. (data2 (org-freemind--parse-xml (or style-2 "")))
  222. (attr1 (cadr data1))
  223. (attr2 (cadr data2))
  224. (merged-attr attr2)
  225. (children1 (cddr data1))
  226. (children2 (cddr data2))
  227. (merged-children children2))
  228. (let (attr)
  229. (while (setq attr (pop attr1))
  230. (unless (assq (car attr) merged-attr)
  231. (push attr merged-attr))))
  232. (let (child)
  233. (while (setq child (pop children1))
  234. (when (or (stringp child) (not (assq (car child) merged-children)))
  235. (push child merged-children))))
  236. (let ((merged-data (nconc (list 'node merged-attr) merged-children)))
  237. (org-freemind--serialize merged-data contents))))
  238. ;;;; Helpers :: Node contents
  239. (defun org-freemind--richcontent (type contents &optional css-style)
  240. (let* ((type (case type
  241. (note "NOTE")
  242. (node "NODE")
  243. (t "NODE")))
  244. (contents (org-trim contents)))
  245. (if (string= (org-trim contents) "") ""
  246. (format "\n<richcontent TYPE=\"%s\">%s\n</richcontent>"
  247. type
  248. (format "\n<html>\n<head>%s\n</head>\n%s\n</html>"
  249. (or css-style "")
  250. (format "<body>\n%s\n</body>" contents))))))
  251. (defun org-freemind--build-node-contents (element contents info)
  252. (let* ((title (case (org-element-type element)
  253. (headline
  254. (org-element-property :title element))
  255. (org-data
  256. (plist-get info :title))
  257. (t (error "Shouldn't come here"))))
  258. (element-contents (org-element-contents element))
  259. (section (assq 'section element-contents))
  260. (section-contents
  261. (let ((backend (org-export-create-backend
  262. :parent (org-export-backend-name
  263. (plist-get info :back-end))
  264. :transcoders '((section . (lambda (e c i) c))))))
  265. (org-export-data-with-backend section backend info)))
  266. (itemized-contents-p (let ((first-child-headline
  267. (org-element-map element-contents
  268. 'headline 'identity info t)))
  269. (when first-child-headline
  270. (org-export-low-level-p first-child-headline
  271. info))))
  272. (node-contents (concat section-contents
  273. (when itemized-contents-p
  274. contents))))
  275. (concat (let ((title (org-export-data title info)))
  276. (case org-freemind-section-format
  277. (inline
  278. (org-freemind--richcontent
  279. 'node (concat (format "\n<h2>%s</h2>" title)
  280. node-contents) ))
  281. (note
  282. (concat (org-freemind--richcontent
  283. 'node (format "\n<p>%s\n</p>" title))
  284. (org-freemind--richcontent
  285. 'note node-contents)))
  286. (node
  287. (concat
  288. (org-freemind--richcontent
  289. 'node (format "\n<p>%s\n</p>" title))
  290. (when section
  291. (org-freemind--build-stylized-node
  292. (org-freemind--get-node-style section info) nil
  293. (org-freemind--richcontent 'node node-contents)))))))
  294. (unless itemized-contents-p
  295. contents))))
  296. ;;; Template
  297. (defun org-freemind-template (contents info)
  298. "Return complete document string after Freemind Mindmap conversion.
  299. CONTENTS is the transcoded contents string. RAW-DATA is the
  300. original parsed data. INFO is a plist holding export options."
  301. (format
  302. "<map version=\"0.9.0\">\n%s\n</map>"
  303. (org-freemind--build-stylized-node
  304. (org-freemind--get-node-style nil info) nil
  305. (let ((org-data (plist-get info :parse-tree)))
  306. (org-freemind--build-node-contents org-data contents info)))))
  307. (defun org-freemind-inner-template (contents info)
  308. "Return body of document string after Freemind Mindmap conversion.
  309. CONTENTS is the transcoded contents string. INFO is a plist
  310. holding export options."
  311. contents)
  312. ;;;; Tags
  313. (defun org-freemind--tags (tags)
  314. (mapconcat (lambda (tag)
  315. (format "\n<attribute NAME=\"%s\" VALUE=\"%s\"/>" tag ""))
  316. tags "\n"))
  317. ;;; Transcode Functions
  318. ;;;; Entity
  319. (defun org-freemind-entity (entity contents info)
  320. "Transcode an ENTITY object from Org to Freemind Mindmap.
  321. CONTENTS are the definition itself. INFO is a plist holding
  322. contextual information."
  323. (org-element-property :utf-8 entity))
  324. ;;;; Headline
  325. (defun org-freemind-headline (headline contents info)
  326. "Transcode a HEADLINE element from Org to Freemind Mindmap.
  327. CONTENTS holds the contents of the headline. INFO is a plist
  328. holding contextual information."
  329. ;; Empty contents?
  330. (setq contents (or contents ""))
  331. (let* ((numberedp (org-export-numbered-headline-p headline info))
  332. (level (org-export-get-relative-level headline info))
  333. (text (org-export-data (org-element-property :title headline) info))
  334. (todo (and (plist-get info :with-todo-keywords)
  335. (let ((todo (org-element-property :todo-keyword headline)))
  336. (and todo (org-export-data todo info)))))
  337. (todo-type (and todo (org-element-property :todo-type headline)))
  338. (tags (and (plist-get info :with-tags)
  339. (org-export-get-tags headline info)))
  340. (priority (and (plist-get info :with-priority)
  341. (org-element-property :priority headline)))
  342. (section-number (and (not (org-export-low-level-p headline info))
  343. (org-export-numbered-headline-p headline info)
  344. (mapconcat 'number-to-string
  345. (org-export-get-headline-number
  346. headline info) ".")))
  347. ;; Create the headline text.
  348. (full-text (org-export-data (org-element-property :title headline)
  349. info))
  350. ;; Headline order (i.e, first digit of the section number)
  351. (headline-order (car (org-export-get-headline-number headline info))))
  352. (cond
  353. ;; Case 1: This is a footnote section: ignore it.
  354. ((org-element-property :footnote-section-p headline) nil)
  355. ;; Case 2. This is a deep sub-tree, export it as a list item.
  356. ;; Delegate the actual export to `html' backend.
  357. ((org-export-low-level-p headline info)
  358. (org-html-headline headline contents info))
  359. ;; Case 3. Standard headline. Export it as a section.
  360. (t
  361. (let* ((section-number (mapconcat 'number-to-string
  362. (org-export-get-headline-number
  363. headline info) "-"))
  364. (ids (remove 'nil
  365. (list (org-element-property :CUSTOM_ID headline)
  366. (concat "sec-" section-number)
  367. (org-element-property :ID headline))))
  368. (preferred-id (car ids))
  369. (extra-ids (cdr ids))
  370. (left-p (zerop (% headline-order 2))))
  371. (org-freemind--build-stylized-node
  372. (org-freemind--get-node-style headline info)
  373. (format "<node ID=\"%s\" POSITION=\"%s\" FOLDED=\"%s\">\n</node>"
  374. preferred-id
  375. (if left-p "left" "right")
  376. (if (= level 1) "true" "false"))
  377. (concat (org-freemind--build-node-contents headline contents info)
  378. (org-freemind--tags tags))))))))
  379. ;;;; Section
  380. (defun org-freemind-section (section contents info)
  381. "Transcode a SECTION element from Org to Freemind Mindmap.
  382. CONTENTS holds the contents of the section. INFO is a plist
  383. holding contextual information."
  384. (let ((parent (org-export-get-parent-headline section)))
  385. (when (and parent (org-export-low-level-p parent info))
  386. contents)))
  387. ;;; Filter Functions
  388. (defun org-freemind-final-function (contents backend info)
  389. "Return CONTENTS as pretty XML using `indent-region'."
  390. (if (not org-freemind-pretty-output) contents
  391. (with-temp-buffer
  392. (nxml-mode)
  393. (insert contents)
  394. (indent-region (point-min) (point-max))
  395. (buffer-substring-no-properties (point-min) (point-max)))))
  396. (defun org-freemind-options-function (info backend)
  397. "Install script in export options when appropriate.
  398. EXP-PLIST is a plist containing export options. BACKEND is the
  399. export back-end currently used."
  400. ;; Freemind/Freeplane doesn't seem to like named html entities in
  401. ;; richcontent. For now, turn off smart quote processing so that
  402. ;; entities like "&rsquo;" & friends are avoided in the exported
  403. ;; output.
  404. (plist-put info :with-smart-quotes nil))
  405. ;;; End-user functions
  406. ;;;###autoload
  407. (defun org-freemind-export-to-freemind
  408. (&optional async subtreep visible-only body-only ext-plist)
  409. "Export current buffer to a Freemind Mindmap file.
  410. If narrowing is active in the current buffer, only export its
  411. narrowed part.
  412. If a region is active, export that region.
  413. A non-nil optional argument ASYNC means the process should happen
  414. asynchronously. The resulting file should be accessible through
  415. the `org-export-stack' interface.
  416. When optional argument SUBTREEP is non-nil, export the sub-tree
  417. at point, extracting information from the headline properties
  418. first.
  419. When optional argument VISIBLE-ONLY is non-nil, don't export
  420. contents of hidden elements.
  421. When optional argument BODY-ONLY is non-nil, only write code
  422. between \"<body>\" and \"</body>\" tags.
  423. EXT-PLIST, when provided, is a property list with external
  424. parameters overriding Org default settings, but still inferior to
  425. file-local settings.
  426. Return output file's name."
  427. (interactive)
  428. (let* ((extension (concat ".mm" ))
  429. (file (org-export-output-file-name extension subtreep))
  430. (org-export-coding-system 'utf-8))
  431. (org-export-to-file 'freemind file
  432. async subtreep visible-only body-only ext-plist)))
  433. (provide 'ox-freemind)
  434. ;;; ox-freemind.el ends here