| blob | d04105c3d11a977df6a408f378adbaab2ef349b4 |
1 ;; org-export-generic.el --- Export frameworg with custom backends
3 ;; Copyright (C) 2009-2012 Free Software Foundation, Inc.
5 ;; Author: Wes Hardaker <hardaker at users dot sourceforge dot net>
6 ;; Keywords: outlines, hypermedia, calendar, wp, export
7 ;; Homepage: http://orgmode.org
8 ;; Version: 6.25trans
9 ;; Acks: Much of this code was stolen form the ascii export from Carsten
10 ;;
11 ;; This file is not part of GNU Emacs.
12 ;;
13 ;; GNU Emacs is free software: you can redistribute it and/or modify
14 ;; it under the terms of the GNU General Public License as published by
15 ;; the Free Software Foundation, either version 3 of the License, or
16 ;; (at your option) any later version.
18 ;; GNU Emacs is distributed in the hope that it will be useful,
19 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
20 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 ;; GNU General Public License for more details.
23 ;; You should have received a copy of the GNU General Public License
24 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
25 ;;
26 ;; ----------------------------------------------------------------------
27 ;;
28 ;; OVERVIEW
29 ;;
30 ;; IMPORTANT: IF YOU WANT TO WRITE A NEW EXPORTER FOR ORG, PLEASE
31 ;; CHECK contrib/lisp/org-export.el -- ORG-EXPORT-GENERIC.EL, WHILE
32 ;; STILL USEFUL, SHOULD NOT BE USED FOR NEW EXPORTERS.
33 ;;
34 ;; org-export-generic is basically a simple translation system that
35 ;; knows how to parse at least most of a .org buffer and then add
36 ;; various formatting prefixes before and after each section type. It
37 ;; does this by examining a property list stored in org-generic-alist.
38 ;; You can dynamically add propety lists of your own using the
39 ;; org-set-generic-type function:
40 ;;
41 ;; (org-set-generic-type
42 ;; "really-basic-text"
43 ;; '(:file-suffix ".txt"
44 ;; :key-binding ?R
45 ;;
46 ;; :title-format "=== %s ===\n"
47 ;; :body-header-section-numbers t
48 ;; :body-header-section-number-format "%s) "
49 ;; :body-section-header-prefix "\n"
50 ;; :body-section-header-suffix "\n"
51 ;; :body-line-format " %s\n"
52 ;; :body-line-wrap 75
53 ;; ))
54 ;;
55 ;; Note: Upper case key-bindings are reserved for your use. Lower
56 ;; case key bindings may conflict with future export-generic
57 ;; publications.
58 ;;
59 ;; Then run org-export (ctrl-c ctrl-e) and select generic or run
60 ;; org-export-generic. You'll then be prompted with a list of export
61 ;; types to choose from which will include your new type assigned to
62 ;; the key "r".
63 ;;
64 ;; ----------------------------------------------------------------------
65 ;;
66 ;; TODO (non-ordered)
67 ;; * handle function references
68 ;; * handle other types of multi-complex-listy-things to do
69 ;; ideas: (t ?- "%s" ?-)
70 ;; * handle indent specifiers better
71 ;; ideas: (4 ?\ "%s")
72 ;; * need flag to remove indents from body text
73 ;; * handle links
74 ;; * handle internationalization strings better
75 ;; * date/author/etc needs improvment (internationalization too)
76 ;; * allow specifying of section ordering
77 ;; ideas: :ordering ("header" "toc" "body" "footer")
78 ;; ^ matches current hard coded ordering
79 ;; * err, actually *do* a footer
80 ;; * deal with usage of org globals
81 ;; *** should we even consider them, or let the per-section specifiers do it
82 ;; *** answer: remove; mostly removed now
83 ;; * deal with interactive support for picking a export specifier label
84 ;; * char specifiers that need extra length because of formatting
85 ;; idea: (?- 4) for 4-longer
86 ;; * centering specifier
87 ;; idea: ('center " -- %s -- ")
88 ;; * remove more of the unneeded export-to-ascii copy code
89 ;; * tags
90 ;; *** supported now, but need separate format per tag
91 ;; *** allow different open/closing prefixes
92 ;; * properties
93 ;; * drawers
94 ;; * Escape camel-case for wiki exporters.
95 ;; * Adjust to depth limits on headers --- need to roll-over from headers
96 ;; to lists, as per other exporters
97 ;; * optmization (many plist extracts should be in let vars)
98 ;; * define defcustom spec for the specifier list
99 ;; * fonts: at least monospace is not handled at all here.
100 ;;
101 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
102 ;;
103 ;;; Commentary:
110 "Options specific for ASCII export of Org-mode files."
115 "Non-nil means convert links to notes before the next headline.
116 When nil, the link will be exported in place. If the line becomes long
117 in this way, it will be wrapped."
125 '(
126 ;;
127 ;; generic DEMO exporter
128 ;;
129 ;; (this tries to use every specifier for demo purposes)
130 ;;
133 :key-binding ?d
138 :author-export t
139 :tags-export t
141 :drawers-export t
148 :date-export t
153 :toc-export t
161 :toc-section-numbers t
165 :toc-indent-char ?\
168 :toc-tags-export t
176 ; lists indicate different things per level
177 ; list contents or straight value can either be a
178 ; ?x char reference for printing strings that match the header len
179 ; "" string to print directly
186 :timestamps-export t
187 :priorities-export t
188 :todo-keywords-export t
190 :body-tags-export t
194 ; section prefixes/suffixes can be direct strings or lists as well
197 ; :body-section-prefix ("<sec1>\n" "<sec2>\n" "<sec3>\n")
198 ; :body-section-suffix ("</sec1>\n" "</sec2>\n" "</sec3>\n")
201 ; if preformated text should be included (eg, : prefixed)
202 :body-line-export-preformated t
215 :body-number-list-leave-number t
227 ; other body lines
231 ; print above and below all body parts
235 )
237 ;;
238 ;; ascii exporter
239 ;;
240 ;; (close to the original ascii specifier)
241 ;;
244 :key-binding ?a
253 :date-export t
262 :toc-export t
263 :toc-section-numbers t
267 :toc-indent-char ?\
273 ; :body-section-header-prefix "\n"
274 ; :body-section-header-format "%s\n"
275 ; :body-section-header-suffix (?\$ ?\# ?^ ?\~ ?\= ?\-)
281 ; :body-section-marker-prefix ""
282 ; :body-section-marker-chars (?\$ ?\# ?^ ?\~ ?\= ?\-)
283 ; :body-section-marker-suffix "\n"
285 :body-line-export-preformated t
289 ; :body-text-prefix "<t>\n"
290 ; :body-text-suffix "</t>\n"
294 ; :body-bullet-list-suffix (?* ?+ ?-)
295 )
297 ;;
298 ;; wikipedia
299 ;;
302 :key-binding ?w
309 :date-export nil
311 :toc-export nil
313 :body-header-section-numbers nil
331 )
332 ;;
333 ;; mediawiki
334 ;;
337 :key-binding ?m
344 :date-export nil
346 :toc-export nil
348 :body-header-section-numbers nil
376 )
377 ;;
378 ;; internet-draft .xml for xml2rfc exporter
379 ;;
381 ;; this tries to use every specifier for demo purposes
383 :key-binding ?i
387 <!ENTITY rfcs PUBLIC '' 'blah'>
395 <front>
396 "
399 <organization>Comany, Inc..</organization>
400 <address>
401 <postal>
402 <street></street>
403 <city></city>
404 <region></region>
405 <code></code>
406 <country></country>
407 </postal>
408 <phone></phone>
409 <email></email>
410 </address>
411 </author>
413 <area>Operations and Management</area>
414 <workgroup>FIXME</workgroup>
416 :date-export nil
418 :toc-export nil
420 :body-header-section-numbers nil
425 ; if preformated text should be included (eg, : prefixed)
426 :body-line-export-preformated t
430 ; other body lines
434 ; print above and below all body parts
442 )
445 :key-binding ?T
447 ;; lifted from wikipedia exporter
453 :date-export nil
455 :toc-export nil
457 :body-header-section-numbers nil
473 ;; :body-list-prefix "LISTSTART"
474 ;; :body-list-suffix "LISTEND"
476 ;; this is ignored! [2010/02/02:rpg]
478 )
481 :key-binding ?U
483 ;; lifted from wikipedia exporter
489 :date-export nil
491 :toc-export nil
493 :body-header-section-numbers nil
504 :body-line-wrap nil
510 ;; :body-list-prefix "LISTSTART"
511 ;; :body-list-suffix "LISTEND"
521 )
522 )
523 "A assoc list of property lists to specify export definitions"
524 )
531 ;;;###autoload
533 "Adds a TYPE and DEFINITION to the existing list of defined generic
534 export definitions."
537 ;;; helper functions for org-set-generic-type
540 &key documentation
541 type)
542 "Define KEYWORD as a legitimate element for inclusion in
543 the body of an org-set-generic-type definition."
546 ;; TODO: push the documentation and type information
547 ;; somewhere where it will do us some good.
548 ))
552 inserted in the output for every blank line in the input.
553 The intention is to handle formats where text is flowed, and
554 newlines are interpreted as significant \(e.g., as indicating
555 preformatted text\). A common non-nil value for this keyword
557 :body-line-format that does NOT end with a newline."
560 ;;; fontification keywords
576 )
579 "checks to see if type is already in use, or we're switching parts
580 If we're switching, then insert a potentially previously remembered
581 suffix, and insert the current prefix immediately and then save the
582 suffix a later change time."
592 ;;;###autoload
594 "Export the outline as generic output.
595 If there is an active region, export only the region.
596 The prefix ARG specifies how many levels of the outline should become
597 underlined headlines. The default is 3."
620 opt-plist)))
622 helpstart
629 org-generic-alist))
633 \[ ] the current setting of the org-generic-export-type variable
643 org-generic-alist)
646 r1 r2 ass
648 ;; read in the type to use
666 org-generic-alist))))
683 filesuffix))
687 filename))
703 ; (quote-re (concat "^\\(\\*+\\)\\([ \t]*" org-quote-string "\\>\\)"))
713 region
715 :skip-before-1st-heading
723 :verbatim-multiline t
726 :emph-multiline t
727 :archived-trees
731 ;; export-generic plist variables
803 ;; dynamic variables used heinously in fontification
804 ;; not referenced locally...
814 thetoc toctags have-headings first-heading-pos
815 table-open table-buffer link-buffer link desc desc0 rpl wrap)
833 ;; create local variables for all options, to make sure all called
834 ;; functions get the correct information
838 org-export-plist-vars)
841 org-export-headline-levels))
844 ;; File header
848 :title-prefix
849 :title-format
867 :date-prefix
868 :date-format
871 ;; export the table of contents first
876 :toc-header-prefix
877 :toc-header-format
879 thetoc)
886 ;; This is a headline
890 level-offset)
893 todo
897 org-done-keywords)))
898 ; TODO, not DONE
902 line lines level))))
909 t t txt)))
914 txt))
916 ; include tags but formated
919 txt)
922 toctags
925 export-plist :toc-tags-prefix
929 txt)
943 tocindentchar)
952 txt)
954 toctags)
956 thetoc)
958 ))))
959 lines)
971 ;; Remove the quoted HTML tags.
972 ;; XXX
974 ;; Replace links with the description when possible
975 ;; XXX
986 org-export-code-refs)))
987 t t line))
1002 ;;
1003 ;; a Headline
1004 ;;
1009 level-offset))
1016 ;;
1017 ;; a Table
1018 ;;
1022 ;; New table starts
1024 ;; Accumulate table lines
1038 ;;
1039 ;; pre-formatted text
1040 ;;
1048 ;; if the bullet list item is an asterisk, the leading space is /mandatory/
1049 ;; [2010/02/02:rpg]
1051 ;;
1052 ;; plain list item
1053 ;; TODO: nested lists
1054 ;;
1055 ;; first add a line break between any previous paragraph or line item and this
1056 ;; one
1060 ;; I believe this gets rid of leading whitespace.
1063 ;; won't this insert the suffix /before/ the last line of the list?
1064 ;; also isn't it spoofed by bulleted lists that have a line skip between the list items
1065 ;; unless 'org-empty-line-terminates-plain-lists' is true?
1068 ;; deal with checkboxes
1072 listchecktodoend)))
1075 listcheckdoneend)))
1078 listcheckhalfend)))
1079 )
1083 ;;
1084 ;; numbered list item
1085 ;;
1086 ;; TODO: nested lists
1087 ;;
1091 numlistprefix numlistsuffix)
1093 ;; deal with checkboxes
1094 ;; TODO: whoops; leaving the numbers is a problem for ^ matching
1098 listchecktodoend)))
1101 listcheckdoneend)))
1104 listcheckhalfend)))
1105 )
1114 ;; blank line
1118 ;;
1119 ;; body
1120 ;;
1126 ;; XXX: properties? list?
1132 ;; Remove forced line breaks
1137 ;; XXX: was dependent on wrap var which was calculated by???
1144 ;; if we're at a level > 0; insert the closing body level stuff
1158 ;; insert the table of contents
1170 ;; Convert whitespace place holders
1181 ;; remove display and invisible chars
1198 "converts a property specification to a string given types of properties
1200 The EXPORT-PLIST should be defined as the lookup plist.
1201 The PROP should be the property name to search for in it.
1202 LEN is set to the length of multi-characters strings to generate (or 0)
1203 N is the tree depth
1204 REVERSE means to reverse the list if the plist match is a list
1205 "
1207 subtype)
1211 ;; sequence of chars
1214 prefixtype)
1222 subtype
1225 ))
1228 prefixprop formatprop postfixprop
1230 "convert a header to an output string given formatting property names"
1237 ))
1240 "Do extra work for ASCII export"
1241 ;; Put quotes around verbatim text
1249 ;; Remove target markers
1255 "Handle quoted HTML for ASCII export."
1258 ;; We just remove the tags for now.
1260 line)
1263 "Wrap LINE at or before WHERE."
1268 pos didfirst)
1290 "Push out links in the buffer."
1292 ;; We still have links to push out.
1302 link-buffer))
1307 "Insert a new level in a generic export."
1314 char tagstring)
1320 ;; going deeper
1327 ))
1328 ;; going up
1335 ))
1336 ;; same level
1340 )
1341 )
1346 secnums
1353 ;; handle tags and formatting
1359 export-plist
1360 :body-tags-prefix
1361 :body-tags-format
1369 :body-section-header-prefix
1370 :body-section-header-format
1371 :body-section-header-suffix
1372 level))
1379 "Insert the string S centered and underline it with character UNDERLINE."
1389 "Format a table for ascii export."
1393 ;; Table made by table.el - test for spanning
1394 lines
1396 ;; A normal org table
1397 ;; Get rid of hlines at beginning and end
1403 ;; Check if the table has a marking column. If yes remove the
1404 ;; column and the special lines
1406 ;; Get rid of the vertical lines except for grouping
1416 (setq line (replace-match (concat bodytablefirstcellstart bodytablecellstart " \\1 " bodytablecellend bodytablelastcellend) t nil line)))
1418 (setq start (+ (match-end 0) (length (concat bodytablecellend bodytableinteriorcellend bodytableinteriorcellstart bodytablecellstart))))
1419 (or (pop vl1) (setq line (replace-match (concat bodytablecellend bodytableinteriorcellend bodytableinteriorcellstart bodytablecellstart) t t line)))))
1435 vl))
1438 ;;; FIXME: this should probably turn into a defconstant later [2010/05/20:rpg]
1446 "Alist of org format -> formatting variables for fontification.
1447 Each element of the list is a list of three elements.
1448 The first element is the character used as a marker for fontification.
1449 The second element is a variable name, set in org-export-generic. That
1450 variable will be dereferenced to obtain a formatting string to wrap
1451 fontified text with.
1452 The third element decides whether to protect converted text from other
1455 ;;; Cargo-culted from the latex translation. I couldn't figure out how
1456 ;;; to keep the structure since the generic export operates on lines, rather
1457 ;;; than on a buffer as in the latex export, meaning that none of the
1458 ;;; search forward code could be kept. This led me to rewrite the
1459 ;;; whole thing recursively. A huge lose for efficiency (potentially),
1460 ;;; but I couldn't figure out how to make the looping work.
1461 ;;; Worse, it's /doubly/ recursive, because this function calls
1462 ;;; org-export-generic-emph-format, which can call it recursively...
1463 ;;; [2010/05/20:rpg]
1465 "Convert fontification according to generic rules."
1467 ;; The match goes one char after the *string*, except at the end of a line
1469 org-export-generic-emphasis-alist))
1475 ;; now we need to determine whether we have strikethrough or
1476 ;; a list, which is a bit nasty
1480 ;; a list --- skip this match and recurse on the point after the
1481 ;; first emph char...
1491 string))
1494 "Return a string that results from applying the markup indicated by
1495 FORMAT-VARNAME to STRING."
1499 string
1503 string-to-emphasize))))
1508 ;;; org-export-generic.el ends here