~bzg/worg

614cb66616b8cd13b764d987633465b9ecef6c85 — Ihor Radchenko 17 days ago e5deaca
Improve description of Org document, elements, and objects

* org-syntax.org (General structure of Org document): Move to separate
top-level heading.
(General structure of elements): Move under element and object
headings, reword, providing examples that make use of token convention.
1 files changed, 120 insertions(+), 98 deletions(-)

M org-syntax.org
M org-syntax.org => org-syntax.org +120 -98
@@ 76,104 76,6 @@ contain greater elements or lesser elements. Sections contain both
greater and lesser elements, and headings can contain a section and
other headings.

** General structure of Org document

Any Org document is represented by a sequence of elements, that can
recursively contain other elements and/or objects.

An example document below can be represented as recursive syntax tree:

#+begin_example
,#+title: An example Org document

The document begins with optional zeroth section (everything before
the first heading), followed by a sequence of headings.


    :note:
    Zeroth section can contain other elements - keyword, paragraph,
    and drawer in this example.

    The drawer, in turn, contains the previous and this paragraph; and
    this paragraph consists of mostly plain-text objects, and a single
    *bold markup*.
    :end:

,* Heading

Contains an optional section that is, similar to zeroth section,
followed by other subheadings.

,** Sub-heading 1 with no section and children headings
,** Sub-heading 2
... has a section, but not child subheadings.

,* Another heading
#+end_example

: (org-data ...
:  (zeroth-section ...
:   (keyword ...)
:   (paragraph ...)
:   (drawer
:    (paragraph ...)
:    (pragraph (plain-text) (bold (plain-text)))))
:  (heading
:   (section (paragraph ...))
:   (heading)
:   (heading (section ...)))
:  (heading))

** General structure of elements

The most general representation of an Org syntax element is a sequence
of markup defining the element itself, its contents, and the [[#Blanks][blank
lines]] after.

#+begin_example
<opening markup, belongs to the element itself>
<contents containing recursive child elements/objects>
<closing markup, belongs to the element itself>
<blank lines after, belongs to the element itself>
#+end_example

Not every Org element contains all the above components.  An example
below demonstrates structure of some common Org elements, marking the
parts corresponding to the above structure.

#+begin_example
,* Heading title is a part of the headline element itself <opening markup>


Text inside heading is considered a part of its contents and can
contain other elements recursively.  This paragraph only has
<contents>, no <opening markup>, no <closing markup>, and a <blank
line>.

:drawer:
The same works at the deeper levels, with this drawer having =:drawer:=
line as <opening markup>, this paragraph belonging to drawer
<contents>, =:end:= representing <closing markup>, and no <blank lines>
after.
:end:
#+begin_comment
A comment is taken verbatim, with this text not parsed recursively and
considered a part of the comment block element itself.
=#+begin_commend= is an <opening markup>, =#+end_comment= - closing
markup, and <contents> is absent.
#+end_comment
This is the end of the heading, no <closing markup> exists for
headings.
#+end_example

Org syntax objects have a similar structure, except blank lines being
replaced by trailing spaces:

#+begin_example
This *bold markup*      also includes the subsequent trailing spaces into
the bold object.
#+end_example

** Blank lines
:PROPERTIES:
:CUSTOM_ID: Blanks


@@ 338,10 240,113 @@ Elisp programs utilizing the syntax may directly refer to the Elisp
variable values.  Other users of this syntax reference can use to the
default values we provide here.

* General structure of Org document

Any Org document is represented by a sequence of [[#Elements][elements]], that can
recursively contain other [[#Elements][elements]] and/or [[#Objects][objects]].

An example document below can be represented as recursive syntax tree:

#+begin_example
,#+title: An example Org document (this line is a keyword)

The document begins with optional zeroth section (everything before
the first heading), followed by a sequence of headings. (paragraph)


    :note:
    Zeroth section can contain other elements - keyword, paragraph,
    and drawer in this example.

    The drawer, in turn, contains the previous and this paragraph; and
    this paragraph consists of plain text objects, and a single *bold
    markup*.
    :end:

,* Heading

Contains an optional section that is, similar to zeroth section,
followed by other subheadings.

,** Sub-heading 1 with no section and no child headings
,** Sub-heading 2
... has a section, but not child subheadings.

,* Another heading
#+end_example

: (org-data ...
:  (zeroth-section ...
:   (keyword ...)
:   (paragraph ...)
:   (drawer
:    (paragraph ...)
:    (pragraph (plain-text) (bold (plain-text)))))
:  (heading
:   (section (paragraph ...))
:   (heading)
:   (heading (section ...)))
:  (heading))

* Elements
:PROPERTIES:
:CUSTOM_ID: Elements
:END:

The most general representation of an Org syntax element is a sequence
of markup defining the element itself, its contents, and the [[#Blanks][blank
lines]] after.

#+begin_example
BEGIN
CONTENTS
END
BLANK
#+end_example

or

#+begin_example
BEGIN
VALUE
END
BLANK
#+end_example


+ BEGIN :: Opening markup, belong to the element.
+ CONTENTS :: Element contents - a sequence of child elements/objects.
+ VALUE :: Element value, taken verbatim, when no child
  elements/objects are allowed.
+ END :: Closing markup, belong to the element.
+ BLANK :: Blank lines after, belongs to the element.

Not every Org element contains all the above components.  An example
below demonstrates structure of some common Org elements, marking the
parts corresponding to the above structure.

#+begin_example
,* Heading title is a part of the headline element itself <BEGIN>


Text inside heading is considered a part of its CONTENTS and can
contain other elements recursively.  This paragraph only has CONTENTS,
no BEGIN, no END, and a BLANK line.

:drawer:
The same works at the deeper levels, with this drawer having
=:drawer:= line as BEGIN, this paragraph belonging to drawer CONTENTS,
=:end:= representing END, and no BLANK after.
:end:
#+begin_comment
A comment is taken verbatim, with this text not parsed recursively and
considered a part of the comment block element itself.
=#+begin_commend= is BEGIN, =#+end_comment= - END, and VALUE is this
text.
#+end_comment
This is the end of the heading, no END exists for headings.
#+end_example

** Headings and Sections
:PROPERTIES:
:CUSTOM_ID: Headings_and_Sections


@@ 1173,6 1178,14 @@ Objects can only be found in the following elements:
- [[#Table_Rows][table rows]], which can only contain table cell objects,
- [[#Blocks][verse blocks]].

Org syntax objects have a similar structure to [[#Elements][elements]], except blank
lines being replaced by trailing spaces:

#+begin_example
BEGIN CONTENTS END BLANK
BEGIN VALUE END BLANK
#+end_example

Most objects cannot contain objects.  Those which can will be
specified.  Furthermore, while many objects may contain newlines, a
blank line often terminates the element that the object is a part of,


@@ 1181,6 1194,15 @@ such as a paragraph.
Trailing spaces at the end of objects are considered a part of those
objects.

#+begin_example
This *bold markup*      also includes the subsequent trailing spaces into
the bold object.

*This is not a bold markup

because the previous blank line separates the containing paragraph*.
#+end_example

** Entities
:PROPERTIES:
:CUSTOM_ID: Entities