From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.devel Subject: RE: docstrings and elisp reference Date: Wed, 7 Jun 2017 07:18:47 -0700 (PDT) Message-ID: References: <0BB64F35-233A-471F-B99F-51F96C4E6CCB@gmail.com> <8360g99n07.fsf@gnu.org> <86lgp4q2xa.fsf@stephe-leake.org> <878tl4976i.fsf@fastmail.fm> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1496845185 27767 195.159.176.226 (7 Jun 2017 14:19:45 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Wed, 7 Jun 2017 14:19:45 +0000 (UTC) To: Stefan Monnier , emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Jun 07 16:19:32 2017 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dIbo3-0006XM-5c for ged-emacs-devel@m.gmane.org; Wed, 07 Jun 2017 16:19:31 +0200 Original-Received: from localhost ([::1]:44278 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dIbo8-0007Jy-F4 for ged-emacs-devel@m.gmane.org; Wed, 07 Jun 2017 10:19:36 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:47394) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dIbnV-0007Jq-4S for emacs-devel@gnu.org; Wed, 07 Jun 2017 10:18:58 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dIbnP-00073m-Pd for emacs-devel@gnu.org; Wed, 07 Jun 2017 10:18:57 -0400 Original-Received: from aserp1040.oracle.com ([141.146.126.69]:28737) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1dIbnP-00072E-Fj for emacs-devel@gnu.org; Wed, 07 Jun 2017 10:18:51 -0400 Original-Received: from userv0022.oracle.com (userv0022.oracle.com [156.151.31.74]) by aserp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id v57EInOd024868 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Wed, 7 Jun 2017 14:18:50 GMT Original-Received: from userv0122.oracle.com (userv0122.oracle.com [156.151.31.75]) by userv0022.oracle.com (8.14.4/8.14.4) with ESMTP id v57EInAA020182 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Wed, 7 Jun 2017 14:18:49 GMT Original-Received: from abhmp0012.oracle.com (abhmp0012.oracle.com [141.146.116.18]) by userv0122.oracle.com (8.14.4/8.14.4) with ESMTP id v57EImve019034; Wed, 7 Jun 2017 14:18:48 GMT In-Reply-To: X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 12.0.6767.5000 (x86)] X-Source-IP: userv0022.oracle.com [156.151.31.74] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] [fuzzy] X-Received-From: 141.146.126.69 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:215500 Archived-At: > - Better integration between the manual browser and the docstring > browser, so you can click on a function/variable name in the manual to > get to its docstring and you can easily jump from a docstring to the > relevant section of the manual. Yes, 100%. I've long argued that. Cross-reference, not text reuse. And Emacs has already come a fair distance in that direction. It could still be improved. > - Remove the redundant var/fun documentation from the manual (this is > a tedious job: there is some redundance but it's not systematic, so > we can't just do this removal systematically). We should not remove redundant _information_, if there is a reason that it will help readers. And that's the case for 99.9% of the var/fun presentations in the manual. There is often a discussion about whether a given var/fun should be explicitly doc'd in the manual - it's a judgment call. It's not because we _can_ add the doc for a var/fun to the manual that we should. Think redundancy NOT for maintainers (I'm not saying you did that) but for readers. A reader should be _able_ to click to go to additional info or to a different presentation/orientation of the same material. But it is important, IMO, for the manual to have the information that it has, even when that means that the same information is provided also elsewhere (e.g. in a doc string). We lose, do not gain, if we decide to remove the doc for a given function etc. from the manual just because it has a doc string - or vice versa. The question of redundancy _for the user_ means that we also do not, in general, want to have exactly the same text in doc string and manual. A user does not want to click a function name in one or the other, only to end up seeing exactly the same text in the other location. "Reuse" for readers is generally a negative - it means reading the same thing again, generally without being forewarned. Little is more frustrating for a reader. ("Why did you send me here? This is the same text!") That is not to say that repetition in doc is always negative. Far from it. It's about judgment: repeat when there is a good (e.g. pedagogical) reason to repeat. > - Come up with a way to re-add those var/fun documentation into the > printed manual (e.g. by adding to the Texinfo source external > references to docstrings, which are then processed by now ad-hoc > script). Not a good idea, IMO. See above.