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

[Ihor Radchenko]

"Rick Lupton" <rclsub@fastmail.com> writes:

> I wonder if you have seen Pollen’s approach to this? 
> https://docs.racket-lang.org/pollen/pollen-command-syntax.html

Thanks for the interesting reference!
After skimming through the syntax described in the link, I feel like
most of the features are already present in Org syntax or being
discussed here.

> There are two separate ideas used there which seemed related to this 
> discussion. I’m not sure if they are useful in the org context.  
>
> 1. The use of a special character (◊ by default) which introduces a 
> command/inline special block. I don’t know if this would be worth considering 
> as an alternative to @ (which also seems reasonable) to avoid ambiguity with 
> other syntax. As the link above discusses it’s harder to type but there are 
> solutions. 

I do understand the idea behind ◊, but it is the design decision we
would need to make before creating Org syntax. At this point, we are not
going to change the Org syntax concepts just for having the nice
feature. There is no point to solve the escaping problem just for a
single new Org syntax element and not changing the rest of the syntax. 

So, I'd prefer to keep "@" or other symbol we already use in the
existing Org elements/objects.

For escaping @ inside, we already have zero-width, an alternative idea
with special \-- entity, and we can introduce \atsymbol entity that
exports and displays as "@".

> 2. Making it easy to define custom functions that produce org syntax. A bit 
> like perhaps Max's suggestion to use source blocks, but instead of writing 
> AST-like structure directly in the document where you want it, you can call a 
> previously defined function to build it. This is similar to org macros but 
> I’m not sure if they are so flexible as a lisp function. There is also the 
> option to choose between passing arguments as lisp (in [ ]) or as markup (in 
> { })

We already have named code blocks to call arbitrary code in arbitrary
programming language and produce arbitrary results, including Org
markup. On export. I do not think that we should allow runtime markup
calculations on-the-fly due to performance reasons.

Also, Org macros do allow arbitrary elisp:

       As a special case, Org parses any replacement text starting with
    ‘(eval’ as an Emacs Lisp expression and evaluates it accordingly.
    Within such templates, arguments become strings.  Thus, the following
    macro


         #+MACRO: gnustamp (eval (concat "GNU/" (capitalize $1)))
    
    turns ‘{{{gnustamp(linux)}}}’ into ‘GNU/Linux’ during export.

Max's idea about AST structure is just an extra fallback to produce
really tricky cases. And since it is going to be an src block result,
all the features for src blocks will apply, including calling arbitrary
code (not just Elisp). I do not see this idea as being a part of normal
usage, just really weird border cases. (At least, it is my
understanding. Max may chime in with more clarifications).

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