[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: module documentation draft
From: |
Eli Zaretskii |
Subject: |
Re: module documentation draft |
Date: |
Thu, 11 Oct 2018 21:01:47 +0300 |
> From: Philipp Stephani <address@hidden>
> Date: Tue, 26 Dec 2017 21:06:29 +0000
> Cc: address@hidden, address@hidden, address@hidden
>
> Eli Zaretskii <address@hidden> 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!
- Re: module documentation draft,
Eli Zaretskii <=