While implementing a parser from the Org syntax reference
(https://orgmode.org/worg/org-syntax.html), I noticed that the optional
text following NAME on a "#+begin_NAME" line is given two different
names in two sections, even though it occupies the same syntactic
position with the same definition.
Section 4.2.1 (Greater Blocks):
#+begin_NAME PARAMETERS
CONTENTS
#+end_NAME
PARAMETERS (optional)
A string consisting of any characters other than a newline.
Section 4.3.1 (Blocks):
#+begin_NAME DATA
CONTENTS
#+end_NAME
DATA (optional)
A string consisting of any characters but a newline.
Same position (the remainder of the "#+begin_" line after NAME), same
definition -- only the label differs: PARAMETERS versus DATA.
This is confusing when implementing from the spec, since it suggests the
two block families have different header grammars when they do not.
Notably, the existing implementations have already converged on a single
name, and it is not "DATA":
* org-element.el (reference): special-block uses :parameters;
src-block decomposes the header into :language + :switches +
:parameters. The term "data" is not used.
* orgize (Rust): the src header text is the SRC_BLOCK_PARAMETERS
token.
* uniorg (TypeScript): SrcBlock exposes language / switches /
parameters.
So the de-facto resolution is "PARAMETERS"; "DATA" appears in none of
them.
Suggested fix: in 4.3.1, rename "DATA" to "PARAMETERS" so the two
sections agree. If the intent of 4.3.1 was to describe the
further-decomposed forms (export = a single word; src = "LANGUAGE
SWITCHES ARGUMENTS"), it may help to say explicitly that these are
refinements of the same PARAMETERS slot from 4.2.1.
Please CC me, I am not subscribed
--
___
Pet your pets and best regards,
Vladimir @nett00n Budylnikov
