From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Lynn Winebarger Newsgroups: gmane.emacs.devel Subject: Re: Larger GC thresholds for non-interactive Emacs Date: Sat, 25 Jun 2022 12:50:41 -0400 Message-ID: References: <83y1y2utnd.fsf@gnu.org> <87r13up587.fsf@localhost> <83o7yyur0l.fsf@gnu.org> <87leu2p3nu.fsf@localhost> <83leu2uewn.fsf@gnu.org> <87r13qv701.fsf@localhost> <83bkuursya.fsf@gnu.org> <87h74l9jk8.fsf@localhost> <83bkutqb3z.fsf@gnu.org> <9778F176-E724-4E61-B0FB-327BCDD316C0@acm.org> <87sfo4epeo.fsf@localhost> <87bkurrc5e.fsf@localhost> <87bkur72b7.fsf@gnus.org> <874k0j40e7.fsf@gnus.org> <871qvm16he.fsf@gnus.org> <83a6aanm5j.fsf@gnu.org> <87o7yozzj0.fsf@gnus.org> <83k098kg6c.fsf@gnu.org> <8335fvg8kz.fsf@gnu.org> <83y1xncjkj.fsf@gnu.org> <83pmiyd01o.fsf@gnu.org> Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="0000000000008e77ca05e2487d6e" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="2272"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Lars Ingebrigtsen , Stefan Monnier , Ihor Radchenko , =?UTF-8?Q?Mattias_Engdeg=C3=A5rd?= , Tim Cross , rms@gnu.org, Alan Mackenzie , emacs-devel To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat Jun 25 18:53:05 2022 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1o591t-0000S8-Af for ged-emacs-devel@m.gmane-mx.org; Sat, 25 Jun 2022 18:53:05 +0200 Original-Received: from localhost ([::1]:55260 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1o591r-0003tO-Sj for ged-emacs-devel@m.gmane-mx.org; Sat, 25 Jun 2022 12:53:03 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:43320) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1o58zt-0002ZD-T3 for emacs-devel@gnu.org; Sat, 25 Jun 2022 12:51:01 -0400 Original-Received: from mail-oi1-x235.google.com ([2607:f8b0:4864:20::235]:39502) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1o58zq-0002Ay-LU; Sat, 25 Jun 2022 12:51:01 -0400 Original-Received: by mail-oi1-x235.google.com with SMTP id bd16so7483470oib.6; Sat, 25 Jun 2022 09:50:57 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=0ha798gWbgR7I/tVImh7cP75eRC0ZYbFFz6kQrrw55k=; b=cLzeXcEDy9CwPPxVQH1Lq9v2QPb8lL8KEtY0GCuk/kYzZmKgVi07V95djeQ5M5+r1G FbOUKLh2jcCpAAH2khVTGcJtnunIEx0j9xsBRohjMWR+Y02lLqmQWM2/IStBUS9sXeG7 Rhy2v9p8+h2aOQm0AA5eVeRurAvtaeKMSzbDzFFkrQtxZXrxeNW2qwzYqqpsAS2IMShp Q8+ZDXjbJnhDYDEEa9KNkmjF1s5Lp6OQ3wXeVMvNzf7ODJndISElENn9qj2NAibFJXYi 0wyCQ2zozh03wWVvC9b2DMHnMJSWy/SN52lEScY6f7oKM2s4vKx5+q4pj2EfGDboWVhs 2lOA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=0ha798gWbgR7I/tVImh7cP75eRC0ZYbFFz6kQrrw55k=; b=b7kzpoyQQuRN4DtTV/wYyTKfJnjBb+jZ0mhQc3FxzgKPOLeHOUHa7nba2MkGZ+0KAB rQXtEIgu8ZPwHw5xTPHwAqnA4+m0COZnSDZ2eUziyH1NJO8KC1lUXFJf0k3xS8DiaG3x WMoA8s4SZ6U7FWmwfffJKzaB6HR/4SG1o87mHFZmHoCBSxNGfKpzmhMH2Hb0CVIkBSoV i8XsDt/uozMbhyLXrbOfGBd1HP6YFzWpWn9XfA7dgs6TlFORbyKU7V3k+uIbEbUpURxn u98Hxup95oHeZO5zGZfKGU7Vl78BTR8soZ7Tvupne6xdHYudmBgVQG9kjF39nc0fOV3j fOUQ== X-Gm-Message-State: AJIora8zRSE/TZVF77gRG1KSW+ytrpbVnohCDLQDOcj6WSWuq/tW50fD N6xZBgK5nB0N/yn/qLHxAHfRXD2mFaaC9CrlujA4RlJux3g= X-Google-Smtp-Source: AGRyM1ulnYy67yZtZpHb4YLIvRzuZVoK1XRIlufjujZxy5PYk+SxaLgvcZBDMUyy2dZmV5f1iEIRIs6m3vok6BRXBDw= X-Received: by 2002:a05:6808:1a96:b0:333:289e:713d with SMTP id bm22-20020a0568081a9600b00333289e713dmr2943334oib.247.1656175855563; Sat, 25 Jun 2022 09:50:55 -0700 (PDT) In-Reply-To: <83pmiyd01o.fsf@gnu.org> Received-SPF: pass client-ip=2607:f8b0:4864:20::235; envelope-from=owinebar@gmail.com; helo=mail-oi1-x235.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:291621 Archived-At: --0000000000008e77ca05e2487d6e Content-Type: text/plain; charset="UTF-8" On Fri, Jun 24, 2022, 2:54 AM Eli Zaretskii wrote: > > From: Lynn Winebarger > > > > > > It would help if there were some taxonomy of features/design > > > > points for > > > > reference. Is the bug database being used for that? > > > > > > I don't think so (IIUC what you mean by that), and I don't really see > > > how bugs could serve in that role. > > > > I agree, but some of the bug reports are classified as something along > > the lines of "feature request" or "wishlist". > > If you look at those, you will see that almost all of them request > minor features that have no impact on the design whatsoever. It is > very rare to have a feature request on the bug tracker that changes > the design or introduces new designs. I would even dare to say it > never happened, definitely not on my watch. > > > I haven't found any other database tracking anything corresponding > > to features, proposed or otherwise. > > We do have etc/TODO. Did you look there? > Yes, but it's not indexed so there's no good way to reference particular items the way bugs are. > > Once something is in place, no matter how bare-bones, the key would be > > maintainers mandating that any substantive introduction or revision of > > features be tied to appropriate entries for the corresponding > > design/spec documentation, in the same way and for the same reason > > coding standards are enforced. > > I think you are greatly underestimating the efforts required to > maintain documentation of this kind, let alone the effort for creating > it basically from scratch. > I just have a lot of sympathy for the points you made in that portable dumper thread, regarding the cost of accepting substantial contributions from transitory contributors. Anyone can create a new feature or improvement and maintain their own variant, but it's a lot easier for them if the project takes over maintenance and breaking it becomes a rejection test for future changes. Everything you say below is sensible. You and the other (current and future) core maintainers are the ones who have to make the trade-off, after all. I'm going to add some comments below, though, because I think my perspective on what is useful is different. If they are obvious or too idiosyncratic to be useful in the context of attracting new contributors/maintainers, feel free to ignore them. > > Programmers usually don't like writing documentation, and most of them > cannot write good documentation even if they did want, in large part > because that take years of practice actually doing it. In a project > like Emacs, it is nigh impossible to force contributors and developers > do what they are reluctant to do in the first place. Without everyone > updating the documentation as they change code, any documentation > about design and internals will quickly become outdated, and thus not > just useless, but downright harmful. We have trouble keeping even our > user documentation up-to-date. > Is it harmful? I suppose it depends on who's relying on it. Diving into the source of a project with Emacs's complexity with a particular design change in mind, personally I prefer to have some guideposts knowing that they may be dated, then ask knowledgeable people if there seems to be a disagreement between the doc and the code. When that happens on a public forum like this list, then there's some reference. It's true, I have a low bar. It might not seem like it, but my preference is to explore a question as much as I can on my own before bothering the experts. In the best case, the question that stumps me also stumps the expert - then I know I've done adequate study. With Emacs (and often other free software projects), it's just hard to tell what I should be responsible for studying prior to asking questions. Beyond the code itself, of course. Are you aware of _any_ Free Software project that has any useful > documentation of this kind? I know some "Open Source" projects (eg chromium) that have useful docs. Also projects with academic roots (Larceny Scheme is still my go-to) tend to have them. I'm assuming that in this context, the OSS projects, at least, are not "Free Software project[s]" in the sense you intended, even if the software produced by those projects happens to be Free. I don't do development for a living, so when I first looked into the code of those corporate projects, the general culture around demanding uniformity of build systems and supported configurations was quite a culture shock after being accustomed to the approach of Free Software projects. So I'm assuming you intend to refer to projects that have freedom as an organizing principle, and hence exhibit a self-selection bias toward diverse and idiosyncratic preferences and goals among their contributors. Or something along those lines? Every project I ever knew or was involved > with which tried ended up abandoning that. A case in point is GDB, > which once had a "GDB Internals" manual -- it was always outdated, and > was eventually scrapped because the maintainers decided they could not > and didn't want to invest the effort. I remember thinking it was a shame. But, my bar for usefulness is fairly low. XEmacs tried in its time to > have the internals documented, but that was basically a one-man > effort, and even in it whole chapters were never written. Etc. etc. > > I think there's some conclusion waiting here. > I think we have different problem scopes in mind. I'd take some kind of indexed wiki as a substantial improvement, particularly if there were links between tags in the code as well as files and directories cross-referencing features and VC logs, with the primary archive of discussion happening there rather than an email list (as with discussion around bugs). I'd just like to be able to determine answers to questions like: why is preventing the allocation of lisp objects by mmap necessary? What purpose does ralloc.c serve? Do they still serve a purpose?, and know whether I've done enough self-study to justify asking the experts. > That's assuming the maintainers consider such documentation > > important enough for enabling future potential contributors and > > maintainers to hold otherwise useful contributions in limbo. > > And you think we don't? Of course we do! We also want to release > Emacs much more frequently, and we want it to have no bugs, and a few > other things. But somehow, each such goal cannot be reached for some > boring practical reasons, none of them related to their importance in > our eyes. > I did not mean to imply you don't consider them important (I can see it might read that way). I meant "important enough [relative to all the competing priorities]". I don't know of any other way of expressing importance except relative to competing priorities subject to resource constraints. > We do in general consider it somewhat more important to develop Emacs > and accept contributions than to document its internals, that's true. > Which is why I said up-thread that without someone who'd volunteer to > do this job (thus dedicating his/her time almost exclusively to it), > this will probably never happen, given the current state of our > resources, which are barely enough to maintain the status quo and move > forward at some reasonable pace. > > > > Most of the design changes and > > > redesigns in Emacs were developed without any bug report, simply > > > because those who did the job knew that a particular group of problems > > > needs to be taken care of. > > > > It's not like there isn't any discussion or justification of features > > offered prior to code being integrated into the main branch. It's more > > a challenge of how to weave what's there into a coherent account of > > what's going on in the code. > > IME, you are wrong in that assumption. The significant changes in > Emacs design are almost never publicly discussed, not in the way that > would allow someone to glean the design from them. > Then, I should understand Daniel Colascione's approach with the portable dumper preview thread and the more recent one on a revised gc are either outliers - or that I'm misreading their scope relative to the discussion of design issues they provide? [ That's a straight question to resolve my ignorance, not intended to be snarky. ] > It would just be easier to automate some sort of design note > > extraction from the git log if references to mails could be associated > > with relevant features. I've never used org, but maybe there's some > > syntax that would be useful? Or maybe some notation from supercite > > for precise pulling of relevant text from list archives? > > I wish this were true. It isn't. The discussions and the commit log > messages rarely describe the design, and in many cases barely describe > even the particular implementation. In a project where people with > write access can commit changes without any review, I don't know how > can anything else to be expected. We basically rely on each > individual to do the job perfectly and contribute to what you want to > see documented. The results are before our eyes, and they shouldn't > surprise anyone. > True enough. > > > > > https://github.com/rocky/elisp-bytecode > > > > That is really useful documentation that would ideally be in the > emacs docs > > > > or etc directory. > > > > > > That's not design description, though. > > > > You probably have a more nuanced view than me on this. It's true, > > that document is focused on the specification (the "what") rather than > > the (detailed) "how" and "why" - is that what you mean? > > Of course. > > > Either way, if you want to understand how the operational semantics > > of emacs lisp work in practice, a document of that sort is > > invaluable. Without that, a document explaining the "why" isn't > > going to be able to be very concrete. > > I agree, but the "what" is usually already available in the comments > to the code, though not everywhere and for every significant feature. > The "why" and "how", by contrast are almost completely missing. > In the particular case of the bytecode spec, at least it gives me the sense of the invariants that are being maintained by the implementation. Trying to reverse engineer what those invariants are from a giant C switch statement is always tricky, because they tend to be expressed with boilerplate code, and then sometimes you have clever use of the fact that cases are non-exclusive and "fall through" without an explicit break, etc. That's where it intersects with "design" for me. OTOH, the same switch statement could be written as a dispatch table of higher-order functions exploiting proper tail-recursion in a way I would feel comfortable enough with to not feel the need to lean on a spec. But that assumes those higher-order functions clearly express the invariants they impose. It's a personal preference, I know. To summarize: I'm not sure we should continue this discussion, because > I don't see where is it going and what could it possibly change in > practice. I agree with the value of having all of that documented, > I'm just saying it's a large job that needs dedicated individuals, and > I don't see how that could be replaced by any semi-automated means. > I was surprised my off-the-cuff remark about trawling the archives generated any response in the first place, to be honest. One thing (I think) some of those OSS IDE projects do well is eat their own dogfood in terms of features for projects/documentation/collaborative development models generally. AFAICT, Emacs has support (either in core or in non-core packages) for a lot of different tools/approaches/etc to these issues, but doesn't seem to take advantage of them for emacs development itself, beyond the integrated bug reporting and version control systems. There's support for all these project formats and tags - why isn't there a standard choice of those imposed on the emacs projects itself, e.g. with a centralized repo of pre-generated tags and auto-generated extraction of documentation/data structure definitions? Maybe I just haven't read that section of the manual or the right document in "etc" yet - I freely admit my ignorance. As it is, I've just assumed that the core maintainer(s) have weighed the trade-offs and decided imposing that kind of constraint, even among the core maintainers, would cost more than it is worth (in attracting contributors and maintainers). If there was an "emacs-devel" mode where the tags (and files would be tags considered as entries in a directory "document") linked to a database cross-referenced with the feature database, the VC logs, and a wiki-ish interface that could record both documentation and "talk". Sort of like "help" mode, but with a wikipedia-ish feel. The contributors to that piece of code and maintainers covering the related features would be auto-subscribed to the entry, and any discussion would at least get recorded in a way linked to the thing being discussed. I'm not sure contributors would want to be auto-subscribed like that, but then maybe their contribution should be reviewed by someone who would be. It's just an idea - whether it's useful or practical for the purpose of facilitating the recruitment of new contributors/maintainers, given that some culture change would likely be required, is not something I have the perspective to judge. I do know I would find something like what I've described very useful. Lynn --0000000000008e77ca05e2487d6e Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable


