From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Philipp Stephani Newsgroups: gmane.emacs.devel Subject: Re: module documentation draft Date: Tue, 26 Dec 2017 21:06:29 +0000 Message-ID: References: <83k20h78sb.fsf@gnu.org> <83a81d5iay.fsf@gnu.org> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="94eb2c122b70bee228056144a870" X-Trace: blaine.gmane.org 1514322301 17633 195.159.176.226 (26 Dec 2017 21:05:01 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Tue, 26 Dec 2017 21:05:01 +0000 (UTC) Cc: phst@google.com, aurelien.aptel@gmail.com, emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Dec 26 22:04:57 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 1eTwP9-0003rS-Ox for ged-emacs-devel@m.gmane.org; Tue, 26 Dec 2017 22:04:55 +0100 Original-Received: from localhost ([::1]:57161 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eTwR5-0008KU-7c for ged-emacs-devel@m.gmane.org; Tue, 26 Dec 2017 16:06:55 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:32823) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eTwQu-0008K0-9j for emacs-devel@gnu.org; Tue, 26 Dec 2017 16:06:45 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eTwQt-0000wE-0R for emacs-devel@gnu.org; Tue, 26 Dec 2017 16:06:44 -0500 Original-Received: from mail-qt0-x232.google.com ([2607:f8b0:400d:c0d::232]:41621) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1eTwQr-0000sf-4G; Tue, 26 Dec 2017 16:06:41 -0500 Original-Received: by mail-qt0-x232.google.com with SMTP id i40so46060977qti.8; Tue, 26 Dec 2017 13:06:41 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=Mohupfjq9B0sxcYFS3qZ58dXknjc4u1xX3ehV0hPUUM=; b=taUqE/nasGI5H0xD7T5LRfblZq0LwbhWIzBy0oTabuR5FmRUX6jjxM3YNZUkckBRj5 myF6foLSiKs/j6gnWo5gUlQehVP7f1TJpt8u5rLKQ6LIJSRRS+5b61HR9hRnpz3OyhXB cItbRnjVE+j78qu1Fz6Ilp9B/XxjYQkZbTT+e0OzscEZaYnLmTuWBso/28/jqPyBKtvF gUhFDdnOsNEnx2oOduh1/RwJl3Ml+M4bBjQpqR/i25ks9ZSYQT4rhoxjUeSbVmQY3Y2H K1Em/jCL+joK0Iow2ZNwX1cJFocO7HQAE00kUGDc6zMGMhMvBimtFOWP8nKV1cZ2W8MC ncSA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=Mohupfjq9B0sxcYFS3qZ58dXknjc4u1xX3ehV0hPUUM=; b=N0Dv+xuiRqofwfuqS+p1NRvLu/t6nNMbmzYfCtdTkGp7wHpeQFj6Mb179vA2L6xOxX fgRbcjLQ8NwHrBCXQ4Ew2aD8hDYu1mUiVj84KVNqAfnnkyg+dUE2FUnymoey4ZaeeWmI 8rnN+EPbuP4yDOMfv1lastpg+qTtN3Bom2Oi9D6NoAqFmAg6/zG+BuREtDTrswYB2zXF 5R8kSxgnHKc9lKQYMP06OtmJfuLkSItsq3UsBgWl6aOBUX8B+dBdFzBp531Xz0Sep6Ne z/HKoyQPj75LlY5pxe7gluK3LlopAlc2s/MmJIImGFzp5mHGY9RQE2K4eCqhNYUh3c5+ y4Fw== X-Gm-Message-State: AKGB3mJEtMuX/UzjgEsKOomzqNeBUZUlILZKAJ6mHlgeaewmr1X/i3q6 ahh9a7tuNN+mXHC8eePbBAjtr9kl8qtt8JezIyH2mQ== X-Google-Smtp-Source: ACJfBoskfpRDjfMRcpBTrQYNJZ94QGWZIRF43i6hs/Cae1nGukQ3h99QtU/0Y4pJlr8HfYLfHCSqDzdPC6d3dcHxX4Y= X-Received: by 10.200.27.76 with SMTP id p12mr37308697qtk.310.1514322400304; Tue, 26 Dec 2017 13:06:40 -0800 (PST) In-Reply-To: <83a81d5iay.fsf@gnu.org> X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2607:f8b0:400d:c0d::232 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:221427 Archived-At: --94eb2c122b70bee228056144a870 Content-Type: text/plain; charset="UTF-8" Eli Zaretskii schrieb am Fr., 29. Sep. 2017 um 23:03 Uhr: > > 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". > This is again mostly wordsmithing, but what you call out below (ordering of sections, where to put definitions) is definitely part of what I'd call "style". > > > 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. > > 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? > Well, from my point of view the text is almost perfect (since I wrote it), but I guess that's not really helpful ;-) I would probably trim down some of the examples or the "History" section, because they are probably not very interesting for a reference manual. --94eb2c122b70bee228056144a870 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable


Eli Za= retskii <eliz@gnu.org> schrieb am= Fr., 29. Sep. 2017 um 23:03=C2=A0Uhr:
> From: Philipp Stephani <p.stephani2@gmail.com>
> Date: Fri, 29 Sep 2017 20:39:15 +0000
> Cc: aure= lien.aptel@gmail.com, phst@google.com, emacs-devel@gnu.org
>
>=C2=A0 I already read this, when this was first announced in April.
>=C2=A0 Unfortunately, the style and the methodology of the description<= br> >=C2=A0 differs significantly from what we use in the ELisp manual. So t= his
>=C2=A0 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 th= e *style* is easier and requires less
> discussion.

I said "style and methodology", and we seem to disagree about wha= t is
and isn't "style".=C2=A0 My "style" is part of your= "content".

This is again mos= tly wordsmithing, but what you call out below (ordering of sections, where = to put definitions) is definitely part of what I'd call "style&quo= t;.
=C2=A0

> What exactly would you want to have changed to turn it into "refe= rence 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 :-)
=C2=A0
= =C2=A0 For starters, it
is too formal:

Point taken, though the form= ality is to a certain extent intentional: the goal of a reference manual is= to describe as clearly and exhaustively as possible the entire interface o= f the system. This requires a certain amount of formality, otherwise the de= scription easily becomes unclear.
=C2=A0
begins by introducing all the terms, even if that's far<= br> from where they are actually needed in the description;
I'm OK with moving the definitions around, as long as term= s are defined before they are used.
=C2=A0
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.
=C2=A0
etc.=C2=A0 Then the
order of the sections doesn't always make sense to me: for example,
"Compatibility" should be somewhere near the end.=C2=A0

I'm not against some reordering, but again, the = requirements described in the "Compatibility" section are more im= portant than the specific details about the environment functions. If we pu= t such important requirements at the end, module authors will likely skip t= hem, leading to brittle modules that fail in weird ways.
=C2=A0

Doesn't reading a typical chapter in the ELisp manual, such as "Ha= sh
Tables" or "Processes", make the differences clear?

Not really. On a high level, these sections fol= low a similar structure: first they give some general overview and provide = definitions, then a list of functions with specific explanation follows, gr= ouped by topic.
=C2=A0

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?

=
Well, from my point of view the text is almost perfect (since I wrote = it), but I guess that's not really helpful ;-)
I would probab= ly trim down some of the examples or the "History" section, becau= se they are probably not very interesting for a reference manual.
--94eb2c122b70bee228056144a870--