Re: [RFC] Org syntax (draft)

[Achim Gratz <Stromeko@nexgo.de>]

Hi Nicolas,

here are my first comments. I'm still trying to wrap my head around some
things, so if I'm off the map on something, please be patient.

Do you mind if I fix some obvious typos directly on Worg or do you'd
rather want patches?


Nicolas Goaziou writes:
> A core concept in this syntax is that only headlines and sections are
> context-free[1][2].  Every other syntactical part only exists within
> specific environments.

Blank lines or empty lines are also context-free syntactical elements,
I'd think.

> Three categories are used to classify these environments: “Greater
> elements”, “elements”, and “objects”, from the broadest scope to the
> narrowest.

It might be easier to talk about those things if "Greater Element" was
called "Collection" to perhaps keep with the thingies theme of naming
the syntax.

> The paragraph is the unit of measurement.  An element defines
> syntactical parts that are at the same level as a paragraph, i.e. which
> cannot contain or be included in a paragraph.  An object is a part that
> could be included in an element.  Greater elements are all parts that
> can contain an element.

Here's my main contention with that model: I think there should be an
greater element, maybe named "paragraph block" that translates into a
paragraph at the backend level.  Most backends will have a paragraph
model that is much less limited than what the current definition of an
Org paragraph is.  This could be optionally be an implicit greater
block that is defined by the presence or absence of blank lines between
elements, I'd think.

> 3.1 Greater Blocks
> ──────────────────

The same naming confusion as with the various "elements", for now I'd
link to think of these as "Box".

>   Greater blocks consist in the following pattern:
>
>   ╭────
>   │ #+BEGIN_NAME PARAMETERS
>   │ CONTENTS
>   │ #+END_NAME
>   ╰────

I'm beginning to wonder if these should have the same syntax as blocks.
Maybe that's a too fine a distinction visually, but adding a colon would
disambiguate the greater blocks from the normal ones.  In other words

#+BEGIN_CENTER: humdum
…
#+END_CENTER:

would be a center block, while

#+BEGIN_CENTER humdum
…
#+END_CENTER

would be an export block for the center backend.

> 4.2 Blocks
> ──────────
>
>   Like [greater blocks], pattern for blocks is:
>
>   ╭────
>   │ #+BEGIN_NAME DATA
>   │ CONTENTS
>   │ #+END_NAME
>   ╰────
[…]
>   DATA can contain any character but a new line.

I'd keep with PARAMETERS here.

>   If NAME is a string matching the name of any export back-end loaded,
>   the block will be an “export block”.

Conversely, blocks that are not having a recognizable name will simply
insert their content as if the block markers were not there, e.g. it
seems to treat these as parsed blocks.  I don't think this should
happen, instead Org should parse this as an unknown export backend and
drop the content with a warning, not unlike a comment.

This will be a major sticking point with external parsers: they'd
otherwise need to know about the Org export backends to when to use the
content of the block and when not.  A portable Org document should be
able to specify which export backends it expects to be available (and
maybe what standard backend it is derived from) to elicit the correct
behaviour.

>   CONTENTS can contain any character, including new lines.  Though it
>   will only contain Org objects if the block is a verse block.
>   Otherwise, contents will not be parsed.

Would it make sense to make a general distinction between parsed and
non-parsed blocks based on some configuration, even though this would
produce the same issue as with export backends?

>         I suggest to remove angle links.  If one needs spaces in
>         PATH, she can use standard link syntax instead.

They are very ubiquitous on certain platforms, so copy&paste would be
made frustrating there if you'd need to re-format them each time around.



Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

SD adaptation for Waldorf Blofeld V1.15B11:
http://Synth.Stromeko.net/Downloads.html#WaldorfSDada