=
On Fri, Jun 24, 2022, 2:54 AM Eli Zar= etskii <eliz@gnu.org> wrote:
> From: Lynn Wineb= arger <owinebar@gmail.com>
>=C2=A0
> > > It would help if there were some taxonomy of features/design=
> > > points for
> > > reference.=C2=A0 Is the bug database being used for that? > >
> > I don't think so (IIUC what you mean by that), and I don'= t really see
> > how bugs could serve in that role.
>
> I agree, but some of the bug reports are classified as something along=
> the lines of "feature request" or "wishlist".

If you look at those, you will see that almost all of them request
minor features that have no impact on the design whatsoever.=C2=A0 It is very rare to have a feature request on the bug tracker that changes
the design or introduces new designs.=C2=A0 I would even dare to say it
never happened, definitely not on my watch.



> I haven't found any other database tracking anything corresponding=
> to features, proposed or otherwise.

We do have etc/TODO.=C2=A0 Did you look there?
=

Yes, but it's not indexed= so there's no good way to reference particular items the way bugs are.=


> Once something is in place, no matter how bare-bones, the key would be=
> maintainers mandating that any substantive introduction or revision of=
> features be tied to appropriate entries for the corresponding
> design/spec documentation, in the same way and for the same reason
> coding standards are enforced.

