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: Fri, 29 Sep 2017 20:39:15 +0000 Message-ID: References: <83k20h78sb.fsf@gnu.org> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="94eb2c04faa2505eaf055a5a05ec" X-Trace: blaine.gmane.org 1506717592 13354 195.159.176.226 (29 Sep 2017 20:39:52 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Fri, 29 Sep 2017 20:39:52 +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 Fri Sep 29 22:39:42 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 1dy24K-0001hr-FB for ged-emacs-devel@m.gmane.org; Fri, 29 Sep 2017 22:39:32 +0200 Original-Received: from localhost ([::1]:37025 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dy24O-0004Qd-NH for ged-emacs-devel@m.gmane.org; Fri, 29 Sep 2017 16:39:36 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:49640) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dy24I-0004QW-0e for emacs-devel@gnu.org; Fri, 29 Sep 2017 16:39:31 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dy24H-0004V5-05 for emacs-devel@gnu.org; Fri, 29 Sep 2017 16:39:30 -0400 Original-Received: from mail-oi0-x234.google.com ([2607:f8b0:4003:c06::234]:43950) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dy24F-0004Ua-CW; Fri, 29 Sep 2017 16:39:27 -0400 Original-Received: by mail-oi0-x234.google.com with SMTP id r20so1313905oie.0; Fri, 29 Sep 2017 13:39:27 -0700 (PDT) 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=ElmI6WjPWRsHkjWbqZWaD7Iwi4kJOPL7Wogve73qdAQ=; b=c6q1g4+IlIiwmc63prP+0emFvzIqgYcC9LApdJIaTszBojYqphlCe9tHN+oqqzKmgh NceGs7QpnZJnSxiJUo9XmrbeojmJk5zS+10iEy3BSPb9JJ8vvTgvGf+rwLEYSeQlD9x6 2bakQJim6m7kqV3DODEFJ8X5fsQNtiYOodU/BOQnQJyGdOGxxvxDt9wQellEnhScnyEX 8yombKu9XS+0BG2WfGIIonHSFgdMdoy5FnvUepWLOOFAFRKpvJ6BBLO2DttQXC76EMAV qnRLhi3x0Di0bhQHNNXOlXnEfkn4WFCiFiCr9GI43AqI3BJ7Awny53LZrA/+8JNByAq6 BvNw== 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=ElmI6WjPWRsHkjWbqZWaD7Iwi4kJOPL7Wogve73qdAQ=; b=otyczOexjhE6F69rjNdNJWgt1ClMs3Rx4MT9wXi0IKsAGgeysalh0HIvEAVAUNHgOo UtJbyTkx5FeTsTbEUfVE7QWG68M7NSzofIOaLmSNGcI5VLmVdCtjkiPZ/5BI6rr2/MUm wAMFSJEZIGFZYm99ZEo1N3pj4fnWCZJ9NL7qCstjcbT22xJp+CwhqnIjvgisYgMVD7Tf x9CtqqVKlicCvV49DQNPTlChZ5USZnTezPg4W5uqghaFIE/HGit5PBxu7Zu3uA/WkgFV v8DR2Wyxn64/0wFbJ+lAvK7b1FtSYIiL7F23I99EdKpXJoWqJkz2VlD06oYHi01JXRMm qObg== X-Gm-Message-State: AMCzsaWDPnXHgojymmtHDwJFEaMa2GCMdlflAasocHSHZZnuAbSxGCY8 RTPmLXfpnuIPKZnvIDXssD6coUT3/VRTEGdwy6zfCQ== X-Google-Smtp-Source: AOwi7QC+xVWKVnW32LKXy44DVwtTFFAtSV0XKzOG1mJIQEGSs00RlbVhUJq8b6egswT4I9iI8nzlwoYVW/dcWJo6/e4= X-Received: by 10.157.41.36 with SMTP id d33mr3607894otb.61.1506717566249; Fri, 29 Sep 2017 13:39:26 -0700 (PDT) In-Reply-To: <83k20h78sb.fsf@gnu.org> X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2607:f8b0:4003:c06::234 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:218949 Archived-At: --94eb2c04faa2505eaf055a5a05ec Content-Type: text/plain; charset="UTF-8" Eli Zaretskii schrieb am Fr., 29. Sep. 2017 um 18:46 Uhr: > > From: Philipp Stephani > > Date: Thu, 28 Sep 2017 20:25:11 +0000 > > > > Thanks! I've also finally managed to get my draft online: > > https://phst.github.io/emacs-modules > > It's more specification-like and hopefully covers most of the behavior > of the module API. > > > > It would be great if we could have comprehensive documentation in the > ELisp manual in Emacs 26. So it > > would be great if others (especially the maintainers) could review these > two documents. Please focus on the > > content during the first pass, not on stylistic or editorial issues. > > 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. > > 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. What exactly would you want to have changed to turn it into "reference style"? --94eb2c04faa2505eaf055a5a05ec 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 18:46=C2=A0Uhr:
> From: Philipp Stephani <p.stephani2@gmail.com>
> Date: Thu, 28 Sep 2017 20:25:11 +0000
>
>=C2=A0 Thanks! I've also finally managed to get my draft online: >=C2=A0 https://phst.github.io/emacs-modules
>=C2=A0 It's more specification-like and hopefully covers most of th= e behavior of the module API.
>
> It would be great if we could have comprehensive documentation in the = ELisp manual in Emacs 26. So it
> would be great if others (especially the maintainers) could review the= se two documents. Please focus on the
> content during the first pass, not on stylistic or editorial issues.
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.=C2=A0 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 abou= t the *content*. Changing the *style* is easier and requires less discussio= n.
=C2=A0

The
first step is to convert the tutorial-like description to the
reference-style description we use in the manual.=C2=A0

I'm a bit surprised that you call my style "tuto= rial-like". I think it's not a tutorial at all; there's e.g. n= o end-to-end example to step-by-step instructions.
What exactly w= ould you want to have changed to turn it into "reference style"?= =C2=A0
--94eb2c04faa2505eaf055a5a05ec--