From: Philipp Stephani <p.stephani2@gmail.com>
To: Eli Zaretskii <eliz@gnu.org>
Cc: phst@google.com, aurelien.aptel@gmail.com, emacs-devel@gnu.org
Subject: Re: module documentation draft
Date: Tue, 26 Dec 2017 21:06:29 +0000 [thread overview]
Message-ID: <CAArVCkTvPmX_4btZYHoYK1h2+iSgTaDeMnwahnG3M5W96ch7Pg@mail.gmail.com> (raw)
In-Reply-To: <83a81d5iay.fsf@gnu.org>
[-- Attachment #1: Type: text/plain, Size: 3145 bytes --]
Eli Zaretskii <eliz@gnu.org> schrieb am Fr., 29. Sep. 2017 um 23:03 Uhr:
> > From: Philipp Stephani <p.stephani2@gmail.com>
> > 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.
[-- Attachment #2: Type: text/html, Size: 4968 bytes --]
next prev parent reply other threads:[~2017-12-26 21:06 UTC|newest]
Thread overview: 14+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-04-24 17:04 module documentation draft Aurélien Aptel
2017-07-23 18:57 ` Philipp Stephani
2017-07-25 12:50 ` Aurélien Aptel
2017-09-28 20:25 ` Philipp Stephani
2017-09-28 21:51 ` Aurélien Aptel
2017-09-29 16:45 ` Eli Zaretskii
2017-09-29 16:49 ` Aurélien Aptel
2017-09-29 18:08 ` Eli Zaretskii
2017-09-29 20:39 ` Philipp Stephani
2017-09-29 21:03 ` Eli Zaretskii
2017-12-26 21:06 ` Philipp Stephani [this message]
2018-10-11 18:01 ` Eli Zaretskii
2018-10-14 15:47 ` Basil L. Contovounesios
2018-10-14 16:14 ` Eli Zaretskii
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=CAArVCkTvPmX_4btZYHoYK1h2+iSgTaDeMnwahnG3M5W96ch7Pg@mail.gmail.com \
--to=p.stephani2@gmail.com \
--cc=aurelien.aptel@gmail.com \
--cc=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
--cc=phst@google.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.