nett00n <[email protected]> writes: > 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.
There is a slight difference. PARAMETERS in greater blocks usually take a form of :keyword value. While DATA typically uses format like <lang-name> :keyword value ... > 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. If you feel strongly about this, I do not mind changing the wording. -- Ihor Radchenko // yantar92, Org mode maintainer, Learn more about Org mode at <https://orgmode.org/>. Support Org development at <https://liberapay.com/org-mode>, or support my work at <https://liberapay.com/yantar92>