I think you are greatly underestimating the efforts required to
maintain documentation of this kind, let alone the effort for creating
it basically from scratch.
I just have a lot of sympathy for the points you = made in that portable dumper thread, regarding the cost of accepting substa= ntial contributions from transitory contributors.
An= yone can create a new feature or improvement and maintain their own variant= , but it's a lot easier for them if the project takes over maintenance = and breaking it becomes a rejection test for future changes.
Everything you say below is sensible.=C2=A0 You and the other (cu= rrent and future) core maintainers are the ones who have to make the trade-= off, after all.=C2=A0 I'm going to add some comments below, though, bec= ause I think my perspective on what is useful is different.=C2=A0 If they a= re obvious or too idiosyncratic to be useful in the context of attracting n= ew contributors/maintainers, feel free to ignore them.=C2=A0=C2=A0

Programmers usually don't like writing documentation, and most of them<= br> cannot write good documentation even if they did want, in large part
because that take years of practice actually doing it.=C2=A0 In a project like Emacs, it is nigh impossible to force contributors and developers
do what they are reluctant to do in the first place.=C2=A0 Without everyone=
updating the documentation as they change code, any documentation
about design and internals will quickly become outdated, and thus not
just useless, but downright harmful.=C2=A0 We have trouble keeping even our=
user documentation up-to-date.

