discovering export (and other) keywords?

discovering export (and other) keywords?

[kevinbanjo]

[-- Attachment #1: Type: text/plain, Size: 560 bytes --]

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?

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?

TIA,
-Kevin

[-- Attachment #2: Type: text/html, Size: 884 bytes --]

Re: discovering export (and other) keywords?

[Alain.Cochard]

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.

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


-- 
EOST (École et Observatoire des Sciences de la Terre) 
ITE (Institut Terre & Environnement) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 106]  | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France     | [ slot available for rent ]

Re: discovering export (and other) keywords?

[Ihor Radchenko]

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

Re: discovering export (and other) keywords?

[Max Nikulin]

On 18/07/2022 19:10, kevinbanjo wrote:
> 
> 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?

For source blocks you may try `org-babel-view-src-block-info' (C-c C-v 
I, C-c C-v TAB).

org-contrib has org-eldoc.el that displays values of some header 
arguments when cursor is on a #+begin_src line. The code uses
     (nth 2 (org-babel-get-src-block-info 'light))

Re: discovering export (and other) keywords?

[Michael Eliachevitch]

[-- Attachment #1: Type: text/plain, Size: 1324 bytes --]

Hello,

On 2022-07-20 at 23:02 +07, Max Nikulin <manikulin@gmail.com> wrote:
> On 18/07/2022 19:10, kevinbanjo wrote:
>> 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?
>
> For source blocks you may try `org-babel-view-src-block-info' (C-c C-v I, C-c
> C-v TAB).


For source blocks I found the  company-org-block [1] package helpful to get auto-completion candidates for code-block keywords.

Recently I moved away from using company and just use completion-at-point-functions with corfu [2] for selecting the completion candidate. Luckily, the "cape" package of the same developer has an experimental company-adapter [3] to convert company backends to completion-at-point functions and this seemeed to work well for me with company-org-block.

I just wonder if it wouldn't be better to have a package providing completion-at-point-functions for that from the start and if this couldn't be provided by org.

Cheers, Michael


[1]: https://github.com/xenodium/company-org-block
[2]: https://github.com/minad/corfu
[3]: https://github.com/minad/cape#company-adapter

--
Michael Eliachevitch
Public PGP Key: https://keyoxide.org/hkp/546908c782383ad0e7d894ec1b8f95c8125dce31

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 519 bytes --]