org-cite-insert function docstring and documentation don't tell how to validate

org-cite-insert function docstring and documentation don't tell how to validate

[Sébastien Gendre]

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

Hello,


I am trying to use the Org-mode citation system, as described in the
documentation: https://orgmode.org/manual/Citation-handling.html

For inserting a citation, I call interactively the function
org-cite-insert, as described in the documentation:
https://orgmode.org/manual/Citations.html

But when I select a citation in the mini-buffer and validate with "enter",
the citation key is added in the mini-buffer and Org-mode continue to
ask me what I want to cite. I cannot end it and actually have a citation
link inside my documentation.

I have seen if a special keyboard shortcut is needed after selecting a
key to cite, but neither in the documentation or the function docstring
I found it.

Any idea ?

Version of Org-mode:   9.7.2
Version of Emacs:      29.4


Best regards

-------
Gendre Sébastien

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

Re: org-cite-insert function docstring and documentation don't tell how to validate

[András Simonyi]

Dear All,

On Sun, 21 Jul 2024 at 12:15, Sébastien Gendre <seb@k-7.ch> wrote:

> I have seen if a special keyboard shortcut is needed after selecting a
> key to cite, but neither in the documentation or the function docstring
> I found it.
> Any idea ?

I think it depends on the used completion system, but one of the
non-obvious shortcuts for this
that I've seen was "C-u C-j" (e.g., for Ivy), perhaps it's worth a try.

best wishes,
András

Re: org-cite-insert function docstring and documentation don't tell how to validate

[Sébastien Gendre]

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


I have found that on Vanilla Emacs, it's "C-j".

And with Vertico, it's "Alt-Enter".

I wonder if we need to document it. In the docstring of
"org-cite-insert" and in the documentation. Of course, not mentioning
every possible shortcut. But at least telling how the command
"org-cite-insert" behave. And the general idea of how user can stop the
reference selection.


András Simonyi <andras.simonyi@gmail.com> writes:

> Dear All,
>
> On Sun, 21 Jul 2024 at 12:15, Sébastien Gendre <seb@k-7.ch> wrote:
>
>> I have seen if a special keyboard shortcut is needed after selecting a
>> key to cite, but neither in the documentation or the function docstring
>> I found it.
>> Any idea ?
>
> I think it depends on the used completion system, but one of the
> non-obvious shortcuts for this
> that I've seen was "C-u C-j" (e.g., for Ivy), perhaps it's worth a try.
>
> best wishes,
> András

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

Re: org-cite-insert function docstring and documentation don't tell how to validate

[Ihor Radchenko]

Sébastien Gendre <seb@k-7.ch> writes:

> I have found that on Vanilla Emacs, it's "C-j".
>
> And with Vertico, it's "Alt-Enter".
>
> I wonder if we need to document it. In the docstring of
> "org-cite-insert" and in the documentation. Of course, not mentioning
> every possible shortcut. But at least telling how the command
> "org-cite-insert" behave. And the general idea of how user can stop the
> reference selection.

The minibuffer prompt in `org-cite-insert' says: "empty input exits"
IMHO, it is more than enough. In fact, better than shelving it deep into
the manual/docstring.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: org-cite-insert function docstring and documentation don't tell how to validate

[Sébastien Gendre]

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


What does "empty input exists" mean ?

Ihor Radchenko <yantar92@posteo.net> writes:

> Sébastien Gendre <seb@k-7.ch> writes:
>
>> I have found that on Vanilla Emacs, it's "C-j".
>>
>> And with Vertico, it's "Alt-Enter".
>>
>> I wonder if we need to document it. In the docstring of
>> "org-cite-insert" and in the documentation. Of course, not mentioning
>> every possible shortcut. But at least telling how the command
>> "org-cite-insert" behave. And the general idea of how user can stop the
>> reference selection.
>
> The minibuffer prompt in `org-cite-insert' says: "empty input exits"
> IMHO, it is more than enough. In fact, better than shelving it deep into
> the manual/docstring.

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

Re: org-cite-insert function docstring and documentation don't tell how to validate

[Ihor Radchenko]

Sébastien Gendre <seb@k-7.ch> writes:

> What does "empty input exists" mean ?

Empty minibuffer input.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: org-cite-insert function docstring and documentation don't tell how to validate

[Sébastien Gendre]

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


You mean that the mini-buffer is empty ?



Ihor Radchenko <yantar92@posteo.net> writes:

> Sébastien Gendre <seb@k-7.ch> writes:
>
>> What does "empty input exists" mean ?
>
> Empty minibuffer input.

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

Re: org-cite-insert function docstring and documentation don't tell how to validate

[Ihor Radchenko]

Sébastien Gendre <seb@k-7.ch> writes:

> You mean that the mini-buffer is empty ?

I mean that what you type in the minibuffer is empty.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: org-cite-insert function docstring and documentation don't tell how to validate

[Sébastien Gendre]

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


What do you mean ?

Ihor Radchenko <yantar92@posteo.net> writes:

> Sébastien Gendre <seb@k-7.ch> writes:
>
>> You mean that the mini-buffer is empty ?
>
> I mean that what you type in the minibuffer is empty.

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

Re: org-cite-insert function docstring and documentation don't tell how to validate

[Ihor Radchenko]

Sébastien Gendre <seb@k-7.ch> writes:

> What do you mean ?

When a prompt is displayed in Emacs, you enter something in the minibuffer.
You can type some text there (with completion) or you can type nothing.
If you type nothing, your input is empty.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: org-cite-insert function docstring and documentation don't tell how to validate

[Sébastien Gendre]

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


Yes, but how this information tell me that I have to do a special key
binding to validate my citation selection and to have the
citation link inserted into my org-mode document ?



Ihor Radchenko <yantar92@posteo.net> writes:

> Sébastien Gendre <seb@k-7.ch> writes:
>
>> What do you mean ?
>
> When a prompt is displayed in Emacs, you enter something in the minibuffer.
> You can type some text there (with completion) or you can type nothing.
> If you type nothing, your input is empty.

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

Re: org-cite-insert function docstring and documentation don't tell how to validate

[Ihor Radchenko]

Sébastien Gendre <seb@k-7.ch> writes:

> Yes, but how this information tell me that I have to do a special key
> binding to validate my citation selection and to have the
> citation link inserted into my org-mode document ?

It does not. It is completely up to the completion flavor you are using.
By default, pressing <RET> in the minibuffer when you do not enter
anything will send empty input. But third-party completion packages
sometimes change it. You need to know the completion package you are using.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: org-cite-insert function docstring and documentation don't tell how to validate

[Christian Moe]

Sébastien Gendre writes:

> What does "empty input exists" mean ?

I think this conversation took a wrong turn where Sebastian read "exits"
as "exists". :-)

That is, choose a cite, hit RET to insert it, then hit RET again to exit
the loop.

Yours,
Christian