From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: module documentation draft Date: Sat, 30 Sep 2017 00:03:17 +0300 Message-ID: <83a81d5iay.fsf@gnu.org> References: <83k20h78sb.fsf@gnu.org> Reply-To: Eli Zaretskii NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1506719018 24890 195.159.176.226 (29 Sep 2017 21:03:38 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Fri, 29 Sep 2017 21:03:38 +0000 (UTC) Cc: phst@google.com, aurelien.aptel@gmail.com, emacs-devel@gnu.org To: Philipp Stephani Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Sep 29 23:03:33 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 1dy2RW-0005l8-0A for ged-emacs-devel@m.gmane.org; Fri, 29 Sep 2017 23:03:30 +0200 Original-Received: from localhost ([::1]:37090 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dy2Rd-0002YE-Ck for ged-emacs-devel@m.gmane.org; Fri, 29 Sep 2017 17:03:37 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:56266) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dy2RU-0002XT-0C for emacs-devel@gnu.org; Fri, 29 Sep 2017 17:03:28 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dy2RQ-00008n-Sp for emacs-devel@gnu.org; Fri, 29 Sep 2017 17:03:28 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:54879) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dy2RQ-00008j-QT; Fri, 29 Sep 2017 17:03:24 -0400 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:1560 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1dy2RQ-0001hU-7J; Fri, 29 Sep 2017 17:03:24 -0400 In-reply-to: (message from Philipp Stephani on Fri, 29 Sep 2017 20:39:15 +0000) 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.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:218952 Archived-At: > From: Philipp Stephani > Date: Fri, 29 Sep 2017 20:39:15 +0000 > Cc: aurelien.aptel@gmail.com, phst@google.com, emacs-devel@gnu.org > > I already read this, when this was first announced in April. > Unfortunately, the style and the methodology of the description > differs significantly from what we use in the ELisp manual. So this > text will have to be reworked, and I didn't yet find time to do it. > > As said, I'd like to get feedback about the *content*. Changing the *style* is easier and requires less > discussion. I said "style and methodology", and we seem to disagree about what is and isn't "style". My "style" is part of your "content". > The > first step is to convert the tutorial-like description to the > reference-style description we use in the manual. > > I'm a bit surprised that you call my style "tutorial-like". I think it's not a tutorial at all; there's e.g. no end-to-end > example to step-by-step instructions. I already said I won't argue about the "tutorial" part, so let's drop it. > What exactly would you want to have changed to turn it into "reference style"? It's hard to explain without doing the actual work. For starters, it is too formal: begins by introducing all the terms, even if that's far from where they are actually needed in the description; talks about requirements before describing the interesting stuff; etc. Then the order of the sections doesn't always make sense to me: for example, "Compatibility" should be somewhere near the end. And there are other issues. Doesn't reading a typical chapter in the ELisp manual, such as "Hash Tables" or "Processes", make the differences clear? Or let me turn the table and ask you: do you think that text is fit for putting it as-is into the ELisp manual?