Is it harmful?=C2=A0 I suppose it depends on = who's relying on it.=C2=A0 Diving into the source of a project with Ema= cs's complexity with a particular design change in mind,=C2=A0 personal= ly I prefer to have some guideposts knowing that they may be dated, then as= k knowledgeable people if there seems to be a disagreement between the doc = and the code.=C2=A0 When that happens on a public forum like this list, the= n there's some reference.

It's true, I have a low bar.=C2=A0 It might not seem like it, but= my preference is to explore a question as much as I can on my own before b= othering the experts.=C2=A0 In the best case, the question that stumps me a= lso stumps the expert - then I know I've done adequate study.=C2=A0 =C2= =A0With Emacs (and often other free software projects), it's just hard = to tell what I should be responsible for studying prior to asking questions= .=C2=A0 Beyond the code itself, of course.


<= blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px= #ccc solid;padding-left:1ex">Are you aware of _any_ Free Software project = that has any useful
documentation of this kind?=C2=A0

I know some "Open Source" projects = (eg chromium) that have useful docs.=C2=A0 Also projects with academic root= s (Larceny Scheme is still my go-to) tend to have them.=C2=A0 I'm assum= ing that in this context, the OSS projects, at least, are not "Free So= ftware project[s]" in the sense you intended, even if the software pro= duced by those projects happens to be Free.=C2=A0=C2=A0
I don't do development for a living, so when I first looked into th= e code of those corporate projects, the general culture around demanding un= iformity of build systems and supported configurations was quite a culture = shock after being accustomed to the approach of Free Software projects.=C2= =A0 So I'm assuming you intend to refer to projects that have freedom a= s an organizing principle, and hence exhibit a self-selection bias toward d= iverse and idiosyncratic preferences and goals among their contributors.=C2= =A0 Or something along those lines?

