Re: module documentation draft

[Eli Zaretskii <eliz@gnu.org>]

> From: Philipp Stephani <p.stephani2@gmail.com>
> Date: Tue, 26 Dec 2017 21:06:29 +0000
> Cc: aurelien.aptel@gmail.com, phst@google.com, emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> 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!