org-export.el 111 KB

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