From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Philipp Stephani
> 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".
> 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.
= =C2=A0 For starters, it
is too formal:
begins by introducing all the terms, even if that's far<= br> from where they are actually needed in the description;
talks about
requirements before describing the interesting stuff;
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=A0I'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= div>--94eb2c122b70bee228056144a870--
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.