From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.devel Subject: RE: Changes in revision 114466 Date: Mon, 30 Sep 2013 09:38:06 -0700 (PDT) Message-ID: References: < <831u49fkxk.fsf@gnu.org> <83pprse4mf.fsf@gnu.org>> <<87ioxk3x9z.fsf@zigzag.favinet> > <<83k3hye2uq.fsf@gnu.org>> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1380559129 8308 80.91.229.3 (30 Sep 2013 16:38:49 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 30 Sep 2013 16:38:49 +0000 (UTC) Cc: ttn@gnu.org, emacs-devel@gnu.org To: Eli Zaretskii , Xue Fuqiao Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Sep 30 18:38:51 2013 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1VQgUl-000637-C3 for ged-emacs-devel@m.gmane.org; Mon, 30 Sep 2013 18:38:51 +0200 Original-Received: from localhost ([::1]:50405 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VQgUk-0003ED-Fb for ged-emacs-devel@m.gmane.org; Mon, 30 Sep 2013 12:38:50 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:47262) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VQgUa-0003Ch-1a for emacs-devel@gnu.org; Mon, 30 Sep 2013 12:38:48 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VQgUR-0004kH-GB for emacs-devel@gnu.org; Mon, 30 Sep 2013 12:38:39 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:24531) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VQgU7-0004cn-8n; Mon, 30 Sep 2013 12:38:11 -0400 Original-Received: from ucsinet21.oracle.com (ucsinet21.oracle.com [156.151.31.93]) by userp1040.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with ESMTP id r8UGc8C7013303 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Mon, 30 Sep 2013 16:38:09 GMT Original-Received: from aserz7021.oracle.com (aserz7021.oracle.com [141.146.126.230]) by ucsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r8UGc76Q000222 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Mon, 30 Sep 2013 16:38:08 GMT Original-Received: from abhmt108.oracle.com (abhmt108.oracle.com [141.146.116.60]) by aserz7021.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r8UGc78h013629; Mon, 30 Sep 2013 16:38:07 GMT In-Reply-To: <<83k3hye2uq.fsf@gnu.org>> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8 (707110) [OL 12.0.6680.5000 (x86)] X-Source-IP: ucsinet21.oracle.com [156.151.31.93] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-Received-From: 156.151.31.81 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 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-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:163737 Archived-At: > > IMO every user option and every command needs documentation. >=20 > First, the original issue that started this thread was about changes > in the ELisp manual,=20 That may be. But the statement that every user option and command needs documentation does not speak about manuals. In any case, that's how I understood it: these things need documentation. Which they (and others, IMHO) do: doc strings. > The only serious problem with the doc strings is that they lack the > "glue": the kind of overview and background material that we usually > put in the manual when we describe a significant topic. A manual is exactly where such glue (overview, background, context, relations) belongs. > So what would probably be a good idea in order to improve the visibility > of those commands and options that are not in the manual is the following > measures: I disagree. We don't need such an additional manual. Either (a) something should be documented in the manual or (b) it does not to be documented there and doc strings suffice. By "doc strings" (plural), I include the possibility that one doc string refers to (links to) another. What we might want/need (I have proposed this several times, and so have others) is linking from doc strings to the manuals. That would indeed be useful, IMO. It would provide missing glue, as you put it. There are a very few doc strings, IIRC, that actually do this. It would be good to generalize it, or at least make use of it more.