* [BUG] Typo in manual [9.5.2 (9.5.2-gfbff08 @ /home/ignacio/.emacs.d/elpa/org-9.5.2/)]
@ 2022-02-10 10:01 Ignacio Casso
2022-02-10 10:59 ` Marco Wahl
0 siblings, 1 reply; 3+ messages in thread
From: Ignacio Casso @ 2022-02-10 10:01 UTC (permalink / raw)
To: emacs-orgmode
Hello,
I would like to report a minor typo in the manual, although I'm not sure
if this is the right place (please point me to it if it's not).
In the section Appendix A Hacking -> Using the Mapping API
(https://orgmode.org/manual/Using-the-Mapping-API.html), it says that
org-map-entries returns an alist, but it actually returns a list (as
correctly stated by C-h f org-map-entries).
Regards,
Ignacio
Emacs : GNU Emacs 27.2 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.24.20)
of 2022-01-16
Package: Org mode version 9.5.2 (9.5.2-gfbff08 @ /home/ignacio/.emacs.d/elpa/org-9.5.2/)
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [BUG] Typo in manual [9.5.2 (9.5.2-gfbff08 @ /home/ignacio/.emacs.d/elpa/org-9.5.2/)]
2022-02-10 10:01 [BUG] Typo in manual [9.5.2 (9.5.2-gfbff08 @ /home/ignacio/.emacs.d/elpa/org-9.5.2/)] Ignacio Casso
@ 2022-02-10 10:59 ` Marco Wahl
2022-10-06 11:35 ` [HELP] Please help checking function definitions in the manual vs. docstrings (was: [BUG] Typo in manual [9.5.2 (9.5.2-gfbff08 @ /home/ignacio/.emacs.d/elpa/org-9.5.2/)]) Ihor Radchenko
0 siblings, 1 reply; 3+ messages in thread
From: Marco Wahl @ 2022-02-10 10:59 UTC (permalink / raw)
To: Ignacio Casso; +Cc: emacs-orgmode
Ignacio Casso <ignaciocasso@hotmail.com> writes:
> I would like to report a minor typo in the manual, although I'm not sure
> if this is the right place (please point me to it if it's not).
Confirmed.
And this is the right place to report this bug. Thanks!
> In the section Appendix A Hacking -> Using the Mapping API
> (https://orgmode.org/manual/Using-the-Mapping-API.html), it says that
> org-map-entries returns an alist, but it actually returns a list (as
> correctly stated by C-h f org-map-entries).
To me this looks like the documentation in the manual started from the
documentation of the function. and with time these two documentations
diverged.
What about removing the (diverged) duplication of the documentation of
function org-map-entries from the manual?
^ permalink raw reply [flat|nested] 3+ messages in thread
* [HELP] Please help checking function definitions in the manual vs. docstrings (was: [BUG] Typo in manual [9.5.2 (9.5.2-gfbff08 @ /home/ignacio/.emacs.d/elpa/org-9.5.2/)])
2022-02-10 10:59 ` Marco Wahl
@ 2022-10-06 11:35 ` Ihor Radchenko
0 siblings, 0 replies; 3+ messages in thread
From: Ihor Radchenko @ 2022-10-06 11:35 UTC (permalink / raw)
To: Marco Wahl; +Cc: Ignacio Casso, emacs-orgmode
Marco Wahl <marcowahlsoft@gmail.com> writes:
> Ignacio Casso <ignaciocasso@hotmail.com> writes:
>
>> I would like to report a minor typo in the manual, although I'm not sure
>> if this is the right place (please point me to it if it's not).
>
> Confirmed.
I fixed the exact typo on main for now.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=580f2861402ebd9c4effe0c8db5e6efdc139e79a
Fixed.
> And this is the right place to report this bug. Thanks!
>
>> In the section Appendix A Hacking -> Using the Mapping API
>> (https://orgmode.org/manual/Using-the-Mapping-API.html), it says that
>> org-map-entries returns an alist, but it actually returns a list (as
>> correctly stated by C-h f org-map-entries).
>
> To me this looks like the documentation in the manual started from the
> documentation of the function. and with time these two documentations
> diverged.
>
> What about removing the (diverged) duplication of the documentation of
> function org-map-entries from the manual?
I do not think that we should remove the function description from the
manual completely. There should be at least some description. Good
enough to get the users started.
Moreover, this function is not the only place where the outdated
docstring is used directly in the manual. Search for #+begin_defun in
the manual and try comparing manual vs. the actual docstring.
We may need to go through these function definitions and strip them out
of excessive details that might be a subject of change. Just leave the
essence about what the function does.
The above is just my suggestion though. Do note that Elisp manual is
using similar approach to the Org manual - a number of functions pretty
much have their docstrings copied from the code to the manual. And they
also do diverge...
I am not sure which way is better.
--
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>
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2022-10-06 11:57 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-02-10 10:01 [BUG] Typo in manual [9.5.2 (9.5.2-gfbff08 @ /home/ignacio/.emacs.d/elpa/org-9.5.2/)] Ignacio Casso
2022-02-10 10:59 ` Marco Wahl
2022-10-06 11:35 ` [HELP] Please help checking function definitions in the manual vs. docstrings (was: [BUG] Typo in manual [9.5.2 (9.5.2-gfbff08 @ /home/ignacio/.emacs.d/elpa/org-9.5.2/)]) Ihor Radchenko
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).