From b7dbf357c3ef3496ef9f7972c2b849a794582dab Mon Sep 17 00:00:00 2001 From: Nicolas Goaziou Date: Sat, 5 May 2012 17:15:18 +0200 Subject: [PATCH] org-element: Small modifications to comments --- contrib/lisp/org-element.el | 78 ++++++++++++++++++------------------- 1 file changed, 39 insertions(+), 39 deletions(-) diff --git a/contrib/lisp/org-element.el b/contrib/lisp/org-element.el index fd69fa2c2..120c6a784 100644 --- a/contrib/lisp/org-element.el +++ b/contrib/lisp/org-element.el @@ -21,14 +21,14 @@ ;; along with this program. If not, see . ;;; Commentary: - +;; ;; Org syntax can be divided into three categories: "Greater ;; elements", "Elements" and "Objects". - +;; ;; Elements are related to the structure of the document. Indeed, all ;; elements are a cover for the document: each position within belongs ;; to at least one element. - +;; ;; An element always starts and ends at the beginning of a line. With ;; a few exceptions (namely `babel-call', `clock', `headline', `item', ;; `keyword', `planning', `property-drawer' and `section' types), it @@ -71,7 +71,7 @@ ;; elements and elements containing objects will also have ;; `:contents-begin' and `:contents-end' properties to delimit ;; contents. - +;; ;; Lisp-wise, an element or an object can be represented as a list. ;; It follows the pattern (TYPE PROPERTIES CONTENTS), where: ;; TYPE is a symbol describing the Org element or object. @@ -80,27 +80,27 @@ ;; list. ;; CONTENTS is a list of elements, objects or raw strings contained ;; in the current element or object, when applicable. - +;; ;; An Org buffer is a nested list of such elements and objects, whose ;; type is `org-data' and properties is nil. - +;; ;; The first part of this file implements a parser and an interpreter ;; for each type of Org syntax. - +;; ;; The next two parts introduce four accessors and a function ;; retrieving the element starting at point (respectively ;; `org-element-type', `org-element-property', `org-element-contents', ;; `org-element-restriction' and `org-element-current-element'). - +;; ;; The following part creates a fully recursive buffer parser. It ;; also provides a tool to map a function to elements or objects ;; matching some criteria in the parse tree. Functions of interest ;; are `org-element-parse-buffer', `org-element-map' and, to a lesser ;; extent, `org-element-parse-secondary-string'. - +;; ;; The penultimate part is the cradle of an interpreter for the ;; obtained parse tree: `org-element-interpret-data'. - +;; ;; The library ends by furnishing a set of interactive tools for ;; element's navigation and manipulation, mostly based on ;; `org-element-at-point' function. @@ -114,10 +114,10 @@ ;;; Greater elements - +;; ;; For each greater element type, we define a parser and an ;; interpreter. - +;; ;; A parser returns the element or object as the list described above. ;; Most of them accepts no argument. Though, exceptions exist. Hence ;; every element containing a secondary string (see @@ -125,22 +125,22 @@ ;; argument to toggle parsing of that secondary string. Moreover, ;; `item' parser requires current list's structure as its first ;; element. - +;; ;; An interpreter accepts two arguments: the list representation of ;; the element or object, and its contents. The latter may be nil, ;; depending on the element or object considered. It returns the ;; appropriate Org syntax, as a string. - +;; ;; Parsing functions must follow the naming convention: ;; org-element-TYPE-parser, where TYPE is greater element's type, as ;; defined in `org-element-greater-elements'. ;; ;; Similarly, interpreting functions must follow the naming ;; convention: org-element-TYPE-interpreter. - +;; ;; With the exception of `headline' and `item' types, greater elements ;; cannot contain other greater elements of their own type. - +;; ;; Beside implementing a parser and an interpreter, adding a new ;; greater element requires to tweak `org-element-current-element'. ;; Moreover, the newly defined type must be added to both @@ -858,15 +858,15 @@ CONTENTS is the contents of the element." ;;; Elements - +;; ;; For each element, a parser and an interpreter are also defined. ;; Both follow the same naming convention used for greater elements. - +;; ;; Also, as for greater elements, adding a new element type is done ;; through the following steps: implement a parser and an interpreter, ;; tweak `org-element-current-element' so that it recognizes the new ;; type and add that new type to `org-element-all-elements'. - +;; ;; As a special case, when the newly defined type is a block type, ;; `org-element-block-name-alist' has to be modified accordingly. @@ -2765,11 +2765,11 @@ CONTENTS is nil." ;;; Definitions And Rules - +;; ;; Define elements, greater elements and specify recursive objects, ;; along with the affiliated keywords recognized. Also set up ;; restrictions on recursive objects combinations. - +;; ;; These variables really act as a control center for the parsing ;; process. (defconst org-element-paragraph-separate @@ -3126,28 +3126,28 @@ element it has to parse." ;; element beginning, we want to move before them, as they belong to ;; that element, and, in the meantime, collect information they give ;; into appropriate properties. Hence the following function. - +;; ;; Usage of optional arguments may not be obvious at first glance: - +;; ;; - TRANS-LIST is used to polish keywords names that have evolved ;; during Org history. In example, even though =result= and ;; =results= coexist, we want to have them under the same =result= ;; property. It's also true for "srcname" and "name", where the ;; latter seems to be preferred nowadays (thus the "name" property). - +;; ;; - CONSED allows to regroup multi-lines keywords under the same ;; property, while preserving their own identity. This is mostly ;; used for "attr_latex" and al. - +;; ;; - PARSED prepares a keyword value for export. This is useful for ;; "caption". Objects restrictions for such keywords are defined in ;; `org-element-object-restrictions'. - +;; ;; - DUALS is used to take care of keywords accepting a main and an ;; optional secondary values. For example "results" has its ;; source's name as the main value, and may have an hash string in ;; optional square brackets as the secondary one. - +;; ;; A keyword may belong to more than one category. (defconst org-element--affiliated-re @@ -3167,8 +3167,8 @@ match group 2. Don't modify it, set `org-element-affiliated-keywords' instead.") -(defun org-element-collect-affiliated-keywords (&optional key-re trans-list - consed parsed duals) +(defun org-element-collect-affiliated-keywords + (&optional key-re trans-list consed parsed duals) "Collect affiliated keywords before point. Optional argument KEY-RE is a regexp matching keywords, which @@ -3246,13 +3246,13 @@ cdr a plist of keywords and values." ;;; The Org Parser - +;; ;; The two major functions here are `org-element-parse-buffer', which ;; parses Org syntax inside the current buffer, taking into account ;; region, narrowing, or even visibility if specified, and ;; `org-element-parse-secondary-string', which parses objects within ;; a given string. - +;; ;; The (almost) almighty `org-element-map' allows to apply a function ;; on elements or objects matching some type, and accumulate the ;; resulting values. In an export situation, it also skips unneeded @@ -3384,15 +3384,15 @@ Nil values returned from FUN do not appear in the results." (nreverse --acc)))) ;; The following functions are internal parts of the parser. - +;; ;; The first one, `org-element-parse-elements' acts at the element's ;; level. - +;; ;; The second one, `org-element-parse-objects' applies on all objects ;; of a paragraph or a secondary string. It uses ;; `org-element-get-candidates' to optimize the search of the next ;; object in the buffer. - +;; ;; More precisely, that function looks for every allowed object type ;; first. Then, it discards failed searches, keeps further matches, ;; and searches again types matched behind point, for subsequent @@ -3571,7 +3571,7 @@ OBJECTS is the previous candidates alist." ;;; Towards A Bijective Process - +;; ;; The parse tree obtained with `org-element-parse-buffer' is really ;; a snapshot of the corresponding Org buffer. Therefore, it can be ;; interpreted and expanded into a string with canonical Org syntax. @@ -3783,7 +3783,7 @@ indentation is not done with TAB characters." ;;; The Toolbox - +;; ;; The first move is to implement a way to obtain the smallest element ;; containing point. This is the job of `org-element-at-point'. It ;; basically jumps back to the beginning of section containing point @@ -3871,17 +3871,17 @@ first element of current section." ;; to implement some replacements for `forward-paragraph' ;; `backward-paragraph', namely `org-element-forward' and ;; `org-element-backward'. - +;; ;; Also, `org-transpose-elements' mimics the behaviour of ;; `transpose-words', at the element's level, whereas ;; `org-element-drag-forward', `org-element-drag-backward', and ;; `org-element-up' generalize, respectively, functions ;; `org-subtree-down', `org-subtree-up' and `outline-up-heading'. - +;; ;; `org-element-unindent-buffer' will, as its name almost suggests, ;; smartly remove global indentation from buffer, making it possible ;; to use Org indent mode on a file created with hard indentation. - +;; ;; `org-element-nested-p' and `org-element-swap-A-B' are used ;; internally by some of the previously cited tools.