Re: [HELP] Fwd: Org format as a new standard source format for GNU manuals

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

> It seems I completely failed trying to express my idea.
>
> Instead of extending Org grammar (syntax), I suggest to change behavior 
> of source blocks during export. In addition to current :results options, 
> "ast" may be added. Its effect is that instead of adding text to export 
> buffer that is parsed as Org markup, it causes insertion of a branch of 
> syntax tree into original parse results. I admit, during export it may 
> be necessary to iterate over source blocks one more time at a later stage.

So, do I understand it correctly that you are _not_ suggesting the AST
format _instead_ of the discussed inline blocks?

> Such source blocks should return "Org Syntax Tree", a simplified variant 
> of org-element. It allows to change implementation details and e.g. to 
> use vectors instead of lists for attributes in org-element. A converter 
> from Org Syntax Tree to org-element should be implemented.

Doesn't it effectively mean that we need to introduce yet another Org
element syntax---"Simplified AST"?

> Certainly such format may be used directly as src_ost{(code (:class var) 
> "language")} inline snippets or as
>
> #+begin_src ost
>    (code nil ("libtree-{sitter}-"
>               (code (:class var) "\"language\"")
>               "."
>               (code (:class var) "ext")))
> #+end_src
>
> block-level elements. However I expect that it is the last resort option 
> when there is no way to express desired construct in some other way.

I can foresee issues when we insert, say, code object in place of
paragraph element. The consequences might be drastic. Unless we just
allow users to shoot their own leg.

> I think, more convenient org-babel backends may be created to parse 
> TeX-like (texinfo-like) or SGML-like (XML-like) syntax into Org Syntax 
> Tree hierarchy. The essential idea is that outside of source blocks 
> usual lightweight markup is used. Source blocks however have just a few 
> special characters ([\{}], [@{}], or [&<>], etc.) to reduce issues with 
> escaping for regular text or verbatim-like commands.

This is not a bad idea, but I feel like it is getting a bit too far from
the syntax discussion herein. You might open a new thread about
importing foreign syntax into Org.

>>>       (code nil ("libtree-{sitter}-"
>>>                  (code (:class var) "\"language\"")
>>>                  "."
>>>                  (code (:class var) "ext")))
>> 
>> This is not much different from @name[nil]{<contents>} idea, but
>> more verbose.
>>
>  > Also, more importantly, I strongly dislike the need to wrap the text
>  > into "". You will have to escape \". And it will force third-party
>  > parsers to re-implement Elisp sexp reader.
>
> By this example I was trying to show how to express @var, @samp, @file 
> without introducing of new custom objects. I do not see any problem with 
> verbosity of such format, it may be used for really special cases only, 
> while some more convenient markup is used for more simple cases.

I was comparing the inline block vs. your AST proposal. If the AST idea
is complementary, I see no issue.

>>> If there was some syntax for object attributes then simple cases would
>>> be like
>>>
>>>       [[attr:(:class var)]]~language~
>> 
>> I do not like this idea. It will require non-trivial changes in Org
>> parser and fontification.
>> 
>> Using dedicated object properties or at least inheriting properties from
>> :parent is the style we employ more commonly across the code:
>> 
>> @var{language}
>> or
>> @code[:class var]{language}
>> or
>> @attr[:class var]{~language~}
>
> I do not mind to have some "span" object to assign attributes to its 
> direct children. I used link-like prefix object just because a proof of 
> concept may be tried with no changes in Org. It does not require support 
> of nested objects. There is no existing syntax for such "span" objects, 
> but perhaps it is not necessary and source blocks should be used instead 
> for special needs.

The problem is that instead of supporting nested objects we will have to
support "previous object changing the meaning of subsequent", which is
more fundamental change.

I envision the new inline blocks to allow assigning attributes to
children. These new inline blocks must not have issues with nesting by
design.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
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>