Marco Wahl <marcowahls...@gmail.com> writes: > Ignacio Casso <ignacioca...@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>
