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