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: The poor state of documentation of pcase like things. Date: Fri, 18 Dec 2015 11:21:25 +0200 Message-ID: <8360zwxgbu.fsf@gnu.org> References: <20151216202605.GA3752@acm.fritz.box> <87fuz0ydvb.fsf@russet.org.uk> <83poy4xm60.fsf@gnu.org> <871tak15pb.fsf@gmx.us> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1450430476 13333 80.91.229.3 (18 Dec 2015 09:21:16 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 18 Dec 2015 09:21:16 +0000 (UTC) Cc: emacs-devel@gnu.org To: Rasmus Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Dec 18 10:21:10 2015 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 1a9rDp-0006Nx-Ok for ged-emacs-devel@m.gmane.org; Fri, 18 Dec 2015 10:21:09 +0100 Original-Received: from localhost ([::1]:59147 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9rDp-00088Y-2S for ged-emacs-devel@m.gmane.org; Fri, 18 Dec 2015 04:21:09 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:58314) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9rDl-00087Y-Pg for emacs-devel@gnu.org; Fri, 18 Dec 2015 04:21:06 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1a9rDi-0004Sn-HY for emacs-devel@gnu.org; Fri, 18 Dec 2015 04:21:05 -0500 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:52916) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9rDi-0004Sj-EL; Fri, 18 Dec 2015 04:21:02 -0500 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:1726 helo=HOME-C4E4A596F7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1a9rDh-00025q-RL; Fri, 18 Dec 2015 04:21:02 -0500 In-reply-to: <871tak15pb.fsf@gmx.us> (message from Rasmus on Fri, 18 Dec 2015 10:12:00 +0100) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e 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:196457 Archived-At: > From: Rasmus > Date: Fri, 18 Dec 2015 10:12:00 +0100 > > > IMO, that's largely a waste of your time and energy: the manual is > > rarely if ever read in its entirety, or even in large portions. Most > > of its uses is to quickly find the subject whose description you need, > > hopefully by using the Info-index command ("i TOPIC RET"), and read > > that and perhaps some of the cross-references there. With this use > > case, the level on which a description is found is irrelevant. > > But by lifting it, it would appear more prominently in the TOC. Only in the printed book, maybe. The TOC of the Info manual is flat: all the nodes appear on the same level. Are printed or PDF manuals being used a lot these days, in preference to the Info manual? Besides, did you ever see anyone read the TOC of a large manual? I didn't. I guess someone might do that, but I cannot imagine this being a frequent use case. Once again, I won't object to such a change, I just think there are lots and lots of much more important things that can and should be done in Emacs development, even in the documentation area. I'd love to see the available scarce resource we have applied in those more important areas, if possible.