Hi All,

I’ve talked about adding citation syntax to the org-syntax document before, and
previously expressed the thought that it could be generally improved quite a
bit. This has culminated me in spending the last few days straight working on a
rewrite of org-syntax.org to try to bring it closer to the point where we can
knock “(draft)” out of the title 🙂.

Ihor has been a tremendous help pointing out inaccuracies and explaining some of
the parsing behaviour (thanks!), which has allowed me to get it to a point where
I think it would benefit from wider feedback.

I’ve just pushed my latest revision to worg as
<https://orgmode.org/worg/dev/org-syntax-edited.html>. Personally though, I think
it’s best viewed as a PDF, so I’ve also uploaded the PDF export to
<https://0x0.st/oiM5.pdf>.

It would be great if those of you with an interest/understanding of Org’s syntax
could have a look and let me know what you think. I think the best way to
compare to the current org-syntax.org would be to put them side-by-side. I’ve
attempted to list the main changes I’ve made in the appendix, however I’ve
likely missed things.

Lastly, having spent a while looking at the syntax, I’m wondering if we should
take this opportunity to mark some of the syntactic elements we’ve become less
happy with as *(depreciated)*. I’m specifically thinking of the TeX-style LaTeX
fragments which have been a bit of a pain. To quote Nicolas in org-syntax.org:
      It would introduce incompatibilities with previous Org versions,
      but support for `$...$' (and for symmetry, `$$...$$') constructs
      ought to be removed.

      They are slow to parse, fragile, redundant and imply false
      positives.  — ngz

Marking this as depreciated would have no effect on Org’s current behaviour, but
we could:
1. Mark as depreciated now-ish
2. Add a utility to convert from TeX-style to LaTeX-style
3. Add org lint/fortification warnings
4. A while later (half a decade? more?) actually remove support

The other component of the syntax which feels particularly awkward to me is
source block switches. They seem a bit odd, and since arguments exist,
completely redundant.

――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――

That’s all for now, I hope you all had a great Christmas and new year!

All the best,
Timothy