Re: [RFC] Org syntax (draft)

[Nicolas Goaziou <n.goaziou@gmail.com>]

Hello,

Achim Gratz <Stromeko@nexgo.de> writes:

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

Please go ahead. This is on Worg so anyone can improve it.

> 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.

No, the aren't, as they belong to the broadest element ending before
them. So you need to know what this element is.

>> 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.

Collection could also be ambiguous as a paragraph may be seen as
a collection of objects.

>> 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.

I don't get it. What would be the exact definition of a "paragraph
block"? What limitations are you talking about?

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

This naming was for the org-syntax file only. "Greater blocks" means
nothing for org-element.el, but "center block", "quote block", "special
block" do.

>>   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.

I agree. More on that below.

>> 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.

Ok. Just fix it.

>>   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.

You are talking about "special blocks", right? They have a special
purpose. In latex back-end,

  #+begin_special
  ...
  #+end_special

becomes

  \begin{special}
  ...
  \end{special}

IOW this is an Org feature.

> 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 would remove special blocks.

> 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.

I agree, as notified above. If we want to separate Org /format/ from
Emacs, we need to separate special blocks from export blocks. The former
cannot be the fallback type when the latter isn't recognized.

In that case, a different syntax for export blocks would be needed.
Maybe the colons you suggested above. I think that something more
visible would be better, though.

>>   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?

This is inherent from the block type. This mustn't be configurable.
There is no point in parsing a src-block, for example. On the other
hand, if you don't parse (partially) contents of a verse-block, you get
an example-block, and one of them becomes useless.

Then, there are special blocks. It was suggested, a few days ago, that
a parameter could be set in order to tell the parser what to do with
their contents. That's an interesting idea. But it only makes sense if
there is also a way to specify a transformation function on these
contents (otherwise, an export block would be sufficient). Also the same
could be achieved with Babel, the non-parsed data being an example
block, and the transformation function a src-block.


Regards,

-- 
Nicolas Goaziou