Re: Larger GC thresholds for non-interactive Emacs

[Lynn Winebarger]

On Thu, Jun 23, 2022 at 2:37 PM Eli Zaretskii <eliz@gnu.org> wrote:
>

> What you describe is a full-time job, more or less.  I'd love to have
> someone who'd volunteer to record all those points, but we don't have
> him/her yet.
>
> The only places where design is document are the large comments in
> some source files.
>
> > 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".  I haven't found any
other database tracking anything corresponding to features, proposed
or otherwise.  In more formal environments, feature implementation
would be preceded by some kind of ticket describing the problem to be
solved or functionality to be implemented.  I don't expect any
strictly enforced workflow in this kind of project, but that kind of
referent is still useful for the same reasons having an entry in a bug
database to reference is useful.

A crude taxonomy wouldn't be that hard to come up with, then
elaborated with finer points:
   Value Representation
   ELisp Abstract Machine
   Memory Management
   Intermediate Representations
      Core Lisp
      Lisp Assembly
      LIMPLE
   Compiler Transformations
   Serialized Lisp Program Formats
        ELC
        ELN
        PDMP
   etc
Some of these points are already documented in the Elisp manual, of
course, and some in the code comments, and others in the emacs-devel
archives.

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.  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 probably that doing so is convenient to
do.

>  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.

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 feel like if I were a more savvy Emacs user, I would know all of
this functionality is already implemented in some combination of
CEDET-originated tools, one or more tagging systems, the various
interfaces for using the tagging systems, org, etc.

>
> > Actually, a good example (even though it's more post facto description than
> > prospective
> > design & cost-benefit tradeoff analysis) would be
> > 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?  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.