Fix some docstrings

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.
+
+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\")))
+  \(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

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,

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)))