| blob | 01a8a8c7532ffdfe3fdedec1ada7db1c7269d127 |
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 yet 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 ;; org-export-generic is basically a simple translation system that
31 ;; knows how to parse at least most of a .org buffer and then add
32 ;; various formatting prefixes before and after each section type. It
33 ;; does this by examining a property list stored in org-generic-alist.
34 ;; You can dynamically add propety lists of your own using the
35 ;; org-set-generic-type function:
36 ;;
37 ;; (org-set-generic-type
38 ;; "really-basic-text"
39 ;; '(:file-suffix ".txt"
40 ;; :key-binding ?R
41 ;;
42 ;; :title-format "=== %s ===\n"
43 ;; :body-header-section-numbers t
44 ;; :body-header-section-number-format "%s) "
45 ;; :body-section-header-prefix "\n"
46 ;; :body-section-header-suffix "\n"
47 ;; :body-line-format " %s\n"
48 ;; :body-line-wrap 75
49 ;; ))
50 ;;
51 ;; Note: Upper case key-bindings are reserved for your use. Lower
52 ;; case key bindings may conflict with future export-generic
53 ;; publications.
54 ;;
55 ;; Then run org-export (ctrl-c ctrl-e) and select generic or run
56 ;; org-export-generic. You'll then be prompted with a list of export
57 ;; types to choose from which will include your new type assigned to
58 ;; the key "r".
59 ;;
60 ;; ----------------------------------------------------------------------
61 ;;
62 ;; TODO (non-ordered)
63 ;; * handle function references
64 ;; * handle other types of multi-complex-listy-things to do
65 ;; ideas: (t ?- "%s" ?-)
66 ;; * handle indent specifiers better
67 ;; ideas: (4 ?\ "%s")
68 ;; * need flag to remove indents from body text
69 ;; * handle links
70 ;; * handle internationalization strings better
71 ;; * date/author/etc needs improvment (internationalization too)
72 ;; * allow specifying of section ordering
73 ;; ideas: :ordering ("header" "toc" "body" "footer")
74 ;; ^ matches current hard coded ordering
75 ;; * err, actually *do* a footer
76 ;; * deal with usage of org globals
77 ;; *** should we even consider them, or let the per-section specifiers do it
78 ;; *** answer: remove; mostly removed now
79 ;; * deal with interactive support for picking a export specifier label
80 ;; * char specifiers that need extra length because of formatting
81 ;; idea: (?- 4) for 4-longer
82 ;; * centering specifier
83 ;; idea: ('center " -- %s -- ")
84 ;; * remove more of the unneeded export-to-ascii copy code
85 ;; * tags
86 ;; *** supported now, but need separate format per tag
87 ;; *** allow different open/closing prefixes
88 ;; * properties
89 ;; * drawers
90 ;; * Escape camel-case for wiki exporters.
91 ;; * Adjust to depth limits on headers --- need to roll-over from headers
92 ;; to lists, as per other exporters
93 ;; * optmization (many plist extracts should be in let vars)
94 ;; * define defcustom spec for the specifier list
95 ;; * fonts: at least monospace is not handled at all here.
96 ;;
97 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
98 ;;
99 ;;; Commentary:
105 "Options specific for ASCII export of Org-mode files."
110 "Non-nil means convert links to notes before the next headline.
111 When nil, the link will be exported in place. If the line becomes long
112 in this way, it will be wrapped."
120 '(
121 ;;
122 ;; generic DEMO exporter
123 ;;
124 ;; (this tries to use every specifier for demo purposes)
125 ;;
128 :key-binding ?d
133 :author-export t
134 :tags-export t
136 :drawers-export t
143 :date-export t
148 :toc-export t
156 :toc-section-numbers t
160 :toc-indent-char ?\
163 :toc-tags-export t
171 ; lists indicate different things per level
172 ; list contents or straight value can either be a
173 ; ?x char reference for printing strings that match the header len
174 ; "" string to print directly
181 :timestamps-export t
182 :priorities-export t
183 :todo-keywords-export t
185 :body-tags-export t
189 ; section prefixes/suffixes can be direct strings or lists as well
192 ; :body-section-prefix ("<sec1>\n" "<sec2>\n" "<sec3>\n")
193 ; :body-section-suffix ("</sec1>\n" "</sec2>\n" "</sec3>\n")
196 ; if preformated text should be included (eg, : prefixed)
197 :body-line-export-preformated t
210 :body-number-list-leave-number t
222 ; other body lines
226 ; print above and below all body parts
230 )
232 ;;
233 ;; ascii exporter
234 ;;
235 ;; (close to the original ascii specifier)
236 ;;
239 :key-binding ?a
248 :date-export t
257 :toc-export t
258 :toc-section-numbers t
262 :toc-indent-char ?\
268 ; :body-section-header-prefix "\n"
269 ; :body-section-header-format "%s\n"
270 ; :body-section-header-suffix (?\$ ?\# ?^ ?\~ ?\= ?\-)
276 ; :body-section-marker-prefix ""
277 ; :body-section-marker-chars (?\$ ?\# ?^ ?\~ ?\= ?\-)
278 ; :body-section-marker-suffix "\n"
280 :body-line-export-preformated t
284 ; :body-text-prefix "<t>\n"
285 ; :body-text-suffix "</t>\n"
289 ; :body-bullet-list-suffix (?* ?+ ?-)
290 )
292 ;;
293 ;; wikipedia
294 ;;
297 :key-binding ?w
304 :date-export nil
306 :toc-export nil
308 :body-header-section-numbers nil
326 )
327 ;;
328 ;; mediawiki
329 ;;
332 :key-binding ?m
339 :date-export nil
341 :toc-export nil
343 :body-header-section-numbers nil
371 )
372 ;;
373 ;; internet-draft .xml for xml2rfc exporter
374 ;;
376 ;; this tries to use every specifier for demo purposes
378 :key-binding ?i
382 <!ENTITY rfcs PUBLIC '' 'blah'>
390 <front>
391 "
394 <organization>Comany, Inc..</organization>
395 <address>
396 <postal>
397 <street></street>
398 <city></city>
399 <region></region>
400 <code></code>
401 <country></country>
402 </postal>
403 <phone></phone>
404 <email></email>
405 </address>
406 </author>
408 <area>Operations and Management</area>
409 <workgroup>FIXME</workgroup>
411 :date-export nil
413 :toc-export nil
415 :body-header-section-numbers nil
420 ; if preformated text should be included (eg, : prefixed)
421 :body-line-export-preformated t
425 ; other body lines
429 ; print above and below all body parts
437 )
440 :key-binding ?T
442 ;; lifted from wikipedia exporter
448 :date-export nil
450 :toc-export nil
452 :body-header-section-numbers nil
468 ;; :body-list-prefix "LISTSTART"
469 ;; :body-list-suffix "LISTEND"
471 ;; this is ignored! [2010/02/02:rpg]
473 )
476 :key-binding ?U
478 ;; lifted from wikipedia exporter
484 :date-export nil
486 :toc-export nil
488 :body-header-section-numbers nil
499 :body-line-wrap nil
505 ;; :body-list-prefix "LISTSTART"
506 ;; :body-list-suffix "LISTEND"
516 )
517 )
518 "A assoc list of property lists to specify export definitions"
519 )
526 ;;;###autoload
528 "Adds a TYPE and DEFINITION to the existing list of defined generic
529 export definitions."
532 ;;; helper functions for org-set-generic-type
535 &key documentation
536 type)
537 "Define KEYWORD as a legitimate element for inclusion in
538 the body of an org-set-generic-type definition."
541 ;; TODO: push the documentation and type information
542 ;; somewhere where it will do us some good.
543 ))
547 inserted in the output for every blank line in the input.
548 The intention is to handle formats where text is flowed, and
549 newlines are interpreted as significant \(e.g., as indicating
550 preformatted text\). A common non-nil value for this keyword
552 :body-line-format that does NOT end with a newline."
555 ;;; fontification keywords
571 )
574 "checks to see if type is already in use, or we're switching parts
575 If we're switching, then insert a potentially previously remembered
576 suffix, and insert the current prefix immediately and then save the
577 suffix a later change time."
587 ;;;###autoload
589 "Export the outline as generic output.
590 If there is an active region, export only the region.
591 The prefix ARG specifies how many levels of the outline should become
592 underlined headlines. The default is 3."
615 opt-plist)))
617 helpstart
624 org-generic-alist))
628 \[ ] the current setting of the org-generic-export-type variable
638 org-generic-alist)
641 r1 r2 ass
643 ;; read in the type to use
661 org-generic-alist))))
678 filesuffix))
682 filename))
698 ; (quote-re (concat "^\\(\\*+\\)\\([ \t]*" org-quote-string "\\>\\)"))
708 region
710 :skip-before-1st-heading
718 :verbatim-multiline t
721 :emph-multiline t
722 :archived-trees
726 ;; export-generic plist variables
798 ;; dynamic variables used heinously in fontification
799 ;; not referenced locally...
809 thetoc toctags have-headings first-heading-pos
810 table-open table-buffer link-buffer link desc desc0 rpl wrap)
828 ;; create local variables for all options, to make sure all called
829 ;; functions get the correct information
833 org-export-plist-vars)
836 org-export-headline-levels))
839 ;; File header
843 :title-prefix
844 :title-format
862 :date-prefix
863 :date-format
866 ;; export the table of contents first
871 :toc-header-prefix
872 :toc-header-format
874 thetoc)
881 ;; This is a headline
885 level-offset)
888 todo
892 org-done-keywords)))
893 ; TODO, not DONE
897 line lines level))))
904 t t txt)))
909 txt))
911 ; include tags but formated
914 txt)
917 toctags
920 export-plist :toc-tags-prefix
924 txt)
938 tocindentchar)
947 txt)
949 toctags)
951 thetoc)
953 ))))
954 lines)
966 ;; Remove the quoted HTML tags.
967 ;; XXX
969 ;; Replace links with the description when possible
970 ;; XXX
981 org-export-code-refs)))
982 t t line))
997 ;;
998 ;; a Headline
999 ;;
1004 level-offset))
1011 ;;
1012 ;; a Table
1013 ;;
1017 ;; New table starts
1019 ;; Accumulate table lines
1033 ;;
1034 ;; pre-formatted text
1035 ;;
1043 ;; if the bullet list item is an asterisk, the leading space is /mandatory/
1044 ;; [2010/02/02:rpg]
1046 ;;
1047 ;; plain list item
1048 ;; TODO: nested lists
1049 ;;
1050 ;; first add a line break between any previous paragraph or line item and this
1051 ;; one
1055 ;; I believe this gets rid of leading whitespace.
1058 ;; won't this insert the suffix /before/ the last line of the list?
1059 ;; also isn't it spoofed by bulleted lists that have a line skip between the list items
1060 ;; unless 'org-empty-line-terminates-plain-lists' is true?
1063 ;; deal with checkboxes
1067 listchecktodoend)))
1070 listcheckdoneend)))
1073 listcheckhalfend)))
1074 )
1078 ;;
1079 ;; numbered list item
1080 ;;
1081 ;; TODO: nested lists
1082 ;;
1086 numlistprefix numlistsuffix)
1088 ;; deal with checkboxes
1089 ;; TODO: whoops; leaving the numbers is a problem for ^ matching
1093 listchecktodoend)))
1096 listcheckdoneend)))
1099 listcheckhalfend)))
1100 )
1109 ;; blank line
1113 ;;
1114 ;; body
1115 ;;
1121 ;; XXX: properties? list?
1127 ;; Remove forced line breaks
1132 ;; XXX: was dependent on wrap var which was calculated by???
1139 ;; if we're at a level > 0; insert the closing body level stuff
1153 ;; insert the table of contents
1165 ;; Convert whitespace place holders
1176 ;; remove display and invisible chars
1193 "converts a property specification to a string given types of properties
1195 The EXPORT-PLIST should be defined as the lookup plist.
1196 The PROP should be the property name to search for in it.
1197 LEN is set to the length of multi-characters strings to generate (or 0)
1198 N is the tree depth
1199 REVERSE means to reverse the list if the plist match is a list
1200 "
1202 subtype)
1206 ;; sequence of chars
1209 prefixtype)
1217 subtype
1220 ))
1223 prefixprop formatprop postfixprop
1225 "convert a header to an output string given formatting property names"
1232 ))
1235 "Do extra work for ASCII export"
1236 ;; Put quotes around verbatim text
1244 ;; Remove target markers
1250 "Handle quoted HTML for ASCII export."
1253 ;; We just remove the tags for now.
1255 line)
1258 "Wrap LINE at or before WHERE."
1263 pos didfirst)
1285 "Push out links in the buffer."
1287 ;; We still have links to push out.
1297 link-buffer))
1302 "Insert a new level in a generic export."
1309 char tagstring)
1315 ;; going deeper
1322 ))
1323 ;; going up
1330 ))
1331 ;; same level
1335 )
1336 )
1341 secnums
1348 ;; handle tags and formatting
1354 export-plist
1355 :body-tags-prefix
1356 :body-tags-format
1364 :body-section-header-prefix
1365 :body-section-header-format
1366 :body-section-header-suffix
1367 level))
1374 "Insert the string S centered and underline it with character UNDERLINE."
1384 "Format a table for ascii export."
1388 ;; Table made by table.el - test for spanning
1389 lines
1391 ;; A normal org table
1392 ;; Get rid of hlines at beginning and end
1398 ;; Check if the table has a marking column. If yes remove the
1399 ;; column and the special lines
1401 ;; Get rid of the vertical lines except for grouping
1411 (setq line (replace-match (concat bodytablefirstcellstart bodytablecellstart " \\1 " bodytablecellend bodytablelastcellend) t nil line)))
1413 (setq start (+ (match-end 0) (length (concat bodytablecellend bodytableinteriorcellend bodytableinteriorcellstart bodytablecellstart))))
1414 (or (pop vl1) (setq line (replace-match (concat bodytablecellend bodytableinteriorcellend bodytableinteriorcellstart bodytablecellstart) t t line)))))
1430 vl))
1433 ;;; FIXME: this should probably turn into a defconstant later [2010/05/20:rpg]
1441 "Alist of org format -> formatting variables for fontification.
1442 Each element of the list is a list of three elements.
1443 The first element is the character used as a marker for fontification.
1444 The second element is a variable name, set in org-export-generic. That
1445 variable will be dereferenced to obtain a formatting string to wrap
1446 fontified text with.
1447 The third element decides whether to protect converted text from other
1450 ;;; Cargo-culted from the latex translation. I couldn't figure out how
1451 ;;; to keep the structure since the generic export operates on lines, rather
1452 ;;; than on a buffer as in the latex export, meaning that none of the
1453 ;;; search forward code could be kept. This led me to rewrite the
1454 ;;; whole thing recursively. A huge lose for efficiency (potentially),
1455 ;;; but I couldn't figure out how to make the looping work.
1456 ;;; Worse, it's /doubly/ recursive, because this function calls
1457 ;;; org-export-generic-emph-format, which can call it recursively...
1458 ;;; [2010/05/20:rpg]
1460 "Convert fontification according to generic rules."
1462 ;; The match goes one char after the *string*, except at the end of a line
1464 org-export-generic-emphasis-alist))
1470 ;; now we need to determine whether we have strikethrough or
1471 ;; a list, which is a bit nasty
1475 ;; a list --- skip this match and recurse on the point after the
1476 ;; first emph char...
1486 string))
1489 "Return a string that results from applying the markup indicated by
1490 FORMAT-VARNAME to STRING."
1494 string
1498 string-to-emphasize))))
1503 ;;; org-export-generic.el ends here