* module documentation draft @ 2017-04-24 17:04 Aurélien Aptel 2017-07-23 18:57 ` Philipp Stephani 0 siblings, 1 reply; 14+ messages in thread From: Aurélien Aptel @ 2017-04-24 17:04 UTC (permalink / raw To: Philipp Stephani, Emacs development discussions [-- Attachment #1: Type: text/plain, Size: 260 bytes --] Hi, ~6 months ago I started writing some doc for modules. Some things have changed since then it seems (Philipp last message about make_global_ref seems to mention something I thought was removed.. hrm..) But it could be a good starting point. Look for XXX. [-- Attachment #2: modules.org --] [-- Type: application/vnd.lotus-organizer, Size: 13101 bytes --] ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: module documentation draft 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 0 siblings, 2 replies; 14+ messages in thread From: Philipp Stephani @ 2017-07-23 18:57 UTC (permalink / raw To: Aurélien Aptel, Philipp Stephani, Emacs development discussions [-- Attachment #1: Type: text/plain, Size: 567 bytes --] Aurélien Aptel <aurelien.aptel@gmail.com> schrieb am Mo., 24. Apr. 2017 um 19:05 Uhr: > Hi, > > ~6 months ago I started writing some doc for modules. Some things have > changed since then it seems (Philipp last message about > make_global_ref seems to mention something I thought was removed.. > hrm..) > > But it could be a good starting point. Look for XXX. > 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. [-- Attachment #2: Type: text/html, Size: 930 bytes --] ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: module documentation draft 2017-07-23 18:57 ` Philipp Stephani @ 2017-07-25 12:50 ` Aurélien Aptel 2017-09-28 20:25 ` Philipp Stephani 1 sibling, 0 replies; 14+ messages in thread From: Aurélien Aptel @ 2017-07-25 12:50 UTC (permalink / raw To: Philipp Stephani; +Cc: Philipp Stephani, Emacs development discussions Finally got around to read this. Nice! I think it's very well written, good job Philipp! ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: module documentation draft 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 1 sibling, 2 replies; 14+ messages in thread From: Philipp Stephani @ 2017-09-28 20:25 UTC (permalink / raw To: Aurélien Aptel, Philipp Stephani, Emacs development discussions [-- Attachment #1: Type: text/plain, Size: 967 bytes --] Philipp Stephani <p.stephani2@gmail.com> schrieb am So., 23. Juli 2017 um 20:57 Uhr: > Aurélien Aptel <aurelien.aptel@gmail.com> schrieb am Mo., 24. Apr. 2017 > um 19:05 Uhr: > >> Hi, >> >> ~6 months ago I started writing some doc for modules. Some things have >> changed since then it seems (Philipp last message about >> make_global_ref seems to mention something I thought was removed.. >> hrm..) >> >> But it could be a good starting point. Look for XXX. >> > > 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. [-- Attachment #2: Type: text/html, Size: 1646 bytes --] ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: module documentation draft 2017-09-28 20:25 ` Philipp Stephani @ 2017-09-28 21:51 ` Aurélien Aptel 2017-09-29 16:45 ` Eli Zaretskii 1 sibling, 0 replies; 14+ messages in thread From: Aurélien Aptel @ 2017-09-28 21:51 UTC (permalink / raw To: Philipp Stephani, Tom Tromey Cc: Philipp Stephani, Emacs development discussions On Thu, Sep 28, 2017 at 10:25 PM, Philipp Stephani <p.stephani2@gmail.com> wrote: > 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 remember finding a couple of mistakes from copy/pasting and typos but otherwise I think the structure is good. I'll make a PR to fix those. I think it would be nice to have full of a properly written simple module as an example. Perhaps my tutorial could be a start. I know the makefile is not portable but it's something. Also Chris Wellon has written 2 posts about how he used modules. It provides a good feedback, I'd suggest reading those (I think he wrote them *before* you wrote the docs): http://nullprogram.com/blog/2016/11/05/ http://nullprogram.com/blog/2017/02/14/ In the second one in particular he uses unix signals as a way to do async communication from a module function. I think it's really interesting. It reminded me of the discussions we had elsewhere with Tom Tromey about adding a way to push special events in emacs event queue to do something similar. cheers, ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: module documentation draft 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 20:39 ` Philipp Stephani 1 sibling, 2 replies; 14+ messages in thread From: Eli Zaretskii @ 2017-09-29 16:45 UTC (permalink / raw To: Philipp Stephani; +Cc: phst, aurelien.aptel, emacs-devel > From: Philipp Stephani <p.stephani2@gmail.com> > 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. If someone else would like to step forward, it would be great. The first step is to convert the tutorial-like description to the reference-style description we use in the manual. My assessment was that it would need a non-trivial amount of editorial work. TIA ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: module documentation draft 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 1 sibling, 1 reply; 14+ messages in thread From: Aurélien Aptel @ 2017-09-29 16:49 UTC (permalink / raw To: Eli Zaretskii Cc: Philipp Stephani, Philipp Stephani, Emacs development discussions Hi, On Fri, Sep 29, 2017 at 6:45 PM, Eli Zaretskii <eliz@gnu.org> wrote: > 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. Eli, I believe you're talking about a different document. Philipp's documentation is much closer to a specification than a tutorial. https://phst.github.io/emacs-modules ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: module documentation draft 2017-09-29 16:49 ` Aurélien Aptel @ 2017-09-29 18:08 ` Eli Zaretskii 0 siblings, 0 replies; 14+ messages in thread From: Eli Zaretskii @ 2017-09-29 18:08 UTC (permalink / raw To: Aurélien Aptel; +Cc: phst, p.stephani2, emacs-devel > From: Aurélien Aptel <aurelien.aptel@gmail.com> > Date: Fri, 29 Sep 2017 18:49:59 +0200 > Cc: Philipp Stephani <p.stephani2@gmail.com>, Philipp Stephani <phst@google.com>, > Emacs development discussions <emacs-devel@gnu.org> > > On Fri, Sep 29, 2017 at 6:45 PM, Eli Zaretskii <eliz@gnu.org> wrote: > > 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. > > Eli, I believe you're talking about a different document. Philipp's > documentation is much closer to a specification than a tutorial. > > https://phst.github.io/emacs-modules No, I'm talking about this very document. I won't argue with the "tutorial" part, but the point is the style and the methodology of introducing the features there is very different from what I expect of a chapter in the ELisp manual. Just read some chapter or section which describes a single large feature, and you will see the difference. I don't mean to denigrate Philipp's work in any way, I'm just saying that importing it into the ELisp manual needs some non-trivial work, that's all. ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: module documentation draft 2017-09-29 16:45 ` Eli Zaretskii 2017-09-29 16:49 ` Aurélien Aptel @ 2017-09-29 20:39 ` Philipp Stephani 2017-09-29 21:03 ` Eli Zaretskii 1 sibling, 1 reply; 14+ messages in thread From: Philipp Stephani @ 2017-09-29 20:39 UTC (permalink / raw To: Eli Zaretskii; +Cc: phst, aurelien.aptel, emacs-devel [-- Attachment #1: Type: text/plain, Size: 1432 bytes --] Eli Zaretskii <eliz@gnu.org> schrieb am Fr., 29. Sep. 2017 um 18:46 Uhr: > > From: Philipp Stephani <p.stephani2@gmail.com> > > 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"? [-- Attachment #2: Type: text/html, Size: 2138 bytes --] ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: module documentation draft 2017-09-29 20:39 ` Philipp Stephani @ 2017-09-29 21:03 ` Eli Zaretskii 2017-12-26 21:06 ` Philipp Stephani 0 siblings, 1 reply; 14+ messages in thread From: Eli Zaretskii @ 2017-09-29 21:03 UTC (permalink / raw To: Philipp Stephani; +Cc: phst, aurelien.aptel, emacs-devel > 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". > 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. I already said I won't argue about the "tutorial" part, so let's drop it. > What exactly would you want to have changed to turn it into "reference style"? It's hard to explain without doing the actual work. For starters, it is too formal: begins by introducing all the terms, even if that's far from where they are actually needed in the description; talks about requirements before describing the interesting stuff; etc. Then the order of the sections doesn't always make sense to me: for example, "Compatibility" should be somewhere near the end. And there are other issues. Doesn't reading a typical chapter in the ELisp manual, such as "Hash Tables" or "Processes", make the differences clear? 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? ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: module documentation draft 2017-09-29 21:03 ` Eli Zaretskii @ 2017-12-26 21:06 ` Philipp Stephani 2018-10-11 18:01 ` Eli Zaretskii 0 siblings, 1 reply; 14+ messages in thread From: Philipp Stephani @ 2017-12-26 21:06 UTC (permalink / raw To: Eli Zaretskii; +Cc: phst, aurelien.aptel, emacs-devel [-- 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 --] ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: module documentation draft 2017-12-26 21:06 ` Philipp Stephani @ 2018-10-11 18:01 ` Eli Zaretskii 2018-10-14 15:47 ` Basil L. Contovounesios 0 siblings, 1 reply; 14+ messages in thread From: Eli Zaretskii @ 2018-10-11 18:01 UTC (permalink / raw To: Philipp Stephani; +Cc: phst, aurelien.aptel, emacs-devel > 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! ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: module documentation draft 2018-10-11 18:01 ` Eli Zaretskii @ 2018-10-14 15:47 ` Basil L. Contovounesios 2018-10-14 16:14 ` Eli Zaretskii 0 siblings, 1 reply; 14+ messages in thread From: Basil L. Contovounesios @ 2018-10-14 15:47 UTC (permalink / raw To: Eli Zaretskii; +Cc: phst, Philipp Stephani, aurelien.aptel, emacs-devel [-- Attachment #1: Type: text/plain, Size: 289 bytes --] Eli Zaretskii <eliz@gnu.org> writes: > 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. It all made sense to me, FWIW. I only noticed one potential improvement: [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #2: internals.diff --] [-- Type: text/x-diff, Size: 655 bytes --] diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index 311eb6b262..c1d855fc2d 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -1190,7 +1190,7 @@ Module Functions Lisp function object from it using @code{make_function}. This is normally done in the module initialization function (@pxref{module initialization function}), after verifying the @acronym{API} -compatibility, and uses the pointer to @code{make_function} provided +compatibility, and using the pointer to @code{make_function} provided in the environment (recall that the pointer to the environment is returned by @code{get_environment}). [-- Attachment #3: Type: text/plain, Size: 257 bytes --] > 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! Thanks to both of you for the great work! -- Basil ^ permalink raw reply related [flat|nested] 14+ messages in thread
* Re: module documentation draft 2018-10-14 15:47 ` Basil L. Contovounesios @ 2018-10-14 16:14 ` Eli Zaretskii 0 siblings, 0 replies; 14+ messages in thread From: Eli Zaretskii @ 2018-10-14 16:14 UTC (permalink / raw To: Basil L. Contovounesios; +Cc: phst, p.stephani2, aurelien.aptel, emacs-devel > From: "Basil L. Contovounesios" <contovob@tcd.ie> > Cc: Philipp Stephani <p.stephani2@gmail.com>, <phst@google.com>, <aurelien.aptel@gmail.com>, <emacs-devel@gnu.org> > Date: Sun, 14 Oct 2018 16:47:25 +0100 > > It all made sense to me, FWIW. I only noticed one potential > improvement: Thanks. I fixed this a bit differently, because my intent was to say something else. ^ permalink raw reply [flat|nested] 14+ messages in thread
end of thread, other threads:[~2018-10-14 16:14 UTC | newest] Thread overview: 14+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 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 2018-10-11 18:01 ` Eli Zaretskii 2018-10-14 15:47 ` Basil L. Contovounesios 2018-10-14 16:14 ` Eli Zaretskii
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.