Ihor Radchenko <yanta...@posteo.net> writes:
> Just as many others, this page hasn't been updated for a while.
> Maybe we should auto-generate it (it is created by transforming
> org-element.el file commentary and defuns). Or maybe drop it.
Some thoughts out loud:
It intersperses docstrings and commentary. Possibly the commentary also
needs updating here and there?
The alternative of dropping the commentary, or the whole page, depends
how it fits in with the other pages on related topics: Org syntax, the
Org element API, the Org export reference documentation, and possibly
others. As a non-developer, I don't have a clear picture.
But I'd assume it usefully complements the other documents and is not
superseded or made redundant by them, since Nicolas kept them updated
concurrently for years.
Structurally, they're a bit scattered:
worg
|_org-syntax.org
|_dev
| |_org-element-api.org
| |_org-export-reference.org
|_exporters
|_org-element-docstrings.org
If org-element-docstrings is worth keeping, it might be worth making it
more discoverable. It currently isn't linked to from exporters/index.org
(nor from dev/index.org).
It *is* linked to from exporters/ox-overview.org, which was written to
mark the new export framework in release 8.0 ... oh goodness, has it
been 12 years already?! If we decide not to keep it updated, it should
probably be preserved for historical value.
Yours,
Christian
