org-export.el 120 KB

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