Every= project I ever knew or was involved
with which tried ended up abandoning that.=C2=A0 A case in point is GDB, which once had a "GDB Internals" manual -- it was always outdated= , and
was eventually scrapped because the maintainers decided they could not
and didn't want to invest the effort.=C2=A0

I remember thinking it was a sha= me.=C2=A0 But, my bar for usefulness is fairly low.
=
XEmacs tried in its time to
have the internals documented, but that was basically a one-man
effort, and even in it whole chapters were never written.=C2=A0 Etc. etc.
I think there's some conclusion waiting here.

I think we have different problem scope= s in mind.=C2=A0 I'd take some kind of indexed wiki as a substantial im= provement, particularly if there were links between tags in the code as wel= l as files and directories cross-referencing features and VC logs, with the= primary archive of discussion happening there rather than an email list (a= s with discussion around bugs).=C2=A0 I'd just like to be able to deter= mine answers to questions like:=C2=A0 why is preventing the allocation of l= isp objects by mmap necessary?=C2=A0 What purpose does ralloc.c serve?=C2= =A0 Do they still serve a purpose?, and know whether I've done enough s= elf-study to justify asking the experts.

<= div dir=3D"auto">
= > That's assuming the maintainers consider such documentation
> important enough for enabling future potential contributors and
> maintainers to hold otherwise useful contributions in limbo.

