From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Changes in revision 114466 Date: Mon, 30 Sep 2013 18:38:53 +0300 Message-ID: <83k3hye2uq.fsf@gnu.org> References: <831u49fkxk.fsf@gnu.org> <83pprse4mf.fsf@gnu.org> <87ioxk3x9z.fsf@zigzag.favinet> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1380555552 27952 80.91.229.3 (30 Sep 2013 15:39:12 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 30 Sep 2013 15:39:12 +0000 (UTC) Cc: ttn@gnu.org, emacs-devel@gnu.org To: Xue Fuqiao Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Sep 30 17:39:15 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 1VQfZ2-0001On-SA for ged-emacs-devel@m.gmane.org; Mon, 30 Sep 2013 17:39:13 +0200 Original-Received: from localhost ([::1]:49472 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VQfZ2-0004Eq-DI for ged-emacs-devel@m.gmane.org; Mon, 30 Sep 2013 11:39:12 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:55956) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VQfYt-0004EL-GS for emacs-devel@gnu.org; Mon, 30 Sep 2013 11:39:09 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VQfYn-0007tw-L2 for emacs-devel@gnu.org; Mon, 30 Sep 2013 11:39:03 -0400 Original-Received: from mtaout23.012.net.il ([80.179.55.175]:65041) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VQfYn-0007tX-Bw; Mon, 30 Sep 2013 11:38:57 -0400 Original-Received: from conversion-daemon.a-mtaout23.012.net.il by a-mtaout23.012.net.il (HyperSendmail v2007.08) id <0MTY0090037VT700@a-mtaout23.012.net.il>; Mon, 30 Sep 2013 18:38:55 +0300 (IDT) Original-Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout23.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0MTY0096S3GUOV70@a-mtaout23.012.net.il>; Mon, 30 Sep 2013 18:38:54 +0300 (IDT) In-reply-to: X-012-Sender: halo1@inter.net.il X-detected-operating-system: by eggs.gnu.org: Solaris 10 X-Received-From: 80.179.55.175 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:163733 Archived-At: > Date: Mon, 30 Sep 2013 12:55:47 +0800 > From: Xue Fuqiao > Cc: emacs-devel > > IMO every user option and every command needs documentation. First, the original issue that started this thread was about changes in the ELisp manual, so user options and commands are not really relevant. In any case, please keep in mind the downsides of this "document everything" attitude: it would bloat the Info manuals to humongous proportions, for reasons that IMO are not good enough. Here are some numbers obtained by a series of simplistic searches: . There are over 5000 commands in Emacs, and over 7500 defcustom's. . Out of these, the Emacs User Manual documents about 1400 commands and slightly less than 700 user options and variables. . Manuals in doc/misc document 2000 more commands and 2000 options. So even if we assume that there's no duplicates between doc/emacs/ and doc/misc/ manuals (I didn't check), a suggestion to document everything would bloat the manual almost twofold. If you ever saw the User Manual in printed format, you know that it is already a very fat book, holding several hundreds of pages. Making it twice that would most probably require to split it into two volumes, something that makes both the book and its production significantly more expensive, and actually shoots the FSF, who produces the book, in the foot, because a larger and more expensive book will get sold less, and thus cut the revenues even more. The maintenance burden of maintaining twice more docs is also something we shouldn't discount easily. The process of updating and reviewing the manuals before a release, especially a major release, is already exceedingly long and painful, typically delaying the release for many weeks. Do we really want to make it even more painful? Meanwhile, most of the stuff that is not in the manual has (barring any bugs) doc strings, which document those commands and options quite adequately, and are at users' fingertips even more readily than the Info manual. What exactly will we say in the manual, besides reiterating those same doc strings, and why is that a necessity? 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. 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: . Add a new manual to doc/misc/, which will be separate from the user manual. In that manual, provide short descriptions of every package, with index entries that will make it easy to find those descriptions even if one doesn't know the package name, and state the file(s) in which the package lives. . Improve the doc strings so that "apropos-documentation" and other apropos commands would find stuff more efficiently. I think this is a much more practical way of improving the user documentation without incurring the kind of overhead that will be required if we decide to "document everything".