From: Ihor Radchenko <yantar92@gmail.com>
To: Marco Wahl <marcowahlsoft@gmail.com>
Cc: Ignacio Casso <ignaciocasso@hotmail.com>, emacs-orgmode@gnu.org
Subject: [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/)])
Date: Thu, 06 Oct 2022 19:35:27 +0800 [thread overview]
Message-ID: <87fsg1422o.fsf@localhost> (raw)
In-Reply-To: <874k57c7i4.fsf@gmail.com>
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>
prev parent reply other threads:[~2022-10-06 11:57 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
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 ` Ihor Radchenko [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87fsg1422o.fsf@localhost \
--to=yantar92@gmail.com \
--cc=emacs-orgmode@gnu.org \
--cc=ignaciocasso@hotmail.com \
--cc=marcowahlsoft@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).