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: Thu, 11 Oct 2018 21:01:47 +0300 Message-ID: <83zhvkwees.fsf@gnu.org> References: <83k20h78sb.fsf@gnu.org> <83a81d5iay.fsf@gnu.org> NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1539280842 25138 195.159.176.226 (11 Oct 2018 18:00:42 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Thu, 11 Oct 2018 18:00:42 +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 Thu Oct 11 20:00:37 2018 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 1gAfGH-0006QO-1T for ged-emacs-devel@m.gmane.org; Thu, 11 Oct 2018 20:00:37 +0200 Original-Received: from localhost ([::1]:35807 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gAfIN-0003sx-FB for ged-emacs-devel@m.gmane.org; Thu, 11 Oct 2018 14:02:47 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:48680) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gAfHc-0003sa-BD for emacs-devel@gnu.org; Thu, 11 Oct 2018 14:02:02 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gAfHY-00081o-LW for emacs-devel@gnu.org; Thu, 11 Oct 2018 14:02:00 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:34921) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gAfHY-00081X-Af; Thu, 11 Oct 2018 14:01:56 -0400 Original-Received: from [176.228.60.248] (port=1667 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1gAfHV-00079Q-Rk; Thu, 11 Oct 2018 14:01:56 -0400 In-reply-to: (message from Philipp Stephani on Tue, 26 Dec 2017 21:06:29 +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:230338 Archived-At: > From: Philipp Stephani > Date: Tue, 26 Dec 2017 21:06:29 +0000 > Cc: aurelien.aptel@gmail.com, phst@google.com, emacs-devel@gnu.org > > Eli Zaretskii schrieb am Fr., 29. Sep. 2017 um 23:03 Uhr: > > > What exactly would you want to have changed to turn it into "reference style"? > > It's hard to explain without doing the actual work. > > It's equally hard to do the work without knowing what work there is to do :-) > > For starters, it > is too formal: > > Point taken, though the formality is to a certain extent intentional: the goal of a reference manual is to describe > as clearly and exhaustively as possible the entire interface of the system. This requires a certain amount of > formality, otherwise the description easily becomes unclear. > > begins by introducing all the terms, even if that's far > from where they are actually needed in the description; > > I'm OK with moving the definitions around, as long as terms are defined before they are used. > > talks about > requirements before describing the interesting stuff; > > The requirements *is* the interesting stuff. What comes later (the description of the specific environment > functions) is rather plain and has much fewer pitfalls. > > etc. Then the > order of the sections doesn't always make sense to me: for example, > "Compatibility" should be somewhere near the end. > > I'm not against some reordering, but again, the requirements described in the "Compatibility" section are more > important than the specific details about the environment functions. If we put such important requirements at > the end, module authors will likely skip them, leading to brittle modules that fail in weird ways. > > > Doesn't reading a typical chapter in the ELisp manual, such as "Hash > Tables" or "Processes", make the differences clear? > > Not really. On a high level, these sections follow a similar structure: first they give some general overview and > provide definitions, then a list of functions with specific explanation follows, grouped by topic. I've finally got to writing up this stuff, please take a look at the ELisp manual's node "Writing Dynamic Modules" on the latest emacs-26 branch. Comments are welcome. I'd like to take this opportunity to thank Philipp for his document (https://phst.github.io/emacs-modules), which I used as inspiration and as a reference against which to check my text. Thanks!