Re: discovering export (and other) keywords?

[Ihor Radchenko <yantar92@gmail.com>]

Alain.Cochard@unistra.fr writes:

> kevinbanjo writes on Mon 18 Jul 2022 05:10:
>  > this page:
>  > 
>  > https://orgmode.org/manual/Macro-Replacement.html#index-macro-replacement_002c-during-export
>  > 
>  > says:
>  > 
>  > Org also recognizes macro references in keywords, such as ‘CAPTION’, ‘TITLE’,
>  > ‘AUTHOR’, ‘DATE’, *and for some back-end specific export options.*
>  > 
>  > How do I discover what those back end specific options are?
>
> I am guessing it would be difficult to maintain a list of these
> options.  On the other hand it should be quick for you to check for a
> specific one.

We actually do. For example, "Beamer specific export settings" section
of the manual lists all the settings for ox-beamer. If something is
missing from the manual, let us know, and we will fix it.

Meanwhile, I think that we can clarify what "some back-end specific
export options" refer to:

Org also recognizes macro references in keywords, such as ‘CAPTION’,
‘TITLE’, ‘AUTHOR’, ‘DATE’, and for some back-end specific export
options (detailed in the relevant sections of the manual).

Will it be more clear?

Another possibility could be changing the format of options alist when
defining export backend. We may allow an optional (but recommended)
docstring field to be provided when defining a backend and its options.
Such docstring can then be used in hypothetical
org-export-describe-backend command that will generate something similar
to M-x describe-mode documentation. This new command cal also be added
to the export menu for easy access. WDYT?

>  > Also, for various elements (e.g. begin_src emacs-lisp, begin_export html,
>  > etc...) how do I discover what the acceptable keywords are, preferably
>  > without only having to go thru the manual pages?
>
> I don't think you can avoid going through the manual.  My experience
> is that it is painful anyway.  I would advise you to start from the
> few examples provided in the manual and try to adapt to your case;
> when an (as simple as possible) example does not work as you would
> expect, ask the list; there is a good chance that a good Samaritan
> will have pity for you and answer.

Because keywords may be specific to a backend and there are also
third-party backends, we cannot easily provide such information
on-the-fly - Org has no idea about the intended export backend when you
type in an Org document; not to mentioned that there may be multiple
intended backends.

Best,
Ihor