Browse Source

Fix some docstrings

Nicolas Goaziou 13 years ago
parent
commit
3c4a0795df
3 changed files with 69 additions and 53 deletions
  1. 37 28
      EXPERIMENTAL/org-e-latex.el
  2. 17 17
      contrib/lisp/org-element.el
  3. 15 8
      contrib/lisp/org-export.el

+ 37 - 28
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
 As an example, one could set the variable to the following, in
 order to reproduce the default set-up:
 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.\"
   \"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
 	  text
 	  \(when tags \(format \"\\\\hfill{}\\\\textsc{%s}\" tags\)\)\)\)"
 	  \(when tags \(format \"\\\\hfill{}\\\\textsc{%s}\" tags\)\)\)\)"
   :group 'org-export-e-latex
   :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
 For example, the variable could be set to the following function
 in order to mimic default behaviour:
 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.\"
 \"Format an inline task element for LaTeX export.\"
   \(let \(\(full-title
   \(let \(\(full-title
 	 \(concat
 	 \(concat
-	  \(when todo \(format \"\\\\textbf{\\\\textsf{\\\\textsc{%s}}} \" todo\)\)
+	  \(when todo
+            \(format \"\\\\textbf{\\\\textsf{\\\\textsc{%s}}} \" todo\)\)
 	  \(when priority \(format \"\\\\framebox{\\\\#%c} \" priority\)\)
 	  \(when priority \(format \"\\\\framebox{\\\\#%c} \" priority\)\)
 	  title
 	  title
 	  \(when tags \(format \"\\\\hfill{}\\\\textsc{%s}\" tags\)\)\)\)\)
 	  \(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.
   "Association list of options for the latex listings package.
 
 
 These options are supplied as a comma-separated list to the
 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
 a list containing two strings: the name of the option, and the
-value. For example,
+value.  For example,
 
 
   (setq org-e-latex-listings-options
   (setq org-e-latex-listings-options
     '((\"basicstyle\" \"\\small\")
     '((\"basicstyle\" \"\\small\")
@@ -509,9 +512,9 @@ pygmentize -L lexers"
   "Association list of options for the latex minted package.
   "Association list of options for the latex minted package.
 
 
 These options are supplied within square brackets in
 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
   (setq org-e-latex-minted-options
     '((\"bgcolor\" \"bg\") (\"frame\" \"lines\")))
     '((\"bgcolor\" \"bg\") (\"frame\" \"lines\")))
@@ -529,12 +532,13 @@ options will be applied to blocks of all languages."
 	   (string :tag "Minted option value"))))
 	   (string :tag "Minted option value"))))
 
 
 (defvar org-e-latex-custom-lang-environments nil
 (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
 would have the effect that if org encounters begin_src python
 during latex export it will output
 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.
   "Return caption and label LaTeX string for floats.
 
 
 CAPTION is a secondary string \(a list of strings and Org
 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.
 a plist holding contextual information.
 
 
 If there's no caption nor label, return the empty string.
 If there's no caption nor label, return the empty string.
@@ -705,7 +709,9 @@ nil."
 	     ","))
 	     ","))
 
 
 (defun org-e-latex--quotation-marks (text info)
 (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)
   (mapc (lambda(l)
 	  (let ((start 0))
 	  (let ((start 0))
 	    (while (setq start (string-match (car l) text start))
 	    (while (setq start (string-match (car l) text start))
@@ -718,7 +724,7 @@ nil."
 
 
 (defun org-e-latex--wrap-label (element output)
 (defun org-e-latex--wrap-label (element output)
   "Wrap label associated to ELEMENT around OUTPUT, if appropriate.
   "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'."
 `org-e-latex--caption/label-string'."
   (let ((label (org-element-get-property :name element)))
   (let ((label (org-element-get-property :name element)))
     (if (or (not output) (not label) (string= output "") (string= label ""))
     (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)
 (defun org-e-latex-template (contents info)
   "Return complete document string after LaTeX conversion.
   "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."
 holding export options."
   (let ((title (org-export-secondary-string
   (let ((title (org-export-secondary-string
 		(plist-get info :title) 'e-latex info)))
 		(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)
 (defun org-e-latex-footnote-reference (footnote-reference contents info)
   "Transcode a FOOTNOTE-REFERENCE element from Org to LaTeX.
   "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
   (concat
    ;; Insert separator between two footnotes in a row.
    ;; Insert separator between two footnotes in a row.
    (let ((prev (org-export-get-previous-element footnote-reference info)))
    (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.
   "Transcode a LINK object from Org to LaTeX.
 
 
 DESC is the description part of the link, or the empty string.
 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'."
 `org-export-data'."
   (let* ((type (org-element-get-property :type link))
   (let* ((type (org-element-get-property :type link))
 	 (raw-path (org-element-get-property :path 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)
 (defun org-e-latex-table--align-string (attr info)
   "Return an appropriate LaTeX alignment string.
   "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
 INFO is the plist containing format info about the table, as
 returned by `org-export-table-format-info'."
 returned by `org-export-table-format-info'."
   (or (and attr
   (or (and attr
@@ -1829,7 +1835,8 @@ contextual information."
 
 
 (defun org-e-latex-time-stamp (time-stamp contents info)
 (defun org-e-latex-time-stamp (time-stamp contents info)
   "Transcode a TIME-STAMP object from Org to LaTeX.
   "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))
   (let ((value (org-element-get-property :value time-stamp))
 	(type (org-element-get-property :type time-stamp))
 	(type (org-element-get-property :type time-stamp))
 	(appt-type (org-element-get-property :appt-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
 ;;;; 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)))
 			 org-e-latex-emphasis-alist)))
-	(value (org-element-get-property :value element)))
+	(value (org-element-get-property :value verbatim)))
     (cond
     (cond
      ;; Handle the `verb' special case.
      ;; Handle the `verb' special case.
      ((eq 'verb fmt)
      ((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)
 (defun org-e-latex-verse-block (verse-block contents info)
   "Transcode a VERSE-BLOCK element from Org to LaTeX.
   "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
   (org-e-latex--wrap-label
    verse-block
    verse-block
    ;; In a verse environment, add a line break to each newline
    ;; In a verse environment, add a line break to each newline

+ 17 - 17
contrib/lisp/org-element.el

@@ -647,6 +647,9 @@ CONTENTS is the contents of the element."
 (defun org-element-plain-list-parser (&optional structure)
 (defun org-element-plain-list-parser (&optional structure)
   "Parse a plain list.
   "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
 Return a list whose car is `plain-list' and cdr is a plist
 containing `:type', `:begin', `:end', `:contents-begin' and
 containing `:type', `:begin', `:end', `:contents-begin' and
 `:contents-end', `:level', `:structure' and `:post-blank'
 `: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
 ;; org-element-NAME-successor, where NAME is the name of the
 ;; successor, as defined in `org-element-all-successors'.
 ;; 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
 ;; object types they can contain will be specified in
 ;; `org-element-object-restrictions'.
 ;; `org-element-object-restrictions'.
 
 
@@ -1542,7 +1545,7 @@ CONTENTS is the contents of the object."
     (concat marker contents marker)))
     (concat marker contents marker)))
 
 
 (defun org-element-text-markup-successor (limit)
 (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.
 LIMIT bounds the search.
 
 
@@ -1718,8 +1721,7 @@ CONTENTS is nil."
     (format "[%s]" (concat label def))))
     (format "[%s]" (concat label def))))
 
 
 (defun org-element-footnote-reference-successor (limit)
 (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.
 LIMIT bounds the search.
 
 
@@ -1768,8 +1770,7 @@ CONTENTS is nil."
 	    (and post-options (format "[%s]" post-options)))))
 	    (and post-options (format "[%s]" post-options)))))
 
 
 (defun org-element-inline-babel-call-successor (limit)
 (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.
 LIMIT bounds the search.
 
 
@@ -1824,7 +1825,7 @@ CONTENTS is nil."
 	    body)))
 	    body)))
 
 
 (defun org-element-inline-src-block-successor (limit)
 (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.
 LIMIT bounds the search.
 
 
@@ -1894,7 +1895,7 @@ CONTENTS is nil."
   "\\\\\n")
   "\\\\\n")
 
 
 (defun org-element-line-break-successor (limit)
 (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.
 LIMIT bounds the search.
 
 
@@ -2000,7 +2001,7 @@ CONTENTS is the contents of the object."
 		(if (string= contents "") "" (format "[%s]" contents)))))))
 		(if (string= contents "") "" (format "[%s]" contents)))))))
 
 
 (defun org-element-link-successor (limit)
 (defun org-element-link-successor (limit)
-  "Search for the next link and return position.
+  "Search for the next link object.
 
 
 LIMIT bounds the search.
 LIMIT bounds the search.
 
 
@@ -2058,7 +2059,7 @@ CONTENTS is nil."
   (org-element-get-property :value macro))
   (org-element-get-property :value macro))
 
 
 (defun org-element-macro-successor (limit)
 (defun org-element-macro-successor (limit)
-  "Search for the next macro and return position.
+  "Search for the next macro object.
 
 
 LIMIT bounds the search.
 LIMIT bounds the search.
 
 
@@ -2104,7 +2105,7 @@ CONTENTS is the contents of the object."
   (concat "<<<" contents ">>>"))
   (concat "<<<" contents ">>>"))
 
 
 (defun org-element-radio-target-successor (limit)
 (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.
 LIMIT bounds the search.
 
 
@@ -2144,7 +2145,7 @@ CONTENTS is nil."
   (org-element-get-property :value statistics-cookie))
   (org-element-get-property :value statistics-cookie))
 
 
 (defun org-element-statistics-cookie-successor (limit)
 (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.
 LIMIT bounds the search.
 
 
@@ -2193,8 +2194,7 @@ CONTENTS is the contents of the object."
    contents))
    contents))
 
 
 (defun org-element-sub/superscript-successor  (limit)
 (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.
 LIMIT bounds the search.
 
 
@@ -2277,7 +2277,7 @@ CONTENTS is the contents of target."
   (concat ""))
   (concat ""))
 
 
 (defun org-element-target-successor (limit)
 (defun org-element-target-successor (limit)
-  "Search for the next target and return position.
+  "Search for the next target object.
 
 
 LIMIT bounds the search.
 LIMIT bounds the search.
 
 
@@ -2345,7 +2345,7 @@ CONTENTS is nil."
    (org-element-get-property :value time-stamp)))
    (org-element-get-property :value time-stamp)))
 
 
 (defun org-element-time-stamp-successor (limit)
 (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.
 LIMIT bounds the search.
 
 
@@ -3084,7 +3084,7 @@ Nil values returned from FUN are ignored in the result."
 
 
 (defun org-element-parse-elements
 (defun org-element-parse-elements
   (beg end special structure granularity visible-only acc)
   (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
 SPECIAL prioritize some elements over the others.  It can set to
 either `section' or `item', which will focus search,
 either `section' or `item', which will focus search,

+ 15 - 8
contrib/lisp/org-export.el

@@ -909,7 +909,9 @@ Return options as a plist."
 (defun org-export-get-inbuffer-options (buffer-string backend files)
 (defun org-export-get-inbuffer-options (buffer-string backend files)
   "Return in-buffer options as a plist.
   "Return in-buffer options as a plist.
 BUFFER-STRING is the string of the buffer.  BACKEND is a symbol
 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)
   (let ((case-fold-search t) plist)
     ;; 1. Special keywords, as in `org-export-special-keywords'.
     ;; 1. Special keywords, as in `org-export-special-keywords'.
     (let ((start 0)
     (let ((start 0)
@@ -1104,7 +1106,7 @@ Following tree properties are set:
 `:back-end'        Back-end used for transcoding.
 `:back-end'        Back-end used for transcoding.
 
 
 `:headline-offset' Offset between true level of headlines and
 `: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
 		   of level 2 should be considered as a level
 		   1 headline in the context.
 		   1 headline in the context.
 
 
@@ -2070,6 +2072,8 @@ INFO is a plist holding contextual information."
 (defun org-export-low-level-p (headline info)
 (defun org-export-low-level-p (headline info)
   "Non-nil when HEADLINE is considered as low level.
   "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
 A low level headlines has a relative level greater than
 `:headline-levels' property value.
 `:headline-levels' property value.
 
 
@@ -2183,9 +2187,9 @@ lines, include only those lines."
 (defun org-export-parse-included-file (keyword info)
 (defun org-export-parse-included-file (keyword info)
   "Parse file specified by include KEYWORD.
   "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."
 Return the parsed tree."
   (let* ((value (org-element-get-property :value keyword))
   (let* ((value (org-element-get-property :value keyword))
@@ -2245,7 +2249,7 @@ Return the parsed tree."
 ;; when the element isn't numbered.
 ;; when the element isn't numbered.
 
 
 (defun org-export-solidify-link-text (s)
 (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
   (save-match-data
     (mapconcat 'identity (org-split-string s "[^a-zA-Z0-9_\\.-]+") "-")))
     (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
 When non-nil, optional argument EXTENSIONS is a list of valid
 extensions for image files, as strings.  Otherwise, a default
 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))
   (and (not (org-element-get-contents link))
        (string= (org-element-get-property :type link) "file")
        (string= (org-element-get-property :type link) "file")
        (org-file-image-p
        (org-file-image-p
@@ -2674,6 +2678,8 @@ it also."
 (defun org-export-collect-headlines (info &optional n)
 (defun org-export-collect-headlines (info &optional n)
   "Collect headlines in order to build a table of contents.
   "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
 When non-nil, optional argument N must be an integer.  It
 specifies the depth of the table of contents.
 specifies the depth of the table of contents.
 
 
@@ -2750,7 +2756,8 @@ links."
 ;;;; Topology
 ;;;; Topology
 
 
 (defun org-export-get-parent-headline (blob info)
 (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
   (catch 'exit
     (mapc
     (mapc
      (lambda (el) (when (eq (car el) 'headline) (throw 'exit el)))
      (lambda (el) (when (eq (car el) 'headline) (throw 'exit el)))