org-export.el 101 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719
  1. ;;; org-export.el --- Generic Export Engine For Org
  2. ;; Copyright (C) 2011 Free Software Foundation, Inc.
  3. ;; Author: Nicolas Goaziou <n.goaziou at gmail dot com>
  4. ;; Keywords: outlines, hypermedia, calendar, wp
  5. ;; This program is free software; you can redistribute it and/or modify
  6. ;; it under the terms of the GNU General Public License as published by
  7. ;; the Free Software Foundation, either version 3 of the License, or
  8. ;; (at your option) any later version.
  9. ;; This program is distributed in the hope that it will be useful,
  10. ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  11. ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  12. ;; GNU General Public License for more details.
  13. ;; You should have received a copy of the GNU General Public License
  14. ;; along with this program. If not, see <http://www.gnu.org/licenses/>.
  15. ;;; Commentary:
  16. ;; This library implements a generic export engine for Org, built on
  17. ;; its syntactical parser: Org Elements.
  18. ;; Besides that parser, the generic exporter is made of three distinct
  19. ;; parts:
  20. ;; - The communication channel consists in a property list, which is
  21. ;; created and updated during the process. Its use is to offer
  22. ;; every piece of information, would it be export options or
  23. ;; contextual data, all in a single place. The exhaustive list of
  24. ;; properties is given in "The Communication Channel" section of
  25. ;; this file.
  26. ;; - The transcoder walks the parse tree, ignores or treat as plain
  27. ;; text elements and objects according to export options, and
  28. ;; eventually calls back-end specific functions to do the real
  29. ;; transcoding, concatenating their return value along the way.
  30. ;; - The filter system is activated at the very beginning and the very
  31. ;; end of the export process, and each time an element or an object
  32. ;; has been converted. It is the entry point to fine-tune standard
  33. ;; output from back-end transcoders.
  34. ;; The core function is `org-export-as'. It returns the transcoded
  35. ;; buffer as a string.
  36. ;; In order to derive an exporter out of this generic implementation,
  37. ;; one can define a transcode function for each element or object.
  38. ;; Such function should return a string for the corresponding element,
  39. ;; without any trailing space, or nil. It must accept three
  40. ;; arguments:
  41. ;; 1. the element or object itself,
  42. ;; 2. its contents, or nil when it isn't recursive,
  43. ;; 3. the property list used as a communication channel.
  44. ;; If no such function is found, that element or object type will
  45. ;; simply be ignored, along with any separating blank line. The same
  46. ;; will happen if the function returns the nil value. If that
  47. ;; function returns the empty string, the type will be ignored, but
  48. ;; the blank lines will be kept.
  49. ;; Contents, when not nil, are stripped from any global indentation
  50. ;; (although the relative one is preserved). They also always end
  51. ;; with a single newline character.
  52. ;; These functions must follow a strict naming convention:
  53. ;; `org-BACKEND-TYPE' where, obviously, BACKEND is the name of the
  54. ;; export back-end and TYPE the type of the element or object handled.
  55. ;; Moreover, two additional functions can be defined. On the one
  56. ;; hand, `org-BACKEND-template' returns the final transcoded string,
  57. ;; and can be used to add a preamble and a postamble to document's
  58. ;; body. It must accept two arguments: the transcoded string and the
  59. ;; property list containing export options. On the other hand,
  60. ;; `org-BACKEND-plain-text', when defined, is to be called on every
  61. ;; text not recognized as an element or an object. It must accept two
  62. ;; arguments: the text string and the information channel.
  63. ;; Any back-end can define its own variables. Among them, those
  64. ;; customizables should belong to the `org-export-BACKEND' group.
  65. ;; Also, a special variable, `org-BACKEND-option-alist', allows to
  66. ;; define buffer keywords and "#+options:" items specific to that
  67. ;; back-end. See `org-export-option-alist' for supported defaults and
  68. ;; syntax.
  69. ;; Tools for common tasks across back-ends are implemented in the last
  70. ;; part of this file.
  71. ;;; Code:
  72. (eval-when-compile (require 'cl))
  73. (require 'org-element)
  74. ;;; Internal Variables
  75. ;; Among internal variables, the most important is
  76. ;; `org-export-option-alist'. This variable define the global export
  77. ;; options, shared between every exporter, and how they are acquired.
  78. (defconst org-export-max-depth 19
  79. "Maximum nesting depth for headlines, counting from 0.")
  80. (defconst org-export-option-alist
  81. '((:author "AUTHOR" nil user-full-name t)
  82. (:creator "CREATOR" nil org-export-creator-string)
  83. (:date "DATE" nil nil t)
  84. (:description "DESCRIPTION" nil nil newline)
  85. (:email "EMAIL" nil user-mail-address t)
  86. (:exclude-tags "EXPORT_EXCLUDE_TAGS" nil org-export-exclude-tags split)
  87. (:headline-levels nil "H" org-export-headline-levels)
  88. (:keywords "KEYWORDS" nil nil space)
  89. (:language "LANGUAGE" nil org-export-default-language t)
  90. (:preserve-breaks nil "\\n" org-export-preserve-breaks)
  91. (:section-numbers nil "num" org-export-with-section-numbers)
  92. (:select-tags "EXPORT_SELECT_TAGS" nil org-export-select-tags split)
  93. (:time-stamp-file nil "timestamp" org-export-time-stamp-file)
  94. (:title "TITLE" nil nil space)
  95. (:with-archived-trees nil "arch" org-export-with-archived-trees)
  96. (:with-author nil "author" org-export-with-author)
  97. (:with-creator nil "creator" org-export-with-creator)
  98. (:with-drawers nil "drawer" org-export-with-drawers)
  99. (:with-email nil "email" org-export-with-email)
  100. (:with-emphasize nil "*" org-export-with-emphasize)
  101. (:with-entities nil "e" org-export-with-entities)
  102. (:with-fixed-width nil ":" org-export-with-fixed-width)
  103. (:with-footnotes nil "f" org-export-with-footnotes)
  104. (:with-priority nil "pri" org-export-with-priority)
  105. (:with-special-strings nil "-" org-export-with-special-strings)
  106. (:with-sub-superscript nil "^" org-export-with-sub-superscripts)
  107. (:with-toc nil "toc" org-export-with-toc)
  108. (:with-tables nil "|" org-export-with-tables)
  109. (:with-tags nil "tags" org-export-with-tags)
  110. (:with-tasks nil "tasks" org-export-with-tasks)
  111. (:with-timestamps nil "<" org-export-with-timestamps)
  112. (:with-todo-keywords nil "todo" org-export-with-todo-keywords))
  113. "Alist between export properties and ways to set them.
  114. The car of the alist is the property name, and the cdr is a list
  115. like \(KEYWORD OPTION DEFAULT BEHAVIOUR\) where:
  116. KEYWORD is a string representing a buffer keyword, or nil.
  117. OPTION is a string that could be found in an #+OPTIONS: line.
  118. DEFAULT is the default value for the property.
  119. BEHAVIOUR determine how Org should handle multiple keywords for
  120. the same property. It is a symbol among:
  121. nil Keep old value and discard the new one.
  122. t Replace old value with the new one.
  123. `space' Concatenate the values, separating them with a space.
  124. `newline' Concatenate the values, separating them with
  125. a newline.
  126. `split' Split values at white spaces, and cons them to the
  127. previous list.
  128. KEYWORD and OPTION have precedence over DEFAULT.
  129. All these properties should be back-end agnostic. For back-end
  130. specific properties, define a similar variable named
  131. `org-BACKEND-option-alist', replacing BACKEND with the name of
  132. the appropriate back-end. You can also redefine properties
  133. there, as they have precedence over these.")
  134. (defconst org-export-special-keywords
  135. '("SETUP_FILE" "OPTIONS" "MACRO")
  136. "List of in-buffer keywords that require special treatment.
  137. These keywords are not directly associated to a property. The
  138. way they are handled must be hard-coded into
  139. `org-export-get-inbuffer-options' function.")
  140. ;;; User-configurable Variables
  141. ;; Configuration for the masses.
  142. ;; They should never be evaled directly, as their value is to be
  143. ;; stored in a property list (cf. `org-export-option-alist').
  144. (defgroup org-export nil
  145. "Options for exporting Org mode files."
  146. :tag "Org Export"
  147. :group 'org)
  148. (defgroup org-export-general nil
  149. "General options for export engine."
  150. :tag "Org Export General"
  151. :group 'org-export)
  152. (defcustom org-export-with-archived-trees 'headline
  153. "Whether sub-trees with the ARCHIVE tag should be exported.
  154. This can have three different values:
  155. nil Do not export, pretend this tree is not present.
  156. t Do export the entire tree.
  157. `headline' Only export the headline, but skip the tree below it.
  158. This option can also be set with the #+OPTIONS line,
  159. e.g. \"arch:nil\"."
  160. :group 'org-export-general
  161. :type '(choice
  162. (const :tag "Not at all" nil)
  163. (const :tag "Headline only" 'headline)
  164. (const :tag "Entirely" t)))
  165. (defcustom org-export-with-author t
  166. "Non-nil means insert author name into the exported file.
  167. This option can also be set with the #+OPTIONS line,
  168. e.g. \"author:nil\"."
  169. :group 'org-export-general
  170. :type 'boolean)
  171. (defcustom org-export-with-creator 'comment
  172. "Non-nil means the postamble should contain a creator sentence.
  173. The sentence can be set in `org-export-creator-string' and
  174. defaults to \"Generated by Org mode XX in Emacs XXX.\".
  175. If the value is `comment' insert it as a comment."
  176. :group 'org-export-general
  177. :type '(choice
  178. (const :tag "No creator sentence" nil)
  179. (const :tag "Sentence as a comment" 'comment)
  180. (const :tag "Insert the sentence" t)))
  181. (defcustom org-export-creator-string
  182. (format "Generated by Org mode %s in Emacs %s." org-version emacs-version)
  183. "String to insert at the end of the generated document."
  184. :group 'org-export-general
  185. :type '(string :tag "Creator string"))
  186. (defcustom org-export-with-drawers nil
  187. "Non-nil means export with drawers like the property drawer.
  188. When t, all drawers are exported. This may also be a list of
  189. drawer names to export."
  190. :group 'org-export-general
  191. :type '(choice
  192. (const :tag "All drawers" t)
  193. (const :tag "None" nil)
  194. (repeat :tag "Selected drawers"
  195. (string :tag "Drawer name"))))
  196. (defcustom org-export-with-email nil
  197. "Non-nil means insert author email into the exported file.
  198. This option can also be set with the #+OPTIONS line,
  199. e.g. \"email:t\"."
  200. :group 'org-export-general
  201. :type 'boolean)
  202. (defcustom org-export-with-emphasize t
  203. "Non-nil means interpret *word*, /word/, and _word_ as emphasized text.
  204. If the export target supports emphasizing text, the word will be
  205. typeset in bold, italic, or underlined, respectively. Not all
  206. export backends support this.
  207. This option can also be set with the #+OPTIONS line, e.g. \"*:nil\"."
  208. :group 'org-export-general
  209. :type 'boolean)
  210. (defcustom org-export-exclude-tags '("noexport")
  211. "Tags that exclude a tree from export.
  212. All trees carrying any of these tags will be excluded from
  213. export. This is without condition, so even subtrees inside that
  214. carry one of the `org-export-select-tags' will be removed."
  215. :group 'org-export-general
  216. :type '(repeat (string :tag "Tag")))
  217. (defcustom org-export-with-fixed-width t
  218. "Non-nil means lines starting with \":\" will be in fixed width font.
  219. This can be used to have pre-formatted text, fragments of code
  220. etc. For example:
  221. : ;; Some Lisp examples
  222. : (while (defc cnt)
  223. : (ding))
  224. will be looking just like this in also HTML. See also the QUOTE
  225. keyword. Not all export backends support this.
  226. This option can also be set with the #+OPTIONS line, e.g. \"::nil\"."
  227. :group 'org-export-translation
  228. :type 'boolean)
  229. (defcustom org-export-with-footnotes t
  230. "Non-nil means Org footnotes should be exported.
  231. This option can also be set with the #+OPTIONS line,
  232. e.g. \"f:nil\"."
  233. :group 'org-export-general
  234. :type 'boolean)
  235. (defcustom org-export-headline-levels 3
  236. "The last level which is still exported as a headline.
  237. Inferior levels will produce itemize lists when exported. Note
  238. that a numeric prefix argument to an exporter function overrides
  239. this setting.
  240. This option can also be set with the #+OPTIONS line, e.g. \"H:2\"."
  241. :group 'org-export-general
  242. :type 'integer)
  243. (defcustom org-export-default-language "en"
  244. "The default language for export and clocktable translations, as a string.
  245. This may have an association in
  246. `org-clock-clocktable-language-setup'."
  247. :group 'org-export-general
  248. :type '(string :tag "Language"))
  249. (defcustom org-export-preserve-breaks nil
  250. "Non-nil means preserve all line breaks when exporting.
  251. Normally, in HTML output paragraphs will be reformatted.
  252. This option can also be set with the #+OPTIONS line,
  253. e.g. \"\\n:t\"."
  254. :group 'org-export-general
  255. :type 'boolean)
  256. (defcustom org-export-with-entities t
  257. "Non-nil means interpret entities when exporting.
  258. For example, HTML export converts \\alpha to &alpha; and \\AA to
  259. &Aring;.
  260. For a list of supported names, see the constant `org-entities'
  261. and the user option `org-entities-user'.
  262. This option can also be set with the #+OPTIONS line,
  263. e.g. \"e:nil\"."
  264. :group 'org-export-general
  265. :type 'boolean)
  266. (defcustom org-export-with-priority nil
  267. "Non-nil means include priority cookies in export.
  268. When nil, remove priority cookies for export."
  269. :group 'org-export-general
  270. :type 'boolean)
  271. (defcustom org-export-with-section-numbers t
  272. "Non-nil means add section numbers to headlines when exporting.
  273. This option can also be set with the #+OPTIONS line,
  274. e.g. \"num:t\"."
  275. :group 'org-export-general
  276. :type 'boolean)
  277. (defcustom org-export-select-tags '("export")
  278. "Tags that select a tree for export.
  279. If any such tag is found in a buffer, all trees that do not carry
  280. one of these tags will be deleted before export. Inside trees
  281. that are selected like this, you can still deselect a subtree by
  282. tagging it with one of the `org-export-exclude-tags'."
  283. :group 'org-export-general
  284. :type '(repeat (string :tag "Tag")))
  285. (defcustom org-export-with-special-strings t
  286. "Non-nil means interpret \"\-\", \"--\" and \"---\" for export.
  287. When this option is turned on, these strings will be exported as:
  288. Org HTML LaTeX
  289. -----+----------+--------
  290. \\- &shy; \\-
  291. -- &ndash; --
  292. --- &mdash; ---
  293. ... &hellip; \ldots
  294. This option can also be set with the #+OPTIONS line,
  295. e.g. \"-:nil\"."
  296. :group 'org-export-general
  297. :type 'boolean)
  298. (defcustom org-export-with-sub-superscripts t
  299. "Non-nil means interpret \"_\" and \"^\" for export.
  300. When this option is turned on, you can use TeX-like syntax for
  301. sub- and superscripts. Several characters after \"_\" or \"^\"
  302. will be considered as a single item - so grouping with {} is
  303. normally not needed. For example, the following things will be
  304. parsed as single sub- or superscripts.
  305. 10^24 or 10^tau several digits will be considered 1 item.
  306. 10^-12 or 10^-tau a leading sign with digits or a word
  307. x^2-y^3 will be read as x^2 - y^3, because items are
  308. terminated by almost any nonword/nondigit char.
  309. x_{i^2} or x^(2-i) braces or parenthesis do grouping.
  310. Still, ambiguity is possible - so when in doubt use {} to enclose
  311. the sub/superscript. If you set this variable to the symbol
  312. `{}', the braces are *required* in order to trigger
  313. interpretations as sub/superscript. This can be helpful in
  314. documents that need \"_\" frequently in plain text.
  315. This option can also be set with the #+OPTIONS line,
  316. e.g. \"^:nil\"."
  317. :group 'org-export-general
  318. :type '(choice
  319. (const :tag "Interpret them" t)
  320. (const :tag "Curly brackets only" {})
  321. (const :tag "Do not interpret them" nil)))
  322. (defcustom org-export-with-toc t
  323. "Non-nil means create a table of contents in exported files.
  324. The TOC contains headlines with levels up
  325. to`org-export-headline-levels'. When an integer, include levels
  326. up to N in the toc, this may then be different from
  327. `org-export-headline-levels', but it will not be allowed to be
  328. larger than the number of headline levels. When nil, no table of
  329. contents is made.
  330. This option can also be set with the #+OPTIONS line,
  331. e.g. \"toc:nil\" or \"toc:3\"."
  332. :group 'org-export-general
  333. :type '(choice
  334. (const :tag "No Table of Contents" nil)
  335. (const :tag "Full Table of Contents" t)
  336. (integer :tag "TOC to level")))
  337. (defcustom org-export-with-tables t
  338. "If non-nil, lines starting with \"|\" define a table.
  339. For example:
  340. | Name | Address | Birthday |
  341. |-------------+----------+-----------|
  342. | Arthur Dent | England | 29.2.2100 |
  343. This option can also be set with the #+OPTIONS line, e.g. \"|:nil\"."
  344. :group 'org-export-general
  345. :type 'boolean)
  346. (defcustom org-export-with-tags t
  347. "If nil, do not export tags, just remove them from headlines.
  348. If this is the symbol `not-in-toc', tags will be removed from
  349. table of contents entries, but still be shown in the headlines of
  350. the document.
  351. This option can also be set with the #+OPTIONS line,
  352. e.g. \"tags:nil\"."
  353. :group 'org-export-general
  354. :type '(choice
  355. (const :tag "Off" nil)
  356. (const :tag "Not in TOC" not-in-toc)
  357. (const :tag "On" t)))
  358. (defcustom org-export-with-tasks t
  359. "Non-nil means include TODO items for export.
  360. This may have the following values:
  361. t include tasks independent of state.
  362. todo include only tasks that are not yet done.
  363. done include only tasks that are already done.
  364. nil remove all tasks before export
  365. list of keywords keep only tasks with these keywords"
  366. :group 'org-export-general
  367. :type '(choice
  368. (const :tag "All tasks" t)
  369. (const :tag "No tasks" nil)
  370. (const :tag "Not-done tasks" todo)
  371. (const :tag "Only done tasks" done)
  372. (repeat :tag "Specific TODO keywords"
  373. (string :tag "Keyword"))))
  374. (defcustom org-export-time-stamp-file t
  375. "Non-nil means insert a time stamp into the exported file.
  376. The time stamp shows when the file was created.
  377. This option can also be set with the #+OPTIONS line,
  378. e.g. \"timestamp:nil\"."
  379. :group 'org-export-general
  380. :type 'boolean)
  381. (defcustom org-export-with-timestamps t
  382. "If nil, do not export time stamps and associated keywords."
  383. :group 'org-export-general
  384. :type 'boolean)
  385. (defcustom org-export-with-todo-keywords t
  386. "Non-nil means include TODO keywords in export.
  387. When nil, remove all these keywords from the export.")
  388. (defcustom org-export-allow-BIND 'confirm
  389. "Non-nil means allow #+BIND to define local variable values for export.
  390. This is a potential security risk, which is why the user must
  391. confirm the use of these lines."
  392. :group 'org-export-general
  393. :type '(choice
  394. (const :tag "Never" nil)
  395. (const :tag "Always" t)
  396. (const :tag "Ask a confirmation for each file" confirm)))
  397. (defcustom org-export-snippet-translation-alist nil
  398. "Alist between export snippets back-ends and exporter back-ends.
  399. This variable allows to provide shortcuts for export snippets.
  400. For example, with a value of '\(\(\"h\" . \"html\"\)\), the HTML
  401. back-end will recognize the contents of \"@h{<b>}\" as HTML code
  402. while every other back-end will ignore it."
  403. :group 'org-export-general
  404. :type '(repeat
  405. (cons
  406. (string :tag "Shortcut")
  407. (string :tag "Back-end"))))
  408. ;;; The Communication Channel
  409. ;; During export process, every function has access to a number of
  410. ;; properties. They are of three types:
  411. ;; 1. Export options are collected once at the very beginning of the
  412. ;; process, out of the original buffer and environment. The task
  413. ;; is handled by `org-export-collect-options' function.
  414. ;;
  415. ;; All export options are defined through the
  416. ;; `org-export-option-alist' variable.
  417. ;;
  418. ;; 2. Persistent properties are stored in
  419. ;; `org-export-persistent-properties' and available at every level
  420. ;; of recursion. Their value is extracted directly from the parsed
  421. ;; tree, and depends on export options (whole trees may be filtered
  422. ;; out of the export process).
  423. ;;
  424. ;; Properties belonging to that type are defined in the
  425. ;; `org-export-persistent-properties-list' variable.
  426. ;;
  427. ;; 3. Every other property is considered local, and available at
  428. ;; a precise level of recursion and below.
  429. ;; Managing properties during transcode process is mainly done with
  430. ;; `org-export-update-info'. Even though they come from different
  431. ;; sources, the function transparently concatenates them in a single
  432. ;; property list passed as an argument to each transcode function.
  433. ;; Thus, during export, all necessary information is available through
  434. ;; that single property list, and the element or object itself.
  435. ;; Though, modifying a property will still require some special care,
  436. ;; and should be done with `org-export-set-property' instead of plain
  437. ;; `plist-put'.
  438. ;; Here is the full list of properties available during transcode
  439. ;; process, with their category (option, persistent or local), their
  440. ;; value type and the function updating them, when appropriate.
  441. ;; + `author' :: Author's name.
  442. ;; - category :: option
  443. ;; - type :: string
  444. ;; + `back-end' :: Current back-end used for transcoding.
  445. ;; - category :: persistent
  446. ;; - type :: symbol
  447. ;; + `code-refs' :: Association list between reference name and real
  448. ;; labels in source code. It is used to properly
  449. ;; resolve links inside source blocks.
  450. ;; - category :: persistent
  451. ;; - type :: alist (INT-OR-STRING . STRING)
  452. ;; - update :: `org-export-handle-code'
  453. ;; + `creator' :: String to write as creation information.
  454. ;; - category :: option
  455. ;; - type :: string
  456. ;; + `date' :: String to use as date.
  457. ;; - category :: option
  458. ;; - type :: string
  459. ;; + `description' :: Description text for the current data.
  460. ;; - category :: option
  461. ;; - type :: string
  462. ;; + `email' :: Author's email.
  463. ;; - category :: option
  464. ;; - type :: string
  465. ;; + `exclude-tags' :: Tags for exclusion of subtrees from export
  466. ;; process.
  467. ;; - category :: option
  468. ;; - type :: list of strings
  469. ;; + `footnotes-labels-alist' :: Alist between footnote labels and
  470. ;; their definition, as parsed data. Once retrieved, the
  471. ;; definition should be exported with `org-export-data'.
  472. ;; - category :: option
  473. ;; - type :: alist (STRING . LIST)
  474. ;; + `genealogy' :: List of current element's parents types.
  475. ;; - category :: local
  476. ;; - type :: list of symbols
  477. ;; - update :: `org-export-update-info'
  478. ;; + `headline-alist' :: Alist between headlines raw name and their
  479. ;; boundaries. It is used to resolve "fuzzy" links
  480. ;; (cf. `org-export-resolve-fuzzy-link').
  481. ;; - category :: persistent
  482. ;; - type :: alist (STRING INTEGER INTEGER)
  483. ;; + `headline-levels' :: Maximum level being exported as an
  484. ;; headline. Comparison is done with the relative level of
  485. ;; headlines in the parse tree, not necessarily with their
  486. ;; actual level.
  487. ;; - category :: option
  488. ;; - type :: integer
  489. ;; + `headline-offset' :: Difference between relative and real level
  490. ;; of headlines in the parse tree. For example, a value of -1
  491. ;; means a level 2 headline should be considered as level
  492. ;; 1 (cf. `org-export-get-relative-level').
  493. ;; - category :: persistent
  494. ;; - type :: integer
  495. ;; + `headline-numbering' :: Alist between headlines' beginning
  496. ;; position and their numbering, as a list of numbers
  497. ;; (cf. `org-export-get-headline-number').
  498. ;; - category :: persistent
  499. ;; - type :: alist (INTEGER . LIST)
  500. ;; + `included-files' :: List of files, with full path, included in
  501. ;; the current buffer, through the "#+include:" keyword. It is
  502. ;; mainly used to verify that no infinite recursive inclusion
  503. ;; happens.
  504. ;; - category :: local
  505. ;; - type :: list of strings
  506. ;; + `inherited-properties' :: Properties of the headline ancestors
  507. ;; of the current element or object. Those from the closest
  508. ;; headline have precedence over the others.
  509. ;; - category :: local
  510. ;; - type :: plist
  511. ;; + `keywords' :: List of keywords attached to data.
  512. ;; - category :: option
  513. ;; - type :: string
  514. ;; + `language' :: Default language used for translations.
  515. ;; - category :: option
  516. ;; - type :: string
  517. ;; + `parent-properties' :: Properties of the parent element.
  518. ;; - category :: local
  519. ;; - type :: plist
  520. ;; - update :: `org-export-update-info'
  521. ;; + `parse-tree' :: Whole parse tree, available at any time during
  522. ;; transcoding.
  523. ;; - category :: global
  524. ;; - type :: list (as returned by `org-element-parse-buffer')
  525. ;; + `point-max' :: Last ending position in the parse tree.
  526. ;; - category :: global
  527. ;; - type :: integer
  528. ;; + `preserve-breaks' :: Non-nil means transcoding should preserve
  529. ;; all line breaks.
  530. ;; - category :: option
  531. ;; - type :: symbol (nil, t)
  532. ;; + `previous-element' :: Previous element's type at the same
  533. ;; level.
  534. ;; - category :: local
  535. ;; - type :: symbol
  536. ;; - update :: `org-export-update-info'
  537. ;; + `previous-object' :: Previous object type (or `plain-text') at
  538. ;; the same level.
  539. ;; - category :: local
  540. ;; - type :: symbol
  541. ;; - update :: `org-export-update-info'
  542. ;; + `section-numbers' :: Non-nil means transcoding should add
  543. ;; section numbers to headlines.
  544. ;; - category :: option
  545. ;; - type :: symbol (nil, t)
  546. ;; + `seen-footnote-labels' :: List of already transcoded footnote
  547. ;; labels.
  548. ;; - category :: persistent
  549. ;; - type :: list of strings
  550. ;; - update :: `org-export-update-info'
  551. ;; + `select-tags' :: List of tags enforcing inclusion of sub-trees in
  552. ;; transcoding. When such a tag is present,
  553. ;; subtrees without it are de facto excluded from
  554. ;; the process. See `use-select-tags'.
  555. ;; - category :: option
  556. ;; - type :: list of strings
  557. ;; + `target-list' :: List of targets raw names encoutered in the
  558. ;; parse tree. This is used to partly resolve
  559. ;; "fuzzy" links
  560. ;; (cf. `org-export-resolve-fuzzy-link').
  561. ;; - category :: persistent
  562. ;; - type :: list of strings
  563. ;; + `time-stamp-file' :: Non-nil means transcoding should insert
  564. ;; a time stamp in the output.
  565. ;; - category :: option
  566. ;; - type :: symbol (nil, t)
  567. ;; + `total-loc' :: Contains total lines of code accumulated by source
  568. ;; blocks with the "+n" option so far.
  569. ;; - category :: persistent
  570. ;; - type :: integer
  571. ;; - update :: `org-export-handle-code'
  572. ;; + `use-select-tags' :: When non-nil, a select tags has been found
  573. ;; in the parse tree. Thus, any headline without one will be
  574. ;; filtered out. See `select-tags'.
  575. ;; - category :: persistent
  576. ;; - type :: interger or nil
  577. ;; + `with-archived-trees' :: Non-nil when archived subtrees should
  578. ;; also be transcoded. If it is set to the `headline' symbol,
  579. ;; only the archived headline's name is retained.
  580. ;; - category :: option
  581. ;; - type :: symbol (nil, t, `headline')
  582. ;; + `with-author' :: Non-nil means author's name should be included
  583. ;; in the output.
  584. ;; - category :: option
  585. ;; - type :: symbol (nil, t)
  586. ;; + `with-creator' :: Non-nild means a creation sentence should be
  587. ;; inserted at the end of the transcoded string. If the value
  588. ;; is `comment', it should be commented.
  589. ;; - category :: option
  590. ;; - type :: symbol (`comment', nil, t)
  591. ;; + `with-drawers' :: Non-nil means drawers should be exported. If
  592. ;; its value is a list of names, only drawers with such names
  593. ;; will be transcoded.
  594. ;; - category :: option
  595. ;; - type :: symbol (nil, t) or list of strings
  596. ;; + `with-email' :: Non-nil means output should contain author's
  597. ;; email.
  598. ;; - category :: option
  599. ;; - type :: symbol (nil, t)
  600. ;; + `with-emphasize' :: Non-nil means emphasized text should be
  601. ;; interpreted.
  602. ;; - category :: option
  603. ;; - type :: symbol (nil, t)
  604. ;; + `with-fixed-width' :: Non-nil if transcoder should interpret
  605. ;; strings starting with a colon as a fixed-with (verbatim)
  606. ;; area.
  607. ;; - category :: option
  608. ;; - type :: symbol (nil, t)
  609. ;; + `with-footnotes' :: Non-nil if transcoder should interpret
  610. ;; footnotes.
  611. ;; - category :: option
  612. ;; - type :: symbol (nil, t)
  613. ;; + `with-priority' :: Non-nil means transcoding should include
  614. ;; priority cookies.
  615. ;; - category :: option
  616. ;; - type :: symbol (nil, t)
  617. ;; + `with-special-strings' :: Non-nil means transcoding should
  618. ;; interpret special strings in plain text.
  619. ;; - category :: option
  620. ;; - type :: symbol (nil, t)
  621. ;; + `with-sub-superscript' :: Non-nil means transcoding should
  622. ;; interpret subscript and superscript. With a value of "{}",
  623. ;; only interpret those using curly brackets.
  624. ;; - category :: option
  625. ;; - type :: symbol (nil, {}, t)
  626. ;; + `with-tables' :: Non-nil means transcoding should interpret
  627. ;; tables.
  628. ;; - category :: option
  629. ;; - type :: symbol (nil, t)
  630. ;; + `with-tags' :: Non-nil means transcoding should keep tags in
  631. ;; headlines. A `not-in-toc' value will remove them
  632. ;; from the table of contents, if any, nonetheless.
  633. ;; - category :: option
  634. ;; - type :: symbol (nil, t, `not-in-toc')
  635. ;; + `with-tasks' :: Non-nil means transcoding should include
  636. ;; headlines with a TODO keyword. A `todo' value
  637. ;; will only include headlines with a todo type
  638. ;; keyword while a `done' value will do the
  639. ;; contrary. If a list of strings is provided, only
  640. ;; tasks with keywords belonging to that list will
  641. ;; be kept.
  642. ;; - category :: option
  643. ;; - type :: symbol (t, todo, done, nil) or list of strings
  644. ;; + `with-timestamps' :: Non-nil means transcoding should include
  645. ;; time stamps and associated keywords. Otherwise, completely
  646. ;; remove them.
  647. ;; - category :: option
  648. ;; - type :: symbol: (t, nil)
  649. ;; + `with-toc' :: Non-nil means that a table of contents has to be
  650. ;; added to the output. An integer value limits its
  651. ;; depth.
  652. ;; - category :: option
  653. ;; - type :: symbol (nil, t or integer)
  654. ;; + `with-todo-keywords' :: Non-nil means transcoding should
  655. ;; include TODO keywords.
  656. ;; - category :: option
  657. ;; - type :: symbol (nil, t)
  658. ;;;; Export Options
  659. ;; Export options come from five sources, in increasing precedence
  660. ;; order:
  661. ;; - Global variables,
  662. ;; - External options provided at export time,
  663. ;; - Options keyword symbols,
  664. ;; - Buffer keywords,
  665. ;; - Subtree properties.
  666. ;; The central internal function with regards to export options is
  667. ;; `org-export-collect-options'. It updates global variables with
  668. ;; "#+BIND:" keywords, then retrieve and prioritize properties from
  669. ;; the different sources.
  670. ;; The internal functions doing the retrieval are:
  671. ;; `org-export-parse-option-keyword' ,
  672. ;; `org-export-get-subtree-options' ,
  673. ;; `org-export-get-inbuffer-options' and
  674. ;; `org-export-get-global-options'.
  675. ;;
  676. ;; Some properties do not rely on the previous sources but still
  677. ;; depend on the original buffer are taken care of in
  678. ;; `org-export-initial-options'.
  679. ;; Also, `org-export-confirm-letbind' and `org-export-install-letbind'
  680. ;; take care of the part relative to "#+BIND:" keywords.
  681. (defun org-export-collect-options (backend subtreep ext-plist)
  682. "Collect export options from the current buffer.
  683. BACKEND is a symbol specifying the back-end to use.
  684. When SUBTREEP is non-nil, assume the export is done against the
  685. current sub-tree.
  686. EXT-PLIST is a property list with external parameters overriding
  687. org-mode's default settings, but still inferior to file-local
  688. settings."
  689. ;; First install #+BIND variables.
  690. (org-export-install-letbind-maybe)
  691. ;; Get and prioritize export options...
  692. (let ((options (org-combine-plists
  693. ;; ... from global variables...
  694. (org-export-get-global-options backend)
  695. ;; ... from an external property list...
  696. ext-plist
  697. ;; ... from in-buffer settings...
  698. (org-export-get-inbuffer-options
  699. (org-with-wide-buffer (buffer-string)) backend
  700. (and buffer-file-name
  701. (org-remove-double-quotes buffer-file-name)))
  702. ;; ... and from subtree, when appropriate.
  703. (and subtreep
  704. (org-export-get-subtree-options)))))
  705. ;; Add initial options.
  706. (setq options (append (org-export-initial-options options)
  707. options))
  708. ;; Set a default title if none has been specified so far.
  709. (unless (plist-get options :title)
  710. (setq options (plist-put options :title
  711. (or (and buffer-file-name
  712. (file-name-sans-extension
  713. (file-name-nondirectory
  714. buffer-file-name)))
  715. (buffer-name)))))
  716. ;; Return plist.
  717. options))
  718. (defun org-export-parse-option-keyword (options backend)
  719. "Parse an OPTIONS line and return values as a plist.
  720. BACKEND is a symbol specifying the back-end to use."
  721. (let* ((all (append org-export-option-alist
  722. (let ((var (intern
  723. (format "org-%s-option-alist" backend))))
  724. (and (boundp var) (eval var)))))
  725. ;; Build an alist between #+OPTION: item and property-name.
  726. (alist (delq nil
  727. (mapcar (lambda (e)
  728. (when (nth 2 e) (cons (regexp-quote (nth 2 e))
  729. (car e))))
  730. all)))
  731. plist)
  732. (mapc (lambda (e)
  733. (when (string-match (concat "\\(\\`\\|[ \t]\\)"
  734. (car e)
  735. ":\\(([^)\n]+)\\|[^ \t\n\r;,.]*\\)")
  736. options)
  737. (setq plist (plist-put plist
  738. (cdr e)
  739. (car (read-from-string
  740. (match-string 2 options)))))))
  741. alist)
  742. plist))
  743. (defun org-export-get-subtree-options ()
  744. "Get export options in subtree at point.
  745. Return the options as a plist."
  746. (org-with-wide-buffer
  747. (when (ignore-errors (org-back-to-heading t))
  748. (let (prop plist)
  749. (when (setq prop (progn (looking-at org-todo-line-regexp)
  750. (or (org-entry-get (point) "EXPORT_TITLE")
  751. (org-match-string-no-properties 3))))
  752. (setq plist (plist-put plist :title prop)))
  753. (when (setq prop (org-entry-get (point) "EXPORT_TEXT"))
  754. (setq plist (plist-put plist :text prop)))
  755. (when (setq prop (org-entry-get (point) "EXPORT_AUTHOR"))
  756. (setq plist (plist-put plist :author prop)))
  757. (when (setq prop (org-entry-get (point) "EXPORT_DATE"))
  758. (setq plist (plist-put plist :date prop)))
  759. (when (setq prop (org-entry-get (point) "EXPORT_OPTIONS"))
  760. (setq plist (org-export-add-options-to-plist plist prop)))
  761. plist))))
  762. (defun org-export-get-inbuffer-options (buffer-string backend files)
  763. "Return in-buffer options as a plist.
  764. BUFFER-STRING is the string of the buffer. BACKEND is a symbol
  765. specifying which back-end should be used."
  766. (let ((case-fold-search t) plist)
  767. ;; 1. Special keywords, as in `org-export-special-keywords'.
  768. (let ((start 0)
  769. (special-re (org-make-options-regexp org-export-special-keywords)))
  770. (while (string-match special-re buffer-string start)
  771. (setq start (match-end 0))
  772. (let ((key (upcase (org-match-string-no-properties 1 buffer-string)))
  773. ;; Special keywords do not have their value expanded.
  774. (val (org-match-string-no-properties 2 buffer-string)))
  775. (setq plist
  776. (org-combine-plists
  777. (cond
  778. ((string= key "SETUP_FILE")
  779. (let ((file (expand-file-name
  780. (org-remove-double-quotes (org-trim val)))))
  781. ;; Avoid circular dependencies.
  782. (unless (member file files)
  783. (org-export-get-inbuffer-options
  784. (org-file-contents file 'noerror)
  785. backend
  786. (cons file files)))))
  787. ((string= key "OPTIONS")
  788. (org-export-parse-option-keyword val backend))
  789. ((string= key "MACRO")
  790. (string-match "^\\([-a-zA-Z0-9_]+\\)[ \t]+\\(.*?[ \t]*$\\)"
  791. val)
  792. (plist-put nil
  793. (intern (concat ":macro-"
  794. (downcase (match-string 1 val))))
  795. (match-string 2 val))))
  796. plist)))))
  797. ;; 2. Standard options, as in `org-export-option-alist'.
  798. (let* ((all (append org-export-option-alist
  799. (let ((var (intern
  800. (format "org-%s-option-alist" backend))))
  801. (and (boundp var) (eval var)))))
  802. ;; Build alist between keyword name and property name.
  803. (alist (delq nil (mapcar (lambda (e)
  804. (when (nth 1 e) (cons (nth 1 e) (car e))))
  805. all)))
  806. ;; Build regexp matching all keywords associated to export
  807. ;; options. Note: the search is case insensitive.
  808. (opt-re (org-make-options-regexp
  809. (delq nil (mapcar (lambda (e) (nth 1 e)) all))))
  810. (start 0))
  811. (while (string-match opt-re buffer-string start)
  812. (setq start (match-end 0))
  813. (let* ((key (upcase (org-match-string-no-properties 1 buffer-string)))
  814. ;; Expand value, applying restrictions for keywords.
  815. (val (org-match-string-no-properties 2 buffer-string))
  816. (prop (cdr (assoc key alist)))
  817. (behaviour (nth 4 (assq prop all))))
  818. (setq plist
  819. (plist-put
  820. plist prop
  821. ;; Handle value depending on specified BEHAVIOUR.
  822. (case behaviour
  823. (space (if (plist-get plist prop)
  824. (concat (plist-get plist prop) " " (org-trim val))
  825. (org-trim val)))
  826. (newline (org-trim
  827. (concat
  828. (plist-get plist prop) "\n" (org-trim val))))
  829. (split `(,@(plist-get plist prop) ,@(org-split-string val)))
  830. ('t val)
  831. (otherwise (plist-get plist prop)))))))
  832. ;; Parse keywords specified in `org-element-parsed-keywords'.
  833. (mapc
  834. (lambda (key)
  835. (let* ((prop (cdr (assoc (upcase key) alist)))
  836. (value (and prop (plist-get plist prop))))
  837. (when (stringp value)
  838. (setq plist
  839. (plist-put
  840. plist prop
  841. (org-element-parse-secondary-string
  842. value
  843. (cdr (assq 'keyword org-element-string-restrictions))))))))
  844. org-element-parsed-keywords))
  845. ;; Return final value.
  846. plist))
  847. (defun org-export-get-global-options (backend)
  848. "Return global export options as a plist.
  849. BACKEND is a symbol specifying which back-end should be used."
  850. (let ((all (append org-export-option-alist
  851. (let ((var (intern
  852. (format "org-%s-option-alist" backend))))
  853. (and (boundp var) (eval var)))))
  854. ;; Output value.
  855. plist)
  856. (mapc (lambda (cell)
  857. (setq plist
  858. (plist-put plist (car cell) (eval (nth 3 cell)))))
  859. all)
  860. ;; Return value.
  861. plist))
  862. (defun org-export-initial-options (options)
  863. "Return a plist with non-optional properties.
  864. OPTIONS is the export options plist computed so far."
  865. (list
  866. :macro-date "(eval (format-time-string \"$1\"))"
  867. :macro-time "(eval (format-time-string \"$1\"))"
  868. :macro-property "(eval (org-entry-get nil \"$1\" 'selective))"
  869. :macro-modification-time
  870. (and (buffer-file-name)
  871. (file-exists-p (buffer-file-name))
  872. (concat "(eval (format-time-string \"$1\" '"
  873. (prin1-to-string (nth 5 (file-attributes (buffer-file-name))))
  874. "))"))
  875. :macro-input-file (and (buffer-file-name)
  876. (file-name-nondirectory (buffer-file-name)))
  877. :footnotes-labels-alist
  878. (let (alist)
  879. (org-with-wide-buffer
  880. (goto-char (point-min))
  881. (while (re-search-forward org-footnote-definition-re nil t)
  882. (let ((def (org-footnote-at-definition-p)))
  883. (org-skip-whitespace)
  884. (push (cons (car def)
  885. (save-restriction
  886. (narrow-to-region (point) (nth 2 def))
  887. (org-element-parse-buffer)))
  888. alist)))
  889. alist))))
  890. (defvar org-export-allow-BIND-local nil)
  891. (defun org-export-confirm-letbind ()
  892. "Can we use #+BIND values during export?
  893. By default this will ask for confirmation by the user, to divert
  894. possible security risks."
  895. (cond
  896. ((not org-export-allow-BIND) nil)
  897. ((eq org-export-allow-BIND t) t)
  898. ((local-variable-p 'org-export-allow-BIND-local) org-export-allow-BIND-local)
  899. (t (org-set-local 'org-export-allow-BIND-local
  900. (yes-or-no-p "Allow BIND values in this buffer? ")))))
  901. (defun org-export-install-letbind-maybe ()
  902. "Install the values from #+BIND lines as local variables.
  903. Variables must be installed before in-buffer options are
  904. retrieved."
  905. (let (letbind pair)
  906. (org-with-wide-buffer
  907. (goto-char (point-min))
  908. (while (re-search-forward (org-make-options-regexp '("BIND")) nil t)
  909. (when (org-export-confirm-letbind)
  910. (push (read (concat "(" (org-match-string-no-properties 2) ")"))
  911. letbind))))
  912. (while (setq pair (pop letbind))
  913. (org-set-local (car pair) (nth 1 pair)))))
  914. ;;;; Persistent Properties
  915. ;; Persistent properties are declared in
  916. ;; `org-export-persistent-properties-list' variable. Most of them are
  917. ;; initialized at the beginning of the transcoding process by
  918. ;; `org-export-initialize-persistent-properties'. The others are
  919. ;; updated during that process.
  920. ;; Dedicated functions focus on computing the value of specific
  921. ;; persistent properties during initialization. Thus,
  922. ;; `org-export-use-select-tag-p' determines if an headline makes use
  923. ;; of an export tag enforcing inclusion. `org-export-get-min-level'
  924. ;; gets the minimal exportable level, used as a basis to compute
  925. ;; relative level for headlines. `org-export-get-point-max' returns
  926. ;; the maximum exportable ending position in the parse tree.
  927. ;; Eventually `org-export-collect-headline-numbering' builds an alist
  928. ;; between headlines' beginning position and their numbering.
  929. (defconst org-export-persistent-properties-list
  930. '(:back-end :code-refs :headline-alist :headline-numbering :headline-offset
  931. :parse-tree :point-max :seen-footnote-labels :target-list
  932. :total-loc :use-select-tags)
  933. "List of persistent properties.")
  934. (defconst org-export-persistent-properties nil
  935. "Used internally to store properties and values during transcoding.
  936. Only properties that should survive recursion are saved here.
  937. This variable is reset before each transcoding.")
  938. (defun org-export-initialize-persistent-properties (data options backend)
  939. "Initialize `org-export-persistent-properties'.
  940. DATA is the parse tree from which information is retrieved.
  941. OPTIONS is a list holding export options. BACKEND is the
  942. back-end called for transcoding, as a symbol.
  943. Following initial persistent properties are set:
  944. `:back-end' Back-end used for transcoding.
  945. `:headline-alist' Alist of all headlines' name as key and a list
  946. holding beginning and ending positions as
  947. value.
  948. `:headline-offset' Offset between true level of headlines and
  949. local level. An offset of -1 means an headline
  950. of level 2 should be considered as a level
  951. 1 headline in the context.
  952. `:headline-numbering' Alist of all headlines' beginning position
  953. as key an the associated numbering as value.
  954. `:parse-tree' Whole parse tree.
  955. `:point-max' Last position in the parse tree
  956. `:target-list' List of all targets' raw name in the parse tree.
  957. `:use-select-tags' Non-nil when parsed tree use a special tag to
  958. enforce transcoding of the headline."
  959. ;; First delete any residual persistent property.
  960. (setq org-export-persistent-properties nil)
  961. ;; Immediately after, set `:use-select-tags' property, as it will be
  962. ;; required for further computations.
  963. (setq options
  964. (org-export-set-property
  965. options
  966. :use-select-tags
  967. (org-export-use-select-tags-p data options)))
  968. ;; Get the rest of the initial persistent properties, now
  969. ;; `:use-select-tags' is set...
  970. ;; 1. `:parse-tree' ...
  971. (setq options (org-export-set-property options :parse-tree data))
  972. ;; 2. `:headline-offset' ...
  973. (setq options
  974. (org-export-set-property
  975. options :headline-offset
  976. (- 1 (org-export-get-min-level data options))))
  977. ;; 3. `:point-max' ...
  978. (setq options (org-export-set-property
  979. options :point-max
  980. (org-export-get-point-max data options)))
  981. ;; 4. `:target-list'...
  982. (setq options (org-export-set-property
  983. options :target-list
  984. (org-element-map
  985. data 'target
  986. (lambda (target info)
  987. (org-element-get-property :raw-value target)))))
  988. ;; 5. `:headline-alist'
  989. (setq options (org-export-set-property
  990. options :headline-alist
  991. (org-element-map
  992. data 'headline
  993. (lambda (headline info)
  994. (list (org-element-get-property :raw-value headline)
  995. (org-element-get-property :begin headline)
  996. (org-element-get-property :end headline))))))
  997. ;; 6. `:headline-numbering'
  998. (setq options (org-export-set-property
  999. options :headline-numbering
  1000. (org-export-collect-headline-numbering data options)))
  1001. ;; 7. `:back-end'
  1002. (setq options (org-export-set-property options :back-end backend)))
  1003. (defun org-export-use-select-tags-p (data options)
  1004. "Non-nil when data use a tag enforcing transcoding.
  1005. DATA is parsed data as returned by `org-element-parse-buffer'.
  1006. OPTIONS is a plist holding export options."
  1007. (org-element-map
  1008. data
  1009. 'headline
  1010. (lambda (headline info)
  1011. (let ((tags (org-element-get-property :with-tags headline)))
  1012. (and tags (string-match
  1013. (format ":%s:" (plist-get info :select-tags)) tags))))
  1014. options
  1015. 'stop-at-first-match))
  1016. (defun org-export-get-min-level (data options)
  1017. "Return minimum exportable headline's level in DATA.
  1018. DATA is parsed tree as returned by `org-element-parse-buffer'.
  1019. OPTIONS is a plist holding export options."
  1020. (catch 'exit
  1021. (let ((min-level 10000))
  1022. (mapc (lambda (blob)
  1023. (when (and (eq (car blob) 'headline)
  1024. (not (org-export-skip-p blob options)))
  1025. (setq min-level
  1026. (min (org-element-get-property :level blob) min-level)))
  1027. (when (= min-level 1) (throw 'exit 1)))
  1028. (org-element-get-contents data))
  1029. ;; If no headline was found, for the sake of consistency, set
  1030. ;; minimum level to 1 nonetheless.
  1031. (if (= min-level 10000) 1 min-level))))
  1032. (defun org-export-get-point-max (data options)
  1033. "Return last exportable ending position in DATA.
  1034. DATA is parsed tree as returned by `org-element-parse-buffer'.
  1035. OPTIONS is a plist holding export options."
  1036. (let ((pos-max 1))
  1037. (mapc (lambda (blob)
  1038. (unless (and (eq (car blob) 'headline)
  1039. (org-export-skip-p blob options))
  1040. (setq pos-max (org-element-get-property :end blob))))
  1041. (org-element-get-contents data))
  1042. pos-max))
  1043. (defun org-export-collect-headline-numbering (data options)
  1044. "Return numbering of all exportable headlines in a parse tree.
  1045. DATA is the parse tree. OPTIONS is the plist holding export
  1046. options.
  1047. Return an alist whose key is headline's beginning position and
  1048. value is its associated numbering (in the shape of a list of
  1049. numbers)."
  1050. (let ((numbering (make-vector org-export-max-depth 0)))
  1051. (org-element-map
  1052. data
  1053. 'headline
  1054. (lambda (headline info)
  1055. (let ((relative-level (1- (org-export-get-relative-level blob info))))
  1056. (cons
  1057. (org-element-get-property :begin headline)
  1058. (loop for n across numbering
  1059. for idx from 0 to org-export-max-depth
  1060. when (< idx relative-level) collect n
  1061. when (= idx relative-level) collect (aset numbering idx (1+ n))
  1062. when (> idx relative-level) do (aset numbering idx 0)))))
  1063. options)))
  1064. ;;;; Properties Management
  1065. ;; This is mostly done with the help of two functions. On the one
  1066. ;; hand `org-export-update-info' is used to keep up-to-date local
  1067. ;; information while walking the nested list representing the parsed
  1068. ;; document. On the other end, `org-export-set-property' handles
  1069. ;; properties modifications according to their type (persistent or
  1070. ;; local).
  1071. ;; As exceptions, `:code-refs' and `:total-loc' properties are updated
  1072. ;; with `org-export-handle-code' function.
  1073. (defun org-export-update-info (blob info recursep)
  1074. "Update export options depending on context.
  1075. BLOB is the element or object being parsed. INFO is the plist
  1076. holding the export options.
  1077. When RECURSEP is non-nil, assume the following element or object
  1078. will be inside the current one.
  1079. The following properties are updated:
  1080. `genealogy' List of current element's parents
  1081. (symbol list).
  1082. `inherited-properties' List of inherited properties from
  1083. parent headlines (plist).
  1084. `parent-properties' List of last element's properties
  1085. (plist).
  1086. `previous-element' Previous element's type (symbol).
  1087. `previous-object' Previous object's type (symbol).
  1088. `seen-footnote-labels' List of already parsed footnote
  1089. labels (string list)
  1090. Return the property list."
  1091. (let* ((type (and (not (stringp blob)) (car blob))))
  1092. (cond
  1093. ;; Case 1: We're moving into a recursive blob.
  1094. (recursep
  1095. (org-combine-plists
  1096. info
  1097. `(:genealogy ,(cons type (plist-get info :genealogy))
  1098. :previous-element nil
  1099. :previous-object nil
  1100. :parent-properties
  1101. ,(if (memq type org-element-all-elements)
  1102. (nth 1 blob)
  1103. (plist-get info :parent-properties))
  1104. :inherited-properties
  1105. ,(if (eq type 'headline)
  1106. (org-combine-plists
  1107. (plist-get info :inherited-properties) (nth 1 blob))
  1108. (plist-get info :inherited-properties)))
  1109. ;; Add persistent properties.
  1110. org-export-persistent-properties))
  1111. ;; Case 2: No recursion.
  1112. (t
  1113. ;; At a footnote reference: mark its label as seen, if not
  1114. ;; already the case.
  1115. (when (eq type 'footnote-reference)
  1116. (let ((label (org-element-get-property :label blob))
  1117. (seen-labels (plist-get org-export-persistent-properties
  1118. :seen-footnote-labels)))
  1119. ;; Store anonymous footnotes (nil label) without checking if
  1120. ;; another anonymous footnote was seen before.
  1121. (unless (and label (member label seen-labels))
  1122. (setq info (org-export-set-property
  1123. info :seen-footnote-labels (push label seen-labels))))))
  1124. ;; Set `:previous-element' or `:previous-object' according to
  1125. ;; BLOB.
  1126. (setq info (cond ((not type)
  1127. (org-export-set-property
  1128. info :previous-object 'plain-text))
  1129. ((memq type org-element-all-elements)
  1130. (org-export-set-property info :previous-element type))
  1131. (t (org-export-set-property info :previous-object type))))
  1132. ;; Return updated value.
  1133. info))))
  1134. (defun org-export-set-property (info prop value)
  1135. "Set property PROP to VALUE in plist INFO.
  1136. Return the new plist."
  1137. (when (memq prop org-export-persistent-properties-list)
  1138. (setq org-export-persistent-properties
  1139. (plist-put org-export-persistent-properties prop value)))
  1140. (plist-put info prop value))
  1141. ;;; The Transcoder
  1142. ;; This function reads Org data (obtained with, i.e.
  1143. ;; `org-element-parse-buffer') and transcodes it into a specified
  1144. ;; back-end output. It takes care of updating local properties,
  1145. ;; filtering out elements or objects according to export options and
  1146. ;; organizing the output blank lines and white space are preserved.
  1147. ;; Though, this function is inapropriate for secondary strings, which
  1148. ;; require a fresh copy of the plist passed as INFO argument. Thus,
  1149. ;; `org-export-secondary-string' is provided for that specific task.
  1150. ;; Internally, three functions handle the filtering of objects and
  1151. ;; elements during the export. More precisely, `org-export-skip-p'
  1152. ;; determines if the considered object or element should be ignored
  1153. ;; altogether, `org-export-interpret-p' tells which elements or
  1154. ;; objects should be seen as real Org syntax and `org-export-expand'
  1155. ;; transforms the others back into their original shape.
  1156. (defun org-export-data (data backend info)
  1157. "Convert DATA to a string into BACKEND format.
  1158. DATA is a nested list as returned by `org-element-parse-buffer'.
  1159. BACKEND is a symbol among supported exporters.
  1160. INFO is a plist holding export options and also used as
  1161. a communication channel between elements when walking the nested
  1162. list. See `org-export-update-info' function for more
  1163. details.
  1164. Return transcoded string."
  1165. (mapconcat
  1166. ;; BLOB can be an element, an object, a string, or nil.
  1167. (lambda (blob)
  1168. (cond
  1169. ((not blob) nil) ((equal blob "") nil)
  1170. ;; BLOB is a string. Check if the optional transcoder for plain
  1171. ;; text exists, and call it in that case. Otherwise, simply
  1172. ;; return string. Also update INFO and call
  1173. ;; `org-export-filter-plain-text-functions'.
  1174. ((stringp blob)
  1175. (setq info (org-export-update-info blob info nil))
  1176. (let ((transcoder (intern (format "org-%s-plain-text" backend))))
  1177. (org-export-filter-apply-functions
  1178. org-export-filter-plain-text-functions
  1179. (if (fboundp transcoder) (funcall transcoder blob info) blob)
  1180. backend)))
  1181. ;; BLOB is an element or an object.
  1182. (t
  1183. (let* ((type (if (stringp blob) 'plain-text (car blob)))
  1184. ;; 1. Determine the appropriate TRANSCODER.
  1185. (transcoder
  1186. (cond
  1187. ;; 1.0 A full Org document is inserted.
  1188. ((eq type 'org-data) 'identity)
  1189. ;; 1.1. BLOB should be ignored.
  1190. ((org-export-skip-p blob info) nil)
  1191. ;; 1.2. BLOB shouldn't be transcoded. Interpret it
  1192. ;; back into Org syntax.
  1193. ((not (org-export-interpret-p blob info))
  1194. 'org-export-expand)
  1195. ;; 1.3. Else apply naming convention.
  1196. (t (let ((trans (intern
  1197. (format "org-%s-%s" backend type))))
  1198. (and (fboundp trans) trans)))))
  1199. ;; 2. Compute CONTENTS of BLOB.
  1200. (contents
  1201. (cond
  1202. ;; Case 0. No transcoder defined: ignore BLOB.
  1203. ((not transcoder) nil)
  1204. ;; Case 1. Transparently export an Org document.
  1205. ((eq type 'org-data)
  1206. (org-export-data blob backend info))
  1207. ;; Case 2. For a recursive object.
  1208. ((memq type org-element-recursive-objects)
  1209. (org-export-data
  1210. blob backend (org-export-update-info blob info t)))
  1211. ;; Case 3. For a recursive element.
  1212. ((memq type org-element-greater-elements)
  1213. ;; Ignore contents of an archived tree
  1214. ;; when `:with-archived-trees' is `headline'.
  1215. (unless (and
  1216. (eq type 'headline)
  1217. (eq (plist-get info :with-archived-trees) 'headline)
  1218. (org-element-get-property :archivedp blob))
  1219. (org-element-normalize-string
  1220. (org-export-data
  1221. blob backend (org-export-update-info blob info t)))))
  1222. ;; Case 4. For a paragraph.
  1223. ((eq type 'paragraph)
  1224. (let ((paragraph
  1225. (org-element-normalize-contents
  1226. blob
  1227. ;; When normalizing contents of an item or
  1228. ;; a footnote definition, ignore first line's
  1229. ;; indentation: there is none and it might be
  1230. ;; misleading.
  1231. (and (not (plist-get info :previous-element))
  1232. (let ((parent (car (plist-get info :genealogy))))
  1233. (memq parent '(footnote-definition item)))))))
  1234. (org-export-data
  1235. paragraph
  1236. backend
  1237. (org-export-update-info blob info t))))))
  1238. ;; 3. Transcode BLOB into RESULTS string.
  1239. (results (cond
  1240. ((not transcoder) nil)
  1241. ((eq transcoder 'org-export-expand)
  1242. (org-export-data
  1243. `(org-data nil ,(funcall transcoder blob contents))
  1244. backend info))
  1245. (t (funcall transcoder blob contents info)))))
  1246. ;; 4. Discard nil results. Otherwise, update INFO, append
  1247. ;; the same white space between elements or objects as in
  1248. ;; the original buffer, and call appropriate filters.
  1249. (when results
  1250. (setq info (org-export-update-info blob info nil))
  1251. ;; No filter for a full document.
  1252. (if (eq type 'org-data)
  1253. results
  1254. (org-export-filter-apply-functions
  1255. (eval (intern (format "org-export-filter-%s-functions" type)))
  1256. (if (memq type org-element-all-elements)
  1257. (concat
  1258. (org-element-normalize-string results)
  1259. (make-string (org-element-get-property :post-blank blob) 10))
  1260. (concat
  1261. results
  1262. (make-string
  1263. (org-element-get-property :post-blank blob) 32)))
  1264. backend)))))))
  1265. (org-element-get-contents data) ""))
  1266. (defun org-export-secondary-string (secondary backend info)
  1267. "Convert SECONDARY string into BACKEND format.
  1268. SECONDARY is a nested list as returned by
  1269. `org-element-parse-secondary-string'.
  1270. BACKEND is a symbol among supported exporters.
  1271. INFO is a plist holding export options and also used as
  1272. a communication channel between elements when walking the nested
  1273. list. See `org-export-update-info' function for more
  1274. details.
  1275. Return transcoded string."
  1276. ;; Make SECONDARY acceptable for `org-export-data'.
  1277. (let ((s (if (listp secondary) secondary (list secondary))))
  1278. (org-export-data `(org-data nil ,@s) backend (copy-sequence info))))
  1279. (defun org-export-skip-p (blob info)
  1280. "Non-nil when element or object BLOB should be skipped during export.
  1281. INFO is the plist holding export options."
  1282. ;; Check headline.
  1283. (unless (stringp blob)
  1284. (case (car blob)
  1285. ('headline
  1286. (let ((with-tasks (plist-get info :with-tasks))
  1287. (todo (org-element-get-property :todo-keyword blob))
  1288. (todo-type (org-element-get-property :todo-type blob))
  1289. (archived (plist-get info :with-archived-trees))
  1290. (tag-list (let ((tags (org-element-get-property :tags blob)))
  1291. (and tags (org-split-string tags ":")))))
  1292. (or
  1293. ;; Ignore subtrees with an exclude tag.
  1294. (loop for k in (plist-get info :exclude-tags)
  1295. thereis (member k tag-list))
  1296. ;; Ignore subtrees without a select tag, when such tag is found
  1297. ;; in the buffer.
  1298. (and (plist-get info :use-select-tags)
  1299. (loop for k in (plist-get info :select-tags)
  1300. never (member k tag-list)))
  1301. ;; Ignore commented sub-trees.
  1302. (org-element-get-property :commentedp blob)
  1303. ;; Ignore archived subtrees if `:with-archived-trees' is nil.
  1304. (and (not archived) (org-element-get-property :archivedp blob))
  1305. ;; Ignore tasks, if specified by `:with-tasks' property.
  1306. (and todo (not with-tasks))
  1307. (and todo
  1308. (memq with-tasks '(todo done))
  1309. (not (eq todo-type with-tasks)))
  1310. (and todo
  1311. (consp with-tasks)
  1312. (not (member todo with-tasks))))))
  1313. ;; Check time-stamp.
  1314. ('time-stamp (not (plist-get info :with-timestamps)))
  1315. ;; Check drawer.
  1316. ('drawer
  1317. (or (not (plist-get info :with-drawers))
  1318. (and (consp (plist-get info :with-drawers))
  1319. (not (member (org-element-get-property :drawer-name blob)
  1320. (plist-get info :with-drawers))))))
  1321. ;; Check export snippet.
  1322. ('export-snippet
  1323. (let* ((raw-back-end (org-element-get-property :back-end blob))
  1324. (true-back-end
  1325. (or (cdr (assoc raw-back-end org-export-snippet-translation-alist))
  1326. raw-back-end)))
  1327. (not (string= (symbol-name (plist-get info :back-end))
  1328. true-back-end)))))))
  1329. (defun org-export-interpret-p (blob info)
  1330. "Non-nil if element or object BLOB should be interpreted as Org syntax.
  1331. Check is done according to export options INFO, stored as
  1332. a plist."
  1333. (case (car blob)
  1334. ;; ... entities...
  1335. (entity (plist-get info :with-entities))
  1336. ;; ... emphasis...
  1337. (emphasis (plist-get info :with-emphasize))
  1338. ;; ... fixed-width areas.
  1339. (fixed-width (plist-get info :with-fixed-width))
  1340. ;; ... footnotes...
  1341. ((footnote-definition footnote-reference)
  1342. (plist-get info :with-footnotes))
  1343. ;; ... sub/superscripts...
  1344. ((subscript superscript)
  1345. (let ((sub/super-p (plist-get info :with-sub-superscript)))
  1346. (if (eq sub/super-p '{})
  1347. (org-element-get-property :use-brackets-p blob)
  1348. sub/super-p)))
  1349. ;; ... tables...
  1350. (table (plist-get info :with-tables))
  1351. (otherwise t)))
  1352. (defsubst org-export-expand (blob contents)
  1353. "Expand a parsed element or object to its original state.
  1354. BLOB is either an element or an object. CONTENTS is its
  1355. contents, as a string or nil."
  1356. (funcall
  1357. (intern (format "org-element-%s-interpreter" (car blob))) blob contents))
  1358. ;;; The Filter System
  1359. ;; Filters allow end-users to tweak easily the transcoded output.
  1360. ;; They are the functional counterpart of hooks, as every filter in
  1361. ;; a set is applied to the return value of the previous one.
  1362. ;; Every set is back-end agnostic. Although, a filter is always
  1363. ;; called, in addition to the string it applies to, with the back-end
  1364. ;; used as argument, so it's easy enough for the end-user to add
  1365. ;; back-end specific filters in the set.
  1366. ;; Filters sets are defined below. There are of four types:
  1367. ;; - `org-export-filter-parse-tree-functions' applies directly on the
  1368. ;; complete parsed tree. It's the only filters set that doesn't
  1369. ;; apply to a string.
  1370. ;; - `org-export-filter-final-output-functions' applies to the final
  1371. ;; transcoded string.
  1372. ;; - `org-export-filter-plain-text-functions' applies to any string
  1373. ;; not recognized as Org syntax.
  1374. ;; - `org-export-filter-TYPE-functions' applies on the string returned
  1375. ;; after an element or object of type TYPE has been transcoded.
  1376. ;; All filters sets are applied through
  1377. ;; `org-export-filter-apply-functions' function. Filters in a set are
  1378. ;; applied in reverse order, that is in the order of consing. It
  1379. ;; allows developers to be reasonably sure that their filters will be
  1380. ;; applied first.
  1381. ;;;; Special Filters
  1382. (defvar org-export-filter-parse-tree-functions nil
  1383. "Filter, or list of filters, applied to the parsed tree.
  1384. Each filter is called with two arguments: the parse tree, as
  1385. returned by `org-element-parse-buffer', and the back-end as
  1386. a symbol. It must return the modified parse tree to transcode.")
  1387. (defvar org-export-filter-final-output-functions nil
  1388. "Filter, or list of filters, applied to the transcoded string.
  1389. Each filter is called with two arguments: the full transcoded
  1390. string, and the back-end as a symbol. It must return a string
  1391. that will be used as the final export output.")
  1392. (defvar org-export-filter-plain-text-functions nil
  1393. "Filter, or list of filters, applied to plain text.
  1394. Each filter is called with two arguments: a string which contains
  1395. no Org syntax, and the back-end as a symbol. It must return
  1396. a string or nil.")
  1397. ;;;; Elements Filters
  1398. (defvar org-export-filter-center-block-functions nil
  1399. "Filter, or list of filters, applied to a transcoded center block.
  1400. Each filter is called with two arguments: the transcoded center
  1401. block, as a string, and the back-end, as a symbol. It must
  1402. return a string or nil.")
  1403. (defvar org-export-filter-drawer-functions nil
  1404. "Filter, or list of filters, applied to a transcoded drawer.
  1405. Each filter is called with two arguments: the transcoded drawer,
  1406. as a string, and the back-end, as a symbol. It must return
  1407. a string or nil.")
  1408. (defvar org-export-filter-dynamic-block-functions nil
  1409. "Filter, or list of filters, applied to a transcoded dynamic-block.
  1410. Each filter is called with two arguments: the transcoded
  1411. dynamic-block, as a string, and the back-end, as a symbol. It
  1412. must return a string or nil.")
  1413. (defvar org-export-filter-headline-functions nil
  1414. "Filter, or list of filters, applied to a transcoded headline.
  1415. Each filter is called with two arguments: the transcoded
  1416. headline, as a string, and the back-end, as a symbol. It must
  1417. return a string or nil.")
  1418. (defvar org-export-filter-inlinetask-functions nil
  1419. "Filter, or list of filters, applied to a transcoded inlinetask.
  1420. Each filter is called with two arguments: the transcoded
  1421. inlinetask, as a string, and the back-end, as a symbol. It must
  1422. return a string or nil.")
  1423. (defvar org-export-filter-plain-list-functions nil
  1424. "Filter, or list of filters, applied to a transcoded plain-list.
  1425. Each filter is called with two arguments: the transcoded
  1426. plain-list, as a string, and the back-end, as a symbol. It must
  1427. return a string or nil.")
  1428. (defvar org-export-filter-item-functions nil
  1429. "Filter, or list of filters, applied to a transcoded item.
  1430. Each filter is called with two arguments: the transcoded item, as
  1431. a string, and the back-end, as a symbol. It must return a string
  1432. or nil.")
  1433. (defvar org-export-filter-comment-functions nil
  1434. "Filter, or list of filters, applied to a transcoded comment.
  1435. Each filter is called with two arguments: the transcoded comment,
  1436. as a string, and the back-end, as a symbol. It must return
  1437. a string or nil.")
  1438. (defvar org-export-filter-comment-block-functions nil
  1439. "Filter, or list of filters, applied to a transcoded comment-comment.
  1440. Each filter is called with two arguments: the transcoded
  1441. comment-block, as a string, and the back-end, as a symbol. It
  1442. must return a string or nil.")
  1443. (defvar org-export-filter-example-block-functions nil
  1444. "Filter, or list of filters, applied to a transcoded example-block.
  1445. Each filter is called with two arguments: the transcoded
  1446. example-block, as a string, and the back-end, as a symbol. It
  1447. must return a string or nil.")
  1448. (defvar org-export-filter-export-block-functions nil
  1449. "Filter, or list of filters, applied to a transcoded export-block.
  1450. Each filter is called with two arguments: the transcoded
  1451. export-block, as a string, and the back-end, as a symbol. It
  1452. must return a string or nil.")
  1453. (defvar org-export-filter-fixed-width-functions nil
  1454. "Filter, or list of filters, applied to a transcoded fixed-width.
  1455. Each filter is called with two arguments: the transcoded
  1456. fixed-width, as a string, and the back-end, as a symbol. It must
  1457. return a string or nil.")
  1458. (defvar org-export-filter-footnote-definition-functions nil
  1459. "Filter, or list of filters, applied to a transcoded footnote-definition.
  1460. Each filter is called with two arguments: the transcoded
  1461. footnote-definition, as a string, and the back-end, as a symbol.
  1462. It must return a string or nil.")
  1463. (defvar org-export-filter-horizontal-rule-functions nil
  1464. "Filter, or list of filters, applied to a transcoded horizontal-rule.
  1465. Each filter is called with two arguments: the transcoded
  1466. horizontal-rule, as a string, and the back-end, as a symbol. It
  1467. must return a string or nil.")
  1468. (defvar org-export-filter-keyword-functions nil
  1469. "Filter, or list of filters, applied to a transcoded keyword.
  1470. Each filter is called with two arguments: the transcoded keyword,
  1471. as a string, and the back-end, as a symbol. It must return
  1472. a string or nil.")
  1473. (defvar org-export-filter-latex-environment-functions nil
  1474. "Filter, or list of filters, applied to a transcoded latex-environment.
  1475. Each filter is called with two arguments: the transcoded
  1476. latex-environment, as a string, and the back-end, as a symbol.
  1477. It must return a string or nil.")
  1478. (defvar org-export-filter-babel-call-functions nil
  1479. "Filter, or list of filters, applied to a transcoded babel-call.
  1480. Each filter is called with two arguments: the transcoded
  1481. babel-call, as a string, and the back-end, as a symbol. It must
  1482. return a string or nil.")
  1483. (defvar org-export-filter-paragraph-functions nil
  1484. "Filter, or list of filters, applied to a transcoded paragraph.
  1485. Each filter is called with two arguments: the transcoded
  1486. paragraph, as a string, and the back-end, as a symbol. It must
  1487. return a string or nil.")
  1488. (defvar org-export-filter-property-drawer-functions nil
  1489. "Filter, or list of filters, applied to a transcoded property-drawer.
  1490. Each filter is called with two arguments: the transcoded
  1491. property-drawer, as a string, and the back-end, as a symbol. It
  1492. must return a string or nil.")
  1493. (defvar org-export-filter-quote-block-functions nil
  1494. "Filter, or list of filters, applied to a transcoded quote block.
  1495. Each filter is called with two arguments: the transcoded quote
  1496. block, as a string, and the back-end, as a symbol. It must
  1497. return a string or nil.")
  1498. (defvar org-export-filter-quote-section-functions nil
  1499. "Filter, or list of filters, applied to a transcoded quote-section.
  1500. Each filter is called with two arguments: the transcoded
  1501. quote-section, as a string, and the back-end, as a symbol. It
  1502. must return a string or nil.")
  1503. (defvar org-export-filter-special-block-functions nil
  1504. "Filter, or list of filters, applied to a transcoded special block.
  1505. Each filter is called with two arguments: the transcoded special
  1506. block, as a string, and the back-end, as a symbol. It must
  1507. return a string or nil.")
  1508. (defvar org-export-filter-src-block-functions nil
  1509. "Filter, or list of filters, applied to a transcoded src-block.
  1510. Each filter is called with two arguments: the transcoded
  1511. src-block, as a string, and the back-end, as a symbol. It must
  1512. return a string or nil.")
  1513. (defvar org-export-filter-table-functions nil
  1514. "Filter, or list of filters, applied to a transcoded table.
  1515. Each filter is called with two arguments: the transcoded table,
  1516. as a string, and the back-end, as a symbol. It must return
  1517. a string or nil.")
  1518. (defvar org-export-filter-verse-block-functions nil
  1519. "Filter, or list of filters, applied to a transcoded verse block.
  1520. Each filter is called with two arguments: the transcoded verse
  1521. block, as a string, and the back-end, as a symbol. It must
  1522. return a string or nil.")
  1523. ;;;; Objects Filters
  1524. (defvar org-export-filter-emphasis-functions nil
  1525. "Filter, or list of filters, applied to a transcoded emphasis.
  1526. Each filter is called with two arguments: the transcoded
  1527. emphasis, as a string, and the back-end, as a symbol. It must
  1528. return a string or nil.")
  1529. (defvar org-export-filter-entity-functions nil
  1530. "Filter, or list of filters, applied to a transcoded entity.
  1531. Each filter is called with two arguments: the transcoded entity,
  1532. as a string, and the back-end, as a symbol. It must return
  1533. a string or nil.")
  1534. (defvar org-export-filter-export-snippet-functions nil
  1535. "Filter, or list of filters, applied to a transcoded export-snippet.
  1536. Each filter is called with two arguments: the transcoded
  1537. export-snippet, as a string, and the back-end, as a symbol. It
  1538. must return a string or nil.")
  1539. (defvar org-export-filter-footnote-reference-functions nil
  1540. "Filter, or list of filters, applied to a transcoded footnote-reference.
  1541. Each filter is called with two arguments: the transcoded
  1542. footnote-reference, as a string, and the back-end, as a symbol.
  1543. It must return a string or nil.")
  1544. (defvar org-export-filter-inline-babel-call-functions nil
  1545. "Filter, or list of filters, applied to a transcoded inline-babel-call.
  1546. Each filter is called with two arguments: the transcoded
  1547. inline-babel-call, as a string, and the back-end, as a symbol. It
  1548. must return a string or nil.")
  1549. (defvar org-export-filter-inline-src-block-functions nil
  1550. "Filter, or list of filters, applied to a transcoded inline-src-block.
  1551. Each filter is called with two arguments: the transcoded
  1552. inline-src-block, as a string, and the back-end, as a symbol. It
  1553. must return a string or nil.")
  1554. (defvar org-export-filter-latex-fragment-functions nil
  1555. "Filter, or list of filters, applied to a transcoded latex-fragment.
  1556. Each filter is called with two arguments: the transcoded
  1557. latex-fragment, as a string, and the back-end, as a symbol. It
  1558. must return a string or nil.")
  1559. (defvar org-export-filter-line-break-functions nil
  1560. "Filter, or list of filters, applied to a transcoded line-break.
  1561. Each filter is called with two arguments: the transcoded
  1562. line-break, as a string, and the back-end, as a symbol. It must
  1563. return a string or nil.")
  1564. (defvar org-export-filter-link-functions nil
  1565. "Filter, or list of filters, applied to a transcoded link.
  1566. Each filter is called with two arguments: the transcoded link, as
  1567. a string, and the back-end, as a symbol. It must return a string
  1568. or nil.")
  1569. (defvar org-export-filter-macro-functions nil
  1570. "Filter, or list of filters, applied to a transcoded macro.
  1571. Each filter is called with two arguments: the transcoded macro,
  1572. as a string, and the back-end, as a symbol. It must return
  1573. a string or nil.")
  1574. (defvar org-export-filter-radio-target-functions nil
  1575. "Filter, or list of filters, applied to a transcoded radio-target.
  1576. Each filter is called with two arguments: the transcoded
  1577. radio-target, as a string, and the back-end, as a symbol. It
  1578. must return a string or nil.")
  1579. (defvar org-export-filter-statistics-cookie-functions nil
  1580. "Filter, or list of filters, applied to a transcoded statistics-cookie.
  1581. Each filter is called with two arguments: the transcoded
  1582. statistics-cookie, as a string, and the back-end, as a symbol.
  1583. It must return a string or nil.")
  1584. (defvar org-export-filter-subscript-functions nil
  1585. "Filter, or list of filters, applied to a transcoded subscript.
  1586. Each filter is called with two arguments: the transcoded
  1587. subscript, as a string, and the back-end, as a symbol. It must
  1588. return a string or nil.")
  1589. (defvar org-export-filter-superscript-functions nil
  1590. "Filter, or list of filters, applied to a transcoded superscript.
  1591. Each filter is called with two arguments: the transcoded
  1592. superscript, as a string, and the back-end, as a symbol. It must
  1593. return a string or nil.")
  1594. (defvar org-export-filter-target-functions nil
  1595. "Filter, or list of filters, applied to a transcoded target.
  1596. Each filter is called with two arguments: the transcoded target,
  1597. as a string, and the back-end, as a symbol. It must return
  1598. a string or nil.")
  1599. (defvar org-export-filter-time-stamp-functions nil
  1600. "Filter, or list of filters, applied to a transcoded time-stamp.
  1601. Each filter is called with two arguments: the transcoded
  1602. time-stamp, as a string, and the back-end, as a symbol. It must
  1603. return a string or nil.")
  1604. (defvar org-export-filter-verbatim-functions nil
  1605. "Filter, or list of filters, applied to a transcoded verbatim.
  1606. Each filter is called with two arguments: the transcoded
  1607. verbatim, as a string, and the back-end, as a symbol. It must
  1608. return a string or nil.")
  1609. (defun org-export-filter-apply-functions (filters value backend)
  1610. "Call every function in FILTERS with arguments VALUE and BACKEND.
  1611. Functions are called in reverse order, to be reasonably sure that
  1612. developer-specified filters, if any, are called first."
  1613. ;; Ensure FILTERS is a list.
  1614. (let ((filters (if (listp filters) (reverse filters) (list filters))))
  1615. (loop for filter in filters
  1616. if (not value) return nil else
  1617. do (setq value (funcall filter value backend))))
  1618. value)
  1619. ;;; Core functions
  1620. ;; This is the room for the main function, `org-export-as', along with
  1621. ;; its derivatives, `org-export-to-buffer' and `org-export-to-file'.
  1622. ;; They differ only by the way they output the resulting code.
  1623. ;; Note that `org-export-as' doesn't really parse the current buffer,
  1624. ;; but a copy of it (with the same buffer-local variables and
  1625. ;; visibility), where Babel blocks are executed, if appropriate.
  1626. ;; `org-export-with-current-buffer-copy' macro prepares that copy.
  1627. (defun org-export-as (backend
  1628. &optional subtreep visible-only body-only ext-plist)
  1629. "Transcode current Org buffer into BACKEND code.
  1630. If narrowing is active in the current buffer, only transcode its
  1631. narrowed part.
  1632. If a region is active, transcode that region.
  1633. When optional argument SUBTREEP is non-nil, transcode the
  1634. sub-tree at point, extracting information from the headline
  1635. properties first.
  1636. When optional argument VISIBLE-ONLY is non-nil, don't export
  1637. contents of hidden elements.
  1638. When optional argument BODY-ONLY is non-nil, only return body
  1639. code, without preamble nor postamble.
  1640. EXT-PLIST, when provided, is a property list with external
  1641. parameters overriding Org default settings, but still inferior to
  1642. file-local settings.
  1643. Return code as a string."
  1644. (save-excursion
  1645. (save-restriction
  1646. ;; Narrow buffer to an appropriate region for parsing.
  1647. (when (org-region-active-p)
  1648. (narrow-to-region (region-beginning) (region-end)))
  1649. (goto-char (point-min))
  1650. (when subtreep
  1651. (unless (org-at-heading-p)
  1652. (org-with-limited-levels (outline-next-heading)))
  1653. (let ((end (save-excursion (org-end-of-subtree t)))
  1654. (begin (progn (forward-line)
  1655. (org-skip-whitespace)
  1656. (point-at-bol))))
  1657. (narrow-to-region begin end)))
  1658. ;; Retrieve export options (INFO) and parsed tree (RAW-DATA).
  1659. ;; Buffer isn't parsed directly. Instead, a temporary copy is
  1660. ;; created, where all code blocks are evaluated. RAW-DATA is
  1661. ;; the parsed tree of the buffer resulting from that process.
  1662. ;; Eventually call `org-export-filter-parse-tree-functions'..
  1663. (let ((info (org-export-collect-options backend subtreep ext-plist))
  1664. (raw-data (org-export-filter-apply-functions
  1665. org-export-filter-parse-tree-functions
  1666. (org-export-with-current-buffer-copy
  1667. (org-export-blocks-preprocess)
  1668. (org-element-parse-buffer nil visible-only))
  1669. backend)))
  1670. ;; Initialize the communication system and combine it to INFO.
  1671. (setq info
  1672. (org-combine-plists
  1673. info
  1674. (org-export-initialize-persistent-properties
  1675. raw-data info backend)))
  1676. ;; Now transcode RAW-DATA. Also call
  1677. ;; `org-export-filter-final-output-functions'.
  1678. (let ((body (org-element-normalize-string
  1679. (org-export-data raw-data backend info)))
  1680. (template (intern (format "org-%s-template" backend))))
  1681. (if (and (not body-only) (fboundp template))
  1682. (org-trim
  1683. (org-export-filter-apply-functions
  1684. org-export-filter-final-output-functions
  1685. (funcall template body info)
  1686. backend))
  1687. (org-export-filter-apply-functions
  1688. org-export-filter-final-output-functions body backend)))))))
  1689. (defun org-export-to-buffer (backend buffer &optional subtreep visible-only
  1690. body-only ext-plist)
  1691. "Call `org-export-as' with output to a specified buffer.
  1692. BACKEND is the back-end used for transcoding, as a symbol.
  1693. BUFFER is the output buffer. If it already exists, it will be
  1694. erased first, otherwise, it will be created.
  1695. Arguments SUBTREEP, VISIBLE-ONLY, BODY-ONLY and EXT-PLIST are
  1696. similar to those used in `org-export-as', which see.
  1697. Return buffer."
  1698. (let ((out (org-export-as backend subtreep visible-only body-only ext-plist))
  1699. (buffer (get-buffer-create buffer)))
  1700. (with-current-buffer buffer
  1701. (erase-buffer)
  1702. (insert out)
  1703. (goto-char (point-min)))
  1704. buffer))
  1705. (defun org-export-to-file (backend filename &optional post-process subtreep
  1706. visible-only body-only ext-plist)
  1707. "Call `org-export-as' with output to a specified file.
  1708. BACKEND is the back-end used for transcoding, as a symbol.
  1709. FILENAME is the output file name. If it already exists, it will
  1710. be erased first, unless it isn't writable, in which case an error
  1711. will be returned. Otherwise, the file will be created.
  1712. Optional argument POST-PROCESS, when non-nil, is a function
  1713. applied to the output file. It expects one argument: the file
  1714. name, as a string. It can be used to call shell commands on that
  1715. file, display a specific buffer, etc.
  1716. Optional arguments SUBTREEP, VISIBLE-ONLY, BODY-ONLY and
  1717. EXT-PLIST are similar to those used in `org-export-as', which
  1718. see.
  1719. Return file name."
  1720. ;; Checks for file and directory permissions.
  1721. (cond
  1722. ((not (file-exists-p filename))
  1723. (let ((dir (or (file-name-directory filename) default-directory)))
  1724. (unless (file-writable-p dir) (error "Output directory not writable"))))
  1725. ((not (file-writable-p filename)) (error "Output file not writable")))
  1726. ;; All checks passed: insert contents to a temporary buffer and
  1727. ;; write it to the specified file.
  1728. (let ((out (org-export-as backend subtreep visible-only body-only ext-plist)))
  1729. (with-temp-buffer
  1730. (insert out)
  1731. (write-file filename)))
  1732. (when post-process (funcall post-process filename))
  1733. ;; Return value.
  1734. filename)
  1735. (defmacro org-export-with-current-buffer-copy (&rest body)
  1736. "Apply BODY in a copy of the current buffer.
  1737. The copy preserves local variables and visibility of the original
  1738. buffer.
  1739. Point is at buffer's beginning when BODY is applied."
  1740. (org-with-gensyms (original-buffer offset buffer-string overlays)
  1741. `(let ((,original-buffer ,(current-buffer))
  1742. (,offset ,(1- (point-min)))
  1743. (,buffer-string ,(buffer-string))
  1744. (,overlays (mapcar
  1745. 'copy-overlay (overlays-in (point-min) (point-max)))))
  1746. (with-temp-buffer
  1747. (let ((buffer-invisibility-spec nil))
  1748. (org-clone-local-variables
  1749. ,original-buffer "^\\(org-\\|orgtbl-\\|major-mode$\\)")
  1750. (insert ,buffer-string)
  1751. (mapc (lambda (ov)
  1752. (move-overlay
  1753. ov
  1754. (- (overlay-start ov) ,offset)
  1755. (- (overlay-end ov) ,offset)
  1756. (current-buffer)))
  1757. ,overlays)
  1758. (goto-char (point-min))
  1759. (progn ,@body))))))
  1760. (def-edebug-spec org-export-with-current-buffer-copy (body))
  1761. ;;; Tools For Back-Ends
  1762. ;; A whole set of tools is available to help build new exporters. Any
  1763. ;; function general enough to have its use across many back-ends
  1764. ;; should be added here.
  1765. ;; As of now, functions operating on headlines, include keywords,
  1766. ;; links, macros, references, src-blocks, tables and tables of
  1767. ;; contents are implemented.
  1768. ;;;; For Headlines
  1769. ;; `org-export-get-relative-level' is a shortcut to get headline
  1770. ;; level, relatively to the lower headline level in the parsed tree.
  1771. ;; `org-export-get-headline-number' returns the section number of an
  1772. ;; headline, while `org-export-number-to-roman' allows to convert it
  1773. ;; to roman numbers.
  1774. ;; `org-export-first-sibling-p' and `org-export-last-sibling-p' are
  1775. ;; two useful predicates when it comes to fulfill the
  1776. ;; `:headline-levels' property.
  1777. (defun org-export-get-relative-level (headline info)
  1778. "Return HEADLINE relative level within current parsed tree.
  1779. INFO is a plist holding contextual information."
  1780. (+ (org-element-get-property :level headline)
  1781. (or (plist-get info :headline-offset) 0)))
  1782. (defun org-export-get-headline-number (headline info)
  1783. "Return HEADLINE numbering as a list of numbers.
  1784. INFO is a plist holding contextual information."
  1785. (cdr (assq (org-element-get-property :begin headline)
  1786. (plist-get info :headline-numbering))))
  1787. (defun org-export-number-to-roman (n)
  1788. "Convert integer N into a roman numeral."
  1789. (let ((roman '((1000 . "M") (900 . "CM") (500 . "D") (400 . "CD")
  1790. ( 100 . "C") ( 90 . "XC") ( 50 . "L") ( 40 . "XL")
  1791. ( 10 . "X") ( 9 . "IX") ( 5 . "V") ( 4 . "IV")
  1792. ( 1 . "I")))
  1793. (res ""))
  1794. (if (<= n 0)
  1795. (number-to-string n)
  1796. (while roman
  1797. (if (>= n (caar roman))
  1798. (setq n (- n (caar roman))
  1799. res (concat res (cdar roman)))
  1800. (pop roman)))
  1801. res)))
  1802. (defun org-export-first-sibling-p (headline info)
  1803. "Non-nil when HEADLINE is the first sibling in its sub-tree.
  1804. INFO is the plist used as a communication channel."
  1805. (not (eq (plist-get info :previous-element) 'headline)))
  1806. (defun org-export-last-sibling-p (headline info)
  1807. "Non-nil when HEADLINE is the last sibling in its sub-tree.
  1808. INFO is the plist used as a communication channel."
  1809. (= (org-element-get-property :end headline)
  1810. (or (plist-get (plist-get info :parent-properties) :end)
  1811. (plist-get info :point-max))))
  1812. ;;;; For Include Keywords
  1813. ;; This section provides a tool to properly handle insertion of files
  1814. ;; during export: `org-export-included-files'. It recursively
  1815. ;; transcodes a file specfied by an include keyword.
  1816. ;; It uses two helper functions: `org-export-get-file-contents'
  1817. ;; returns contents of a file according to parameters specified in the
  1818. ;; keyword while `org-export-parse-included-file' parses the file
  1819. ;; specified by it.
  1820. (defun org-export-included-file (keyword backend info)
  1821. "Transcode file specified with include KEYWORD.
  1822. KEYWORD is the include keyword element transcoded. BACKEND is
  1823. the language back-end used for transcoding. INFO is the plist
  1824. used as a communication channel.
  1825. This function updates `:included-files' and `:headline-offset'
  1826. properties.
  1827. Return the transcoded string."
  1828. (let ((data (org-export-parse-included-file keyword info))
  1829. (file (let ((value (org-element-get-property :value keyword)))
  1830. (and (string-match "^\"\\(\\S-+\\)\"" value)
  1831. (match-string 1 value)))))
  1832. (org-element-normalize-string
  1833. (org-export-data
  1834. data backend
  1835. (org-combine-plists
  1836. info
  1837. ;; Store full path of already included files to avoid
  1838. ;; recursive file inclusion.
  1839. `(:included-files
  1840. ,(cons (expand-file-name file) (plist-get info :included-files))
  1841. ;; Ensure that a top-level headline in the included
  1842. ;; file becomes a direct child of the current headline
  1843. ;; in the buffer.
  1844. :headline-offset
  1845. ,(- (+ (plist-get (plist-get info :inherited-properties) :level)
  1846. (plist-get info :headline-offset))
  1847. (1- (org-export-get-min-level data info)))))))))
  1848. (defun org-export-get-file-contents (file &optional lines)
  1849. "Get the contents of FILE and return them as a string.
  1850. When optional argument LINES is a string specifying a range of
  1851. lines, include only those lines."
  1852. (with-temp-buffer
  1853. (insert-file-contents file)
  1854. (when lines
  1855. (let* ((lines (split-string lines "-"))
  1856. (lbeg (string-to-number (car lines)))
  1857. (lend (string-to-number (cadr lines)))
  1858. (beg (if (zerop lbeg) (point-min)
  1859. (goto-char (point-min))
  1860. (forward-line (1- lbeg))
  1861. (point)))
  1862. (end (if (zerop lend) (point-max)
  1863. (goto-char (point-min))
  1864. (forward-line (1- lend))
  1865. (point))))
  1866. (narrow-to-region beg end)))
  1867. (buffer-string)))
  1868. (defun org-export-parse-included-file (keyword info)
  1869. "Parse file specified by include KEYWORD.
  1870. KEYWORD is the include keyword element transcoded. BACKEND is the
  1871. language back-end used for transcoding. INFO is the plist used as
  1872. a communication channel.
  1873. Return the parsed tree."
  1874. (let* ((value (org-element-get-property :value keyword))
  1875. (file (and (string-match "^\"\\(\\S-+\\)\"" value)
  1876. (prog1 (match-string 1 value)
  1877. (setq value (replace-match "" nil nil value)))))
  1878. (lines (and (string-match
  1879. ":lines +\"\\(\\(?:[0-9]+\\)?-\\(?:[0-9]+\\)?\\)\"" value)
  1880. (prog1 (match-string 1 value)
  1881. (setq value (replace-match "" nil nil value)))))
  1882. (env (cond ((string-match "\\<example\\>" value) "example")
  1883. ((string-match "\\<src\\(?: +\\(.*\\)\\)?" value)
  1884. (match-string 1 value)))))
  1885. (cond
  1886. ((or (not file)
  1887. (not (file-exists-p file))
  1888. (not (file-readable-p file)))
  1889. (format "Cannot include file %s" file))
  1890. ((and (not env)
  1891. (member (expand-file-name file) (plist-get info :included-files)))
  1892. (error "Recursive file inclusion: %S" file))
  1893. (t (let ((raw (org-element-normalize-string
  1894. (org-export-get-file-contents
  1895. (expand-file-name file) lines))))
  1896. ;; If environment isn't specified, Insert file in
  1897. ;; a temporary buffer and parse it as Org syntax.
  1898. ;; Otherwise, build the element representing the file.
  1899. (cond
  1900. ((not env)
  1901. (with-temp-buffer
  1902. (insert raw) (org-mode) (org-element-parse-buffer)))
  1903. ((string= "example" env)
  1904. `(org-data nil (example-block (:value ,raw :post-blank 0))))
  1905. (t
  1906. `(org-data
  1907. nil
  1908. (src-block (:value ,raw :language ,env :post-blank 0))))))))))
  1909. ;;;; For Links
  1910. ;; `org-export-solidify-link-text' turns a string into a safer version
  1911. ;; for links, replacing most non-standard characters with hyphens.
  1912. ;; `org-export-get-coderef-format' returns an appropriate format
  1913. ;; string for coderefs.
  1914. ;; `org-export-inline-image-p' returns a non-nil value when the link
  1915. ;; provided should be considered as an inline image.
  1916. ;; `org-export-resolve-fuzzy-link' searches destination of fuzzy links
  1917. ;; (i.e. links with "fuzzy" as type) within the parsed tree, and
  1918. ;; returns an appropriate unique identifier when found, or nil.
  1919. (defun org-export-solidify-link-text (s)
  1920. "Take link text and make a safe target out of it."
  1921. (save-match-data
  1922. (mapconcat 'identity (org-split-string s "[^a-zA-Z0-9_\\.-]+") "-")))
  1923. (defun org-export-get-coderef-format (path desc)
  1924. "Return format string for code reference link.
  1925. PATH is the link path. DESC is its description."
  1926. (save-match-data
  1927. (cond ((string-match (regexp-quote (concat "(" path ")")) desc)
  1928. (replace-match "%s" t t desc))
  1929. ((string= desc "") "%s")
  1930. (t desc))))
  1931. (defun org-export-inline-image-p (link &optional extensions)
  1932. "Non-nil if LINK object points to an inline image.
  1933. When non-nil, optional argument EXTENSIONS is a list of valid
  1934. extensions for image files, as strings. Otherwise, a default
  1935. list is provided \(cf. `org-image-file-name-regexp'\)."
  1936. (and (not (org-element-get-contents link))
  1937. (string= (org-element-get-property :type link) "file")
  1938. (org-file-image-p
  1939. (expand-file-name (org-element-get-property :path link))
  1940. extensions)))
  1941. (defun org-export-resolve-fuzzy-link (link info)
  1942. "Return an unique identifier for LINK destination.
  1943. INFO is a plist holding contextual information.
  1944. Return value can be a string, an buffer position, or nil:
  1945. - If LINK path exactly matches any target, return its name as the
  1946. identifier.
  1947. - If LINK path exactly matches any headline name, return
  1948. headline's beginning position as the identifier. If more than
  1949. one headline share that name, priority will be given to the one
  1950. with the closest common ancestor, if any, or the first one in
  1951. the parse tree otherwise.
  1952. - Otherwise, return nil.
  1953. Assume LINK type is \"fuzzy\"."
  1954. (let ((path (org-element-get-property :path link)))
  1955. (if (member path (plist-get info :target-list))
  1956. ;; Link points to a target: return its name as a string.
  1957. path
  1958. ;; Link either points to an headline or nothing. Try to find
  1959. ;; the source, with priority given to headlines with the closest
  1960. ;; common ancestor. If such candidate is found, return its
  1961. ;; beginning position as an unique identifier, otherwise return
  1962. ;; nil.
  1963. (let* ((head-alist (plist-get info :headline-alist))
  1964. (link-begin (org-element-get-property :begin link))
  1965. (link-end (org-element-get-property :end link))
  1966. ;; Store candidates as a list of cons cells holding their
  1967. ;; beginning and ending position.
  1968. (cands (loop for head in head-alist
  1969. when (string= (car head) path)
  1970. collect (cons (nth 1 head) (nth 2 head)))))
  1971. (cond
  1972. ;; No candidate: return nil.
  1973. ((not cands) nil)
  1974. ;; If one or more candidates share common ancestors with
  1975. ;; LINK, return beginning position of the first one matching
  1976. ;; the closer ancestor shared.
  1977. ((let ((ancestors (loop for head in head-alist
  1978. when (and (> link-begin (nth 1 head))
  1979. (<= link-end (nth 2 head)))
  1980. collect (cons (nth 1 head) (nth 2 head)))))
  1981. (loop named main for ancestor in (nreverse ancestors) do
  1982. (loop for candidate in cands
  1983. when (and (>= (car candidate) (car ancestor))
  1984. (<= (cdr candidate) (cdr ancestor)))
  1985. do (return-from main (car candidate))))))
  1986. ;; No candidate have a common ancestor with link: First match
  1987. ;; will do. Return its beginning position.
  1988. (t (caar cands)))))))
  1989. ;;;; For Macros
  1990. ;; `org-export-expand-macro' simply takes care of expanding macros.
  1991. (defun org-export-expand-macro (macro info)
  1992. "Expand MACRO and return it as a string.
  1993. INFO is a plist holding export options."
  1994. (let* ((key (org-element-get-property :key macro))
  1995. (args (org-element-get-property :args macro))
  1996. (value (plist-get info (intern (format ":macro-%s" key)))))
  1997. ;; Replace arguments in VALUE.
  1998. (let ((s 0) n)
  1999. (while (string-match "\\$\\([0-9]+\\)" value s)
  2000. (setq s (1+ (match-beginning 0))
  2001. n (string-to-number (match-string 1 value)))
  2002. (and (>= (length args) n)
  2003. (setq value (replace-match (nth (1- n) args) t t value)))))
  2004. ;; VALUE starts with "(eval": it is a s-exp, `eval' it.
  2005. (when (string-match "\\`(eval\\>" value)
  2006. (setq value (eval (read value))))
  2007. ;; Return expanded string.
  2008. (format "%s" value)))
  2009. ;;;; For References
  2010. ;; `org-export-get-ordinal' associates a sequence number to any object
  2011. ;; or element.
  2012. (defun org-export-get-ordinal (element info &optional within-section predicate)
  2013. "Return ordinal number of an element or object.
  2014. ELEMENT is the element or object considered. INFO is the plist
  2015. used as a communication channel.
  2016. When optional argument WITHIN-SECTION is non-nil, narrow counting
  2017. to the section containing ELEMENT.
  2018. Optional argument PREDICATE is a function returning a non-nil
  2019. value if the current element or object should be counted in. It
  2020. accepts one argument: the element or object being considered.
  2021. This argument allows to count only a certain type of objects,
  2022. like inline images, which are a subset of links \(in that case,
  2023. `org-export-inline-image-p' might be an useful predicate\)."
  2024. (let ((counter 0)
  2025. (type (car element))
  2026. ;; Determine if search should apply to current section, in
  2027. ;; which case it should be retrieved first, or to full parse
  2028. ;; tree. As a special case, an element or object without
  2029. ;; a parent headline will also trigger a full search,
  2030. ;; notwithstanding WITHIN-SECTION value.
  2031. (data
  2032. (let ((parse-tree (plist-get info :parse-tree)))
  2033. (if within-section
  2034. (let ((parent (plist-get (plist-get info :inherited-properties)
  2035. :begin)))
  2036. (if (not parent) parse-tree
  2037. (org-element-map
  2038. parse-tree 'headline
  2039. (lambda (el local)
  2040. (when (= (org-element-get-property :begin el) parent) el))
  2041. info 'first-match)))
  2042. parse-tree))))
  2043. ;; Increment counter until ELEMENT is found again.
  2044. (org-element-map
  2045. data type
  2046. (lambda (el local)
  2047. (cond
  2048. ((and (functionp predicate) (funcall predicate el)))
  2049. ((equal element el) (1+ counter))
  2050. (t (incf counter) nil)))
  2051. info 'first-match)))
  2052. ;;;; For Src-Blocks
  2053. ;; `org-export-handle-code' takes care of line numbering and reference
  2054. ;; cleaning in source code, when appropriate. It also updates global
  2055. ;; LOC count (`:total-loc' property) and code references alist
  2056. ;; (`:code-refs' property).
  2057. (defun org-export-handle-code (code switches info
  2058. &optional language num-fmt ref-fmt)
  2059. "Handle line numbers and code references in CODE.
  2060. CODE is the string to process. SWITCHES is the option string
  2061. determining which changes will be applied to CODE. INFO is the
  2062. plist used as a communication channel during export.
  2063. Optional argument LANGUAGE, when non-nil, is a string specifying
  2064. code's language.
  2065. If optional argument NUM-FMT is a string, it will be used as
  2066. a format string for numbers at beginning of each line.
  2067. If optional argument REF-FMT is a string, it will be used as
  2068. a format string for each line of code containing a reference.
  2069. Update the following INFO properties by side-effect: `:total-loc'
  2070. and `:code-refs'.
  2071. Return new code as a string."
  2072. (let* ((switches (or switches ""))
  2073. (numberp (string-match "[-+]n\\>" switches))
  2074. (continuep (string-match "\\+n\\>" switches))
  2075. (total-LOC (if (and numberp (not continuep))
  2076. 0
  2077. (or (plist-get info :total-loc) 0)))
  2078. (preserve-indent-p (or org-src-preserve-indentation
  2079. (string-match "-i\\>" switches)))
  2080. (replace-labels (when (string-match "-r\\>" switches)
  2081. (if (string-match "-k\\>" switches) 'keep t)))
  2082. ;; Get code and clean it. Remove blank lines at its
  2083. ;; beginning and end. Also remove protective commas.
  2084. (code (let ((c (replace-regexp-in-string
  2085. "\\`\\([ \t]*\n\\)+" ""
  2086. (replace-regexp-in-string
  2087. "\\(:?[ \t]*\n\\)*[ \t]*\\'" "\n" code))))
  2088. ;; If appropriate, remove global indentation.
  2089. (unless preserve-indent-p (setq c (org-remove-indentation c)))
  2090. ;; Free up the protected lines. Note: Org blocks
  2091. ;; have commas at the beginning or every line.
  2092. (if (string= language "org")
  2093. (replace-regexp-in-string "^," "" c)
  2094. (replace-regexp-in-string
  2095. "^\\(,\\)\\(:?\\*\\|[ \t]*#\\+\\)" "" c nil nil 1))))
  2096. ;; Split code to process it line by line.
  2097. (code-lines (org-split-string code "\n"))
  2098. ;; Ensure line numbers will be correctly padded before
  2099. ;; applying the format string.
  2100. (num-fmt (format (if (stringp num-fmt) num-fmt "%s: ")
  2101. (format "%%%ds"
  2102. (length (number-to-string
  2103. (+ (length code-lines)
  2104. total-LOC))))))
  2105. ;; Get format used for references.
  2106. (label-fmt (or (and (string-match "-l +\"\\([^\"\n]+\\)\"" switches)
  2107. (match-string 1 switches))
  2108. org-coderef-label-format))
  2109. ;; Build a regexp matching a loc with a reference.
  2110. (with-ref-re (format "^.*?\\S-.*?\\([ \t]*\\(%s\\)\\)[ \t]*$"
  2111. (replace-regexp-in-string
  2112. "%s" "\\([-a-zA-Z0-9_ ]+\\)" label-fmt nil t)))
  2113. coderefs)
  2114. (org-element-normalize-string
  2115. (mapconcat (lambda (loc)
  2116. ;; Maybe add line number to current line of code
  2117. ;; (LOC).
  2118. (when numberp
  2119. (setq loc (concat (format num-fmt (incf total-LOC)) loc)))
  2120. ;; Take action if at a ref line.
  2121. (when (string-match with-ref-re loc)
  2122. (let ((ref (match-string 3 loc)))
  2123. (setq loc
  2124. (cond
  2125. ;; Option "-k": don't remove labels. Use
  2126. ;; numbers for references when lines are
  2127. ;; numbered, use labels otherwise.
  2128. ((eq replace-labels 'keep)
  2129. (let ((full-ref (format "(%s)" ref)))
  2130. (push (cons ref (if numberp total-LOC full-ref))
  2131. coderefs)
  2132. (replace-match full-ref nil nil loc 2))
  2133. (replace-match (format "(%s)" ref) nil nil loc 2))
  2134. ;; Option "-r" without "-k": remove labels.
  2135. ;; Use numbers for references when lines are
  2136. ;; numbered, use labels otherwise.
  2137. (replace-labels
  2138. (push (cons ref (if numberp total-LOC ref))
  2139. coderefs)
  2140. (replace-match "" nil nil loc 1))
  2141. ;; Else: don't remove labels and don't use
  2142. ;; numbers for references.
  2143. (t
  2144. (let ((full-ref (format "(%s)" ref)))
  2145. (push (cons ref full-ref) coderefs)
  2146. (replace-match full-ref nil nil loc 2)))))))
  2147. ;; If REF-FMT is defined, apply it to current LOC.
  2148. (when (stringp ref-fmt) (setq loc (format ref-fmt loc)))
  2149. ;; Update by side-effect communication channel.
  2150. ;; Return updated LOC.
  2151. (setq info (org-export-set-property
  2152. (org-export-set-property
  2153. info :code-refs coderefs)
  2154. :total-loc total-LOC))
  2155. loc)
  2156. code-lines "\n"))))
  2157. ;;;; For Tables
  2158. ;; `org-export-table-format-info' extracts formatting information
  2159. ;; (alignment, column groups and presence of a special column) from
  2160. ;; a raw table and returns it as a property list.
  2161. ;;
  2162. ;; `org-export-clean-table' cleans the raw table from any Org
  2163. ;; table-specific syntax.
  2164. (defun org-export-table-format-info (table)
  2165. "Extract info from TABLE.
  2166. Return a plist whose properties and values are:
  2167. `:alignment' vector of strings among \"r\", \"l\" and \"c\",
  2168. `:column-groups' vector of symbols among `start', `end', `start-end',
  2169. `:row-groups' list of integers representing row groups.
  2170. `:special-column-p' non-nil if table has a special column.
  2171. `:width' vector of integers representing desired width of
  2172. current column, or nil."
  2173. (with-temp-buffer
  2174. (insert table)
  2175. (goto-char 1)
  2176. (org-table-align)
  2177. (let ((align (vconcat (mapcar (lambda (c) (if c "r" "l"))
  2178. org-table-last-alignment)))
  2179. (width (make-vector (length org-table-last-alignment) nil))
  2180. (colgroups (make-vector (length org-table-last-alignment) nil))
  2181. (row-group 0)
  2182. (rowgroups)
  2183. (special-column-p 'empty))
  2184. (mapc (lambda (row)
  2185. (if (string-match "^[ \t]*|[-+]+|[ \t]*$" row)
  2186. (incf row-group)
  2187. (push row-group rowgroups)
  2188. ;; Determine if a special column is present by looking
  2189. ;; for special markers in the first column. More
  2190. ;; accurately, the first column is considered special
  2191. ;; if it only contains special markers and, maybe,
  2192. ;; empty cells.
  2193. (setq special-column-p
  2194. (cond
  2195. ((not special-column-p) nil)
  2196. ((string-match "^[ \t]*| *\\\\?\\([\#!$*_^]\\) *|"
  2197. row) 'special)
  2198. ((string-match "^[ \t]*| +|" row) special-column-p))))
  2199. (cond
  2200. ;; Read forced alignment and width information, if any,
  2201. ;; and determine final alignment for the table.
  2202. ((org-table-cookie-line-p row)
  2203. (let ((col 0))
  2204. (mapc (lambda (field)
  2205. (when (string-match "<\\([lrc]\\)\\([0-9]+\\)?>" field)
  2206. (aset align col (match-string 1 field))
  2207. (aset width col (let ((w (match-string 2 field)))
  2208. (and w (string-to-number w)))))
  2209. (incf col))
  2210. (org-split-string row "[ \t]*|[ \t]*"))))
  2211. ;; Read column groups information.
  2212. ((org-table-colgroup-line-p row)
  2213. (let ((col 0))
  2214. (mapc (lambda (field)
  2215. (aset colgroups col
  2216. (cond ((string= "<" field) 'start)
  2217. ((string= ">" field) 'end)
  2218. ((string= "<>" field) 'start-end)))
  2219. (incf col))
  2220. (org-split-string row "[ \t]*|[ \t]*"))))))
  2221. (org-split-string table "\n"))
  2222. ;; Return plist.
  2223. (list :alignment align
  2224. :column-groups colgroups
  2225. :row-groups (reverse rowgroups)
  2226. :special-column-p (eq special-column-p 'special)
  2227. :width width))))
  2228. (defun org-export-clean-table (table specialp)
  2229. "Clean string TABLE from its formatting elements.
  2230. Remove any row containing column groups or formatting cookies and
  2231. rows starting with a special marker. If SPECIALP is non-nil,
  2232. assume the table contains a special formatting column and remove
  2233. it also."
  2234. (let ((rows (org-split-string table "\n")))
  2235. (mapconcat 'identity
  2236. (delq nil
  2237. (mapcar
  2238. (lambda (row)
  2239. (cond
  2240. ((org-table-colgroup-line-p row) nil)
  2241. ((org-table-cookie-line-p row) nil)
  2242. ;; Ignore rows starting with a special marker.
  2243. ((string-match "^[ \t]*| *[!_^/] *|" row) nil)
  2244. ;; Remove special column.
  2245. ((and specialp
  2246. (or (string-match "^\\([ \t]*\\)|-+\\+" row)
  2247. (string-match "^\\([ \t]*\\)|[^|]*|" row)))
  2248. (replace-match "\\1|" t nil row))
  2249. (t row)))
  2250. rows))
  2251. "\n")))
  2252. ;;;; For Tables Of Contents
  2253. ;; `org-export-collect-headlines' builds a list of all exportable
  2254. ;; headline elements, maybe limited to a certain depth. One can then
  2255. ;; easily parse it and transcode it.
  2256. ;; Building lists of tables, figures or listings is quite similar.
  2257. ;; Once the generic function `org-export-collect-elements' is defined,
  2258. ;; `org-export-collect-tables', `org-export-collect-figures' and
  2259. ;; `org-export-collect-listings' can be derived from it.
  2260. (defun org-export-collect-headlines (info &optional n)
  2261. "Collect headlines in order to build a table of contents.
  2262. When non-nil, optional argument N must be an integer. It
  2263. specifies the depth of the table of contents.
  2264. Return a list of all exportable headlines as parsed elements."
  2265. (org-element-map
  2266. (plist-get info :parse-tree)
  2267. 'headline
  2268. (lambda (headline local)
  2269. ;; Strip contents from HEADLINE.
  2270. (let ((relative-level (org-export-get-relative-level headline local)))
  2271. (unless (and n (> relative-level n)) headline)))
  2272. info))
  2273. (defun org-export-collect-elements (type backend info)
  2274. "Collect named elements of type TYPE.
  2275. Only elements with a caption or a name are collected.
  2276. BACKEND is the back-end used to transcode their caption or name.
  2277. INFO is a plist holding export options.
  2278. Return an alist where key is entry's name and value an unique
  2279. identifier that might be used for internal links."
  2280. (org-element-map
  2281. (plist-get info :parse-tree)
  2282. type
  2283. (lambda (element info)
  2284. (let ((entry
  2285. (cond
  2286. ((org-element-get-property :caption element)
  2287. (org-export-secondary-string
  2288. (org-element-get-property :caption element) backend info))
  2289. ((org-element-get-property :name element)
  2290. (org-export-secondary-string
  2291. (org-element-get-property :name element) backend info)))))
  2292. ;; Skip elements with neither a caption nor a name.
  2293. (when entry (cons entry (org-element-get-property :begin element)))))
  2294. info))
  2295. (defun org-export-collect-tables (backend info)
  2296. "Build a list of tables.
  2297. BACKEND is the back-end used to transcode table's name. INFO is
  2298. a plist holding export options.
  2299. Return an alist where key is the caption of the table and value
  2300. an unique identifier that might be used for internal links."
  2301. (org-export-collect-elements 'table backend info))
  2302. (defun org-export-collect-figures (backend info)
  2303. "Build a list of figures.
  2304. A figure is a paragraph type element with a caption or a name.
  2305. BACKEND is the back-end used to transcode headline's name. INFO
  2306. is a plist holding export options.
  2307. Return an alist where key is the caption of the figure and value
  2308. an unique indentifier that might be used for internal links."
  2309. (org-export-collect-elements 'paragraph backend info))
  2310. (defun org-export-collect-listings (backend info)
  2311. "Build a list of src blocks.
  2312. BACKEND is the back-end used to transcode src block's name. INFO
  2313. is a plist holding export options.
  2314. Return an alist where key is the caption of the src block and
  2315. value an unique indentifier that might be used for internal
  2316. links."
  2317. (org-export-collect-elements 'src-block backend info))
  2318. (provide 'org-export)
  2319. ;;; org-export.el ends here