And you think we don't?=C2=A0 Of course we do!=C2=A0 We also want to re= lease
Emacs much more frequently, and we want it to have no bugs, and a few
other things.=C2=A0 But somehow, each such goal cannot be reached for some<= br> boring practical reasons, none of them related to their importance in
our eyes.

I did not mean to imply you d= on't consider them important (I can see it might read that way).=C2=A0 = I meant "important enough [relative to all the competing priorities]&q= uot;.=C2=A0 I don't know of any other way of expressing importance exce= pt relative to competing priorities subject to resource=C2=A0constraints.= =C2=A0=C2=A0
=C2=A0
We do in= general consider it somewhat more important to develop Emacs
and accept contributions than to document its internals, that's true. Which is why I said up-thread that without someone who'd volunteer to do this job (thus dedicating his/her time almost exclusively to it),
this will probably never happen, given the current state of our
resources, which are barely enough to maintain the status quo and move
forward at some reasonable pace.

> >=C2=A0 Most of the design changes and
> > redesigns in Emacs were developed without any bug report, simply<= br> > > because those who did the job knew that a particular group of pro= blems
> > needs to be taken care of.
>
> It's not like there isn't any discussion or justification of f= eatures
> offered prior to code being integrated into the main branch. It's = more
> a challenge of how to weave what's there into a coherent account o= f
> what's going on in the code.

