diff --git a/EXPERIMENTAL/org-e-latex.el b/EXPERIMENTAL/org-e-latex.el index a4727c734..0b649a1ad 100644 --- a/EXPERIMENTAL/org-e-latex.el +++ b/EXPERIMENTAL/org-e-latex.el @@ -232,10 +232,12 @@ The function result will be used in the section format string. As an example, one could set the variable to the following, in order to reproduce the default set-up: -\(defun org-e-latex-format-headline-default \(todo todo-type priority text tags\) +\(defun org-e-latex-format-headline \(todo todo-type priority text tags\) \"Default format function for an headline.\" - \(concat \(when todo \(format \"\\\\textbf{\\\\textsc{\\\\textsf{%s}}} \" todo\)\) - \(when priority \(format \"\\\\framebox{\\\\#%c} \" priority\)\) + \(concat \(when todo + \(format \"\\\\textbf{\\\\textsc{\\\\textsf{%s}}} \" todo\)\) + \(when priority + \(format \"\\\\framebox{\\\\#%c} \" priority\)\) text \(when tags \(format \"\\\\hfill{}\\\\textsc{%s}\" tags\)\)\)\)" :group 'org-export-e-latex @@ -379,11 +381,12 @@ The function should return the string to be exported. For example, the variable could be set to the following function in order to mimic default behaviour: -\(defun org-e-latex-format-inlinetask-default \(todo type priority name tags contents\) +\(defun org-e-latex-format-inlinetask \(todo type priority name tags contents\) \"Format an inline task element for LaTeX export.\" \(let \(\(full-title \(concat - \(when todo \(format \"\\\\textbf{\\\\textsf{\\\\textsc{%s}}} \" todo\)\) + \(when todo + \(format \"\\\\textbf{\\\\textsf{\\\\textsc{%s}}} \" todo\)\) \(when priority \(format \"\\\\framebox{\\\\#%c} \" priority\)\) title \(when tags \(format \"\\\\hfill{}\\\\textsc{%s}\" tags\)\)\)\)\) @@ -463,9 +466,9 @@ hurt if it is present." "Association list of options for the latex listings package. These options are supplied as a comma-separated list to the -\\lstset command. Each element of the association list should be +\\lstset command. Each element of the association list should be a list containing two strings: the name of the option, and the -value. For example, +value. For example, (setq org-e-latex-listings-options '((\"basicstyle\" \"\\small\") @@ -509,9 +512,9 @@ pygmentize -L lexers" "Association list of options for the latex minted package. These options are supplied within square brackets in -\\begin{minted} environments. Each element of the alist should be -a list containing two strings: the name of the option, and the -value. For example, +\\begin{minted} environments. Each element of the alist should +be a list containing two strings: the name of the option, and the +value. For example, (setq org-e-latex-minted-options '((\"bgcolor\" \"bg\") (\"frame\" \"lines\"))) @@ -529,12 +532,13 @@ options will be applied to blocks of all languages." (string :tag "Minted option value")))) (defvar org-e-latex-custom-lang-environments nil - "Association list mapping languages to language-specific latex -environments used during export of src blocks by the listings and -minted latex packages. For example, + "Alist mapping languages to language-specific LaTeX environments. - (setq org-e-latex-custom-lang-environments - '((python \"pythoncode\"))) +It is used during export of src blocks by the listings and minted +latex packages. For example, + + \(setq org-e-latex-custom-lang-environments + '\(\(python \"pythoncode\"\)\)\) would have the effect that if org encounters begin_src python during latex export it will output @@ -644,7 +648,7 @@ These are the .aux, .log, .out, and .toc files." "Return caption and label LaTeX string for floats. CAPTION is a secondary string \(a list of strings and Org -objects\) and LABEL a string representing the label. INFO is +objects\) and LABEL a string representing the label. INFO is a plist holding contextual information. If there's no caption nor label, return the empty string. @@ -705,7 +709,9 @@ nil." ",")) (defun org-e-latex--quotation-marks (text info) - "Export quotation marks depending on language conventions." + "Export quotation marks depending on language conventions. +TEXT is a string containing quotation marks to be replaced. INFO +is a plist used as a communication channel." (mapc (lambda(l) (let ((start 0)) (while (setq start (string-match (car l) text start)) @@ -718,7 +724,7 @@ nil." (defun org-e-latex--wrap-label (element output) "Wrap label associated to ELEMENT around OUTPUT, if appropriate. -This function shouldn't be used for floats. See +This function shouldn't be used for floats. See `org-e-latex--caption/label-string'." (let ((label (org-element-get-property :name element))) (if (or (not output) (not label) (string= output "") (string= label "")) @@ -731,7 +737,7 @@ This function shouldn't be used for floats. See (defun org-e-latex-template (contents info) "Return complete document string after LaTeX conversion. -CONTENTS is the transcoded contents string. INFO is a plist +CONTENTS is the transcoded contents string. INFO is a plist holding export options." (let ((title (org-export-secondary-string (plist-get info :title) 'e-latex info))) @@ -937,7 +943,7 @@ CONTENTS is nil. INFO is a plist holding contextual information." (defun org-e-latex-footnote-reference (footnote-reference contents info) "Transcode a FOOTNOTE-REFERENCE element from Org to LaTeX. -CONTENTS is nil. INFO is a plist holding contextual information." +CONTENTS is nil. INFO is a plist holding contextual information." (concat ;; Insert separator between two footnotes in a row. (let ((prev (org-export-get-previous-element footnote-reference info))) @@ -1305,7 +1311,7 @@ INFO is a plist containing export options." "Transcode a LINK object from Org to LaTeX. DESC is the description part of the link, or the empty string. -INFO is a plist holding contextual information. See +INFO is a plist holding contextual information. See `org-export-data'." (let* ((type (org-element-get-property :type link)) (raw-path (org-element-get-property :path link)) @@ -1701,7 +1707,7 @@ The format string one placeholder for the body of the table." (defun org-e-latex-table--align-string (attr info) "Return an appropriate LaTeX alignment string. - +ATTR is a string containing table's LaTeX specific attributes. INFO is the plist containing format info about the table, as returned by `org-export-table-format-info'." (or (and attr @@ -1829,7 +1835,8 @@ contextual information." (defun org-e-latex-time-stamp (time-stamp contents info) "Transcode a TIME-STAMP object from Org to LaTeX. -CONTENTS is nil. INFO is a plist holding contextual information." +CONTENTS is nil. INFO is a plist holding contextual +information." (let ((value (org-element-get-property :value time-stamp)) (type (org-element-get-property :type time-stamp)) (appt-type (org-element-get-property :appt-type time-stamp))) @@ -1849,11 +1856,13 @@ CONTENTS is nil. INFO is a plist holding contextual information." ;;;; Verbatim -(defun org-e-latex-verbatim (element contents info) - "Return verbatim text in LaTeX." - (let ((fmt (cdr (assoc (org-element-get-property :marker element) +(defun org-e-latex-verbatim (verbatim contents info) + "Transcode a VERBATIM object from Org to LaTeX. +CONTENTS is nil. INFO is a plist used as a communication +channel." + (let ((fmt (cdr (assoc (org-element-get-property :marker verbatim) org-e-latex-emphasis-alist))) - (value (org-element-get-property :value element))) + (value (org-element-get-property :value verbatim))) (cond ;; Handle the `verb' special case. ((eq 'verb fmt) @@ -1887,7 +1896,7 @@ CONTENTS is nil. INFO is a plist holding contextual information." (defun org-e-latex-verse-block (verse-block contents info) "Transcode a VERSE-BLOCK element from Org to LaTeX. -CONTENTS is nil. INFO is a plist holding contextual information." +CONTENTS is nil. INFO is a plist holding contextual information." (org-e-latex--wrap-label verse-block ;; In a verse environment, add a line break to each newline diff --git a/contrib/lisp/org-element.el b/contrib/lisp/org-element.el index ec8626220..128cd6a63 100644 --- a/contrib/lisp/org-element.el +++ b/contrib/lisp/org-element.el @@ -647,6 +647,9 @@ CONTENTS is the contents of the element." (defun org-element-plain-list-parser (&optional structure) "Parse a plain list. +Optional argument STRUCTURE, when non-nil, is the structure of +the plain list being parsed. + Return a list whose car is `plain-list' and cdr is a plist containing `:type', `:begin', `:end', `:contents-begin' and `:contents-end', `:level', `:structure' and `:post-blank' @@ -1498,7 +1501,7 @@ CONTENTS is nil." ;; org-element-NAME-successor, where NAME is the name of the ;; successor, as defined in `org-element-all-successors'. -;; Some object types (i.e `emphasis') are recursive. Restrictions on +;; Some object types (i.e. `emphasis') are recursive. Restrictions on ;; object types they can contain will be specified in ;; `org-element-object-restrictions'. @@ -1542,7 +1545,7 @@ CONTENTS is the contents of the object." (concat marker contents marker))) (defun org-element-text-markup-successor (limit) - "Search for the next emphasis or verbatim and return position. + "Search for the next emphasis or verbatim object. LIMIT bounds the search. @@ -1718,8 +1721,7 @@ CONTENTS is nil." (format "[%s]" (concat label def)))) (defun org-element-footnote-reference-successor (limit) - "Search for the next footnote-reference and return beginning - position. + "Search for the next footnote-reference object. LIMIT bounds the search. @@ -1768,8 +1770,7 @@ CONTENTS is nil." (and post-options (format "[%s]" post-options))))) (defun org-element-inline-babel-call-successor (limit) - "Search for the next inline-babel-call and return beginning - position. + "Search for the next inline-babel-call object. LIMIT bounds the search. @@ -1824,7 +1825,7 @@ CONTENTS is nil." body))) (defun org-element-inline-src-block-successor (limit) - "Search for the next inline-babel-call and return beginning position. + "Search for the next inline-babel-call element. LIMIT bounds the search. @@ -1894,7 +1895,7 @@ CONTENTS is nil." "\\\\\n") (defun org-element-line-break-successor (limit) - "Search for the next statistics cookie and return position. + "Search for the next line-break object. LIMIT bounds the search. @@ -2000,7 +2001,7 @@ CONTENTS is the contents of the object." (if (string= contents "") "" (format "[%s]" contents))))))) (defun org-element-link-successor (limit) - "Search for the next link and return position. + "Search for the next link object. LIMIT bounds the search. @@ -2058,7 +2059,7 @@ CONTENTS is nil." (org-element-get-property :value macro)) (defun org-element-macro-successor (limit) - "Search for the next macro and return position. + "Search for the next macro object. LIMIT bounds the search. @@ -2104,7 +2105,7 @@ CONTENTS is the contents of the object." (concat "<<<" contents ">>>")) (defun org-element-radio-target-successor (limit) - "Search for the next radio-target and return position. + "Search for the next radio-target object. LIMIT bounds the search. @@ -2144,7 +2145,7 @@ CONTENTS is nil." (org-element-get-property :value statistics-cookie)) (defun org-element-statistics-cookie-successor (limit) - "Search for the next statistics cookie and return position. + "Search for the next statistics cookie object. LIMIT bounds the search. @@ -2193,8 +2194,7 @@ CONTENTS is the contents of the object." contents)) (defun org-element-sub/superscript-successor (limit) - "Search for the next sub/superscript and return beginning -position. + "Search for the next sub/superscript object. LIMIT bounds the search. @@ -2277,7 +2277,7 @@ CONTENTS is the contents of target." (concat "")) (defun org-element-target-successor (limit) - "Search for the next target and return position. + "Search for the next target object. LIMIT bounds the search. @@ -2345,7 +2345,7 @@ CONTENTS is nil." (org-element-get-property :value time-stamp))) (defun org-element-time-stamp-successor (limit) - "Search for the next time-stamp and return position. + "Search for the next time-stamp object. LIMIT bounds the search. @@ -3084,7 +3084,7 @@ Nil values returned from FUN are ignored in the result." (defun org-element-parse-elements (beg end special structure granularity visible-only acc) - "Parse ELEMENT with point at its beginning. + "Parse elements between BEG and END positions. SPECIAL prioritize some elements over the others. It can set to either `section' or `item', which will focus search, diff --git a/contrib/lisp/org-export.el b/contrib/lisp/org-export.el index dce1c1174..55166c233 100644 --- a/contrib/lisp/org-export.el +++ b/contrib/lisp/org-export.el @@ -909,7 +909,9 @@ Return options as a plist." (defun org-export-get-inbuffer-options (buffer-string backend files) "Return in-buffer options as a plist. BUFFER-STRING is the string of the buffer. BACKEND is a symbol -specifying which back-end should be used." +specifying which back-end should be used. FILES is a list of +setup files names read so far, used to avoid circular +dependencies." (let ((case-fold-search t) plist) ;; 1. Special keywords, as in `org-export-special-keywords'. (let ((start 0) @@ -1104,7 +1106,7 @@ Following tree properties are set: `:back-end' Back-end used for transcoding. `:headline-offset' Offset between true level of headlines and - local level. An offset of -1 means an headline + local level. An offset of -1 means an headline of level 2 should be considered as a level 1 headline in the context. @@ -2070,6 +2072,8 @@ INFO is a plist holding contextual information." (defun org-export-low-level-p (headline info) "Non-nil when HEADLINE is considered as low level. +INFO is a plist used as a communication channel. + A low level headlines has a relative level greater than `:headline-levels' property value. @@ -2183,9 +2187,9 @@ lines, include only those lines." (defun org-export-parse-included-file (keyword info) "Parse file specified by include KEYWORD. -KEYWORD is the include keyword element transcoded. BACKEND is the -language back-end used for transcoding. INFO is the plist used as -a communication channel. +KEYWORD is the include keyword element transcoded. BACKEND is +the language back-end used for transcoding. INFO is the plist +used as a communication channel. Return the parsed tree." (let* ((value (org-element-get-property :value keyword)) @@ -2245,7 +2249,7 @@ Return the parsed tree." ;; when the element isn't numbered. (defun org-export-solidify-link-text (s) - "Take link text and make a safe target out of it." + "Take link text S and make a safe target out of it." (save-match-data (mapconcat 'identity (org-split-string s "[^a-zA-Z0-9_\\.-]+") "-"))) @@ -2263,7 +2267,7 @@ PATH is the link path. DESC is its description." When non-nil, optional argument EXTENSIONS is a list of valid extensions for image files, as strings. Otherwise, a default -list is provided \(cf. `org-image-file-name-regexp'\)." +list is provided \(cf `org-image-file-name-regexp'\)." (and (not (org-element-get-contents link)) (string= (org-element-get-property :type link) "file") (org-file-image-p @@ -2674,6 +2678,8 @@ it also." (defun org-export-collect-headlines (info &optional n) "Collect headlines in order to build a table of contents. +INFO is a plist used as a communication channel. + When non-nil, optional argument N must be an integer. It specifies the depth of the table of contents. @@ -2750,7 +2756,8 @@ links." ;;;; Topology (defun org-export-get-parent-headline (blob info) - "Return BLOB's closest parent headline or nil." + "Return BLOB's closest parent headline or nil. +INFO is a plist used as a communication channel." (catch 'exit (mapc (lambda (el) (when (eq (car el) 'headline) (throw 'exit el)))