From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp11.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id 0KKmIsDCPmP8ngAAbAwnHQ (envelope-from ) for ; Thu, 06 Oct 2022 13:57:52 +0200 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp11.migadu.com with LMTPS id wBW3IsDCPmP8CQEA9RJhRA (envelope-from ) for ; Thu, 06 Oct 2022 13:57:52 +0200 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 1436F2D4A7 for ; Thu, 6 Oct 2022 13:57:52 +0200 (CEST) Received: from localhost ([::1]:49768 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ogPVe-0008Gb-VS for larch@yhetil.org; Thu, 06 Oct 2022 07:57:50 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:57240) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ogP9Y-0002Az-Pj for emacs-orgmode@gnu.org; Thu, 06 Oct 2022 07:35:07 -0400 Received: from mail-pg1-x52a.google.com ([2607:f8b0:4864:20::52a]:37683) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1ogP9W-0000NX-NB for emacs-orgmode@gnu.org; Thu, 06 Oct 2022 07:35:00 -0400 Received: by mail-pg1-x52a.google.com with SMTP id bh13so1657067pgb.4 for ; Thu, 06 Oct 2022 04:34:58 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=mime-version:message-id:date:references:in-reply-to:subject:cc:to :from:from:to:cc:subject:date; bh=v6NXwXg5uKWeH4U/hh8Frm9rpMIICI2CfN8La2L8hv4=; b=U+WA03C2xvZw6cfXRkLI28Y8eNxsS6wHG108YFjiHKr+rW9gO9swD7dR+cZaAB8Uhc EaVBug0QCgD+y5MjAuvhtj6xBkQvL4Z3NeP7nfW48Es03O+oe/HddHLJaJu6hrvsdiIQ RZ4UxdGjTW62Yi1cflVKxjQ59XVidObyBe689i5j1liXWYHK24+f2N+PR6cgdCrztTwj JI3d4qPCl0jjGIxXN4z+TMSwrMA/e+GHAOqtF48O4MjJxuRYXA8J3Z0tF4GibDVxWZL/ k/qILZbg7C1U6ON7g64zu4q4HS82QTDcS7Atr8Uy2Ety7bgpVPBs5RQ4YjCL7mK7lIKL IATA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=mime-version:message-id:date:references:in-reply-to:subject:cc:to :from:x-gm-message-state:from:to:cc:subject:date; bh=v6NXwXg5uKWeH4U/hh8Frm9rpMIICI2CfN8La2L8hv4=; b=xCPG3rAmVE1P6Pz3kl0So5BMdR+rvJFhzMHhPzsHN9GmXWIiUD4BqHniAiwiy0MeG6 9IpaYoxSmNL6gwo9KZD1FWZG9LRZsTAR0dREKbQb1E2Hhphkdr9R94rGCjcKbmY+oVrQ 64CRKYxFOwG/L7on8RtngBc5I9WSNWno1WbZm3qh9YJc58lFf88bsBq6CFrXawx44TaZ Wc8VitTYVCXC2DUGYw5FW6EcOw4ylxq5GFmU+CzFIKhALbSmWmy/voIcGCuimD+YI2zO w8vqlntIQKeRHS/C2H3TV7srBDwfAQKxhx1KBkpSXFTzlSe1uZVLNrZMXVfqBa1Apqa3 cITA== X-Gm-Message-State: ACrzQf1u/rdmLwDFq7OgIVEdOqri+ASEJQOGMWRpg/4GG0JWzoqW2Q5K N0OuvnlVyMnNN88+Hz3T9LU= X-Google-Smtp-Source: AMsMyM5UpeuC/l30mBGhKLnlJT+MG2XP6xkWiZiZm1CbH1b6p0Y6ZDu5sOJtVki/lMqTvhGb9875JQ== X-Received: by 2002:a63:2cd2:0:b0:41c:5901:67d8 with SMTP id s201-20020a632cd2000000b0041c590167d8mr4159460pgs.365.1665056097014; Thu, 06 Oct 2022 04:34:57 -0700 (PDT) Received: from localhost ([117.136.87.189]) by smtp.gmail.com with ESMTPSA id ik13-20020a170902ab0d00b0017f7e0f4a4esm3080724plb.35.2022.10.06.04.34.54 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Oct 2022 04:34:56 -0700 (PDT) From: Ihor Radchenko To: Marco Wahl Cc: Ignacio Casso , 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/)]) In-Reply-To: <874k57c7i4.fsf@gmail.com> References: <874k57c7i4.fsf@gmail.com> Date: Thu, 06 Oct 2022 19:35:27 +0800 Message-ID: <87fsg1422o.fsf@localhost> MIME-Version: 1.0 Content-Type: text/plain Received-SPF: pass client-ip=2607:f8b0:4864:20::52a; envelope-from=yantar92@gmail.com; helo=mail-pg1-x52a.google.com X-Spam_score_int: -17 X-Spam_score: -1.8 X-Spam_bar: - X-Spam_report: (-1.8 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_ENVFROM_END_DIGIT=0.25, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: "Emacs-orgmode" X-Migadu-Flow: FLOW_IN X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1665057472; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=v6NXwXg5uKWeH4U/hh8Frm9rpMIICI2CfN8La2L8hv4=; b=L8PlE7iFInDinhQWNpiwitqQFv+dqCdpEhBN2mbupltIT4jPhjbCVcEBL6u35Z1PaKXoH5 by7DjVNBJsnMV0JtSAKvTKU9p72W004sbhBswTmw8NREKlAwk3Km08KWrdAFc0VuEBvQdc p/K19fNNDyBhdp+TpKtCmG1mEWskObHz/EGhwRX3EzlRGPIMKDkRNeyYFZN4F5grYevAgv tffT7F0mdZ0XJRje+EK3WnLG7V0Hbz002zgazGBP4t1hHXghBDcvj1VwfBWYnxTDmJOrck vzqtNyaoM2KhHlXhPHR8dyQCnLAVOQVwAa5fI6QoOB6mGR3N1z2OWHS9hWcHqA== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1665057472; a=rsa-sha256; cv=none; b=Wc9W98nBUsCLa1N9NRG1MkVfN/21UgJUk/ndT3oNN+vTKXL0DGX9nNSSFGZDjOsf730r5M j+FWjw/RoDPwaYviEOIcCVZJQ+ZuqnquvFOiwWM2HzC3QFl9svXfLd74GXV9DekKAtK64u OCuvrH1po6T940h5CdLQeAOUInBeznZQ7CpzTNdFOVMRoKe0NBbwy4QW9WmWUMxR0NgFLR 6/cWStYxx0hRTElNMMh94IUwrqbg0lcBcNaKsvvfHBsEVaFBadFDXdmO+ELxcV7eyM+4G6 gf6BP5B2pR1eRx/oJ9zbfIB3x3U/eL/f8m4p0rgLBU/jguqtHV1NHbL4oQcO5A== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=U+WA03C2; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org" X-Migadu-Spam-Score: -3.67 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=U+WA03C2; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org" X-Migadu-Queue-Id: 1436F2D4A7 X-Spam-Score: -3.67 X-Migadu-Scanner: scn0.migadu.com X-TUID: 7mKm/IhSvNxW Marco Wahl writes: > Ignacio Casso 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 . Support Org development at , or support my work at