IME, you are wrong in that assumption.=C2=A0 The significant changes in
Emacs design are almost never publicly discussed, not in the way that
would allow someone to glean the design from them.
Then,=C2=A0 I should=C2=A0understand Daniel Colascione's ap= proach with the portable dumper preview thread and the more recent one on a= revised gc are either outliers - or that I'm misreading their scope re= lative to the discussion of design issues they provide? [ That's a stra= ight question to resolve my ignorance, not intended to be snarky. ]=C2=A0 = =C2=A0

> It would jus= t be easier to automate some sort of design note
> extraction from the git log if references to mails could be associated=
> with relevant features.=C2=A0 I've never used org, but maybe there= 's some
> syntax that would be useful?=C2=A0 Or maybe some notation from superci= te
> for precise pulling of relevant text from list archives?

I wish this were true.=C2=A0 It isn't.=C2=A0 The discussions and the co= mmit log
messages rarely describe the design, and in many cases barely describe
even the particular implementation.=C2=A0 In a project where people with write access can commit changes without any review, I don't know how can anything else to be expected.=C2=A0 We basically rely on each
individual to do the job perfectly and contribute to what you want to
see documented.=C2=A0 The results are before our eyes, and they shouldn'= ;t
surprise anyone.

True enough.=C2=A0 =C2= =A0=C2=A0
=C2=A0

> > > https://github.com/rocky/elisp-byte= code
> > > That is really useful documentation that would ideally be in= the emacs docs
> > > or etc directory.
> >
> > That's not design description, though.
>
> You probably have a more nuanced view than me on this.=C2=A0 It's = true,
> that document is focused on the specification (the "what") r= ather than
> the (detailed) "how" and "why" - is that what you = mean?

Of course.

> Either way, if you want to understand how the operational semantics > of emacs lisp work in practice, a document of that sort is
> invaluable.=C2=A0 Without that, a document explaining the "why&qu= ot; isn't
> going to be able to be very concrete.

I agree, but the "what" is usually already available in the comme= nts
to the code, though not everywhere and for every significant feature.
The "why" and "how", by contrast are almost completely = missing.

In the particular case of the = bytecode spec, at least it gives me the sense of the invariants that are be= ing maintained by the implementation.=C2=A0 Trying to reverse engineer what= those invariants are from a giant C switch statement is always tricky, bec= ause they tend to be expressed with boilerplate code, and then sometimes yo= u have clever use of the fact that cases are non-exclusive and "fall t= hrough" without an explicit break, etc.=C2=A0 =C2=A0That's where i= t intersects with "design" for me.

OTOH,= the same switch statement could be written as a dispatch table of higher-o= rder functions exploiting proper tail-recursion in a way I would feel comfo= rtable enough with to not feel the need to lean on a spec.=C2=A0 But that a= ssumes those higher-order functions clearly express the invariants they imp= ose.=C2=A0 It's a personal preference, I know.

To summarize: I'm not sure we should continu= e this discussion, because
I don't see where is it going and what could it possibly change in
practice.=C2=A0 I agree with the value of having all of that documented, I'm just saying it's a large job that needs dedicated individuals, = and
I don't see how that could be replaced by any semi-automated means.
=

I was surprised my off-the-cuff remark abo= ut trawling the archives generated any response in the first place, to be h= onest.

One thing (I think) some of those OSS IDE p= rojects do well is eat their own dogfood in terms of features for projects/= documentation/collaborative development models generally.=C2=A0 AFAICT, Ema= cs has support (either in core or in non-core packages) for a lot of differ= ent tools/approaches/etc to these issues, but doesn't seem to take adva= ntage of them for emacs development itself, beyond the integrated bug repor= ting and version control systems.=C2=A0 There's support for all these p= roject formats and tags - why isn't there a standard choice of those im= posed on the emacs projects itself, e.g. with a centralized repo of pre-gen= erated tags and auto-generated extraction of documentation/data structure d= efinitions?=C2=A0 Maybe I just haven't read that section of the manual = or the right document in=C2=A0"etc" yet - I freely admit my ignor= ance.=C2=A0 As it is, I've just assumed that the core maintainer(s) hav= e weighed the trade-offs and decided imposing that kind of constraint, even= among the core maintainers, would cost more than it is worth (in attractin= g contributors and maintainers).

If there was an &= quot;emacs-devel" mode where the tags (and files would be tags conside= red as entries in a directory "document") linked to a database cr= oss-referenced with the feature database, the VC logs, and a wiki-ish inter= face that could record both documentation and "talk".=C2=A0 Sort = of like "help" mode, but with a wikipedia-ish feel.=C2=A0 The con= tributors to that piece of code and maintainers covering the related featur= es would be auto-subscribed to the entry, and any discussion would at least= get recorded in a way linked to the thing being discussed.=C2=A0 I'm n= ot sure contributors would want to be auto-subscribed like that, but then m= aybe their contribution should be reviewed by someone who would be.

It's just an idea - whether it's useful or practi= cal for the purpose of facilitating the recruitment of new contributors/mai= ntainers, given that some culture change would likely be required, is not s= omething I have the perspective to judge.=C2=A0 I do know I would find some= thing like what I've described very useful.

Ly= nn

--0000000000008e77ca05e2487d6e--