mirror of
https://git.savannah.gnu.org/git/emacs/org-mode.git
synced 2024-08-27 20:02:52 +00:00
org-element: Small modifications to comments
This commit is contained in:
parent
e4c2540b68
commit
b7dbf357c3
|
@ -21,14 +21,14 @@
|
|||
;; along with this program. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
;;; 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.
|
||||
|
||||
|
|
Loading…
Reference in a new issue