Re: Opaque objects and Emacs documentation

[Eli Zaretskii]

> From: John Yates <john@yates-sheets.org>
> Date: Fri, 17 Jul 2020 12:56:52 -0400
> Cc: Emacs developers <emacs-devel@gnu.org>, Dmitry Gutov <dgutov@yandex.ru>
> 
> I have used emacs for nearly 30 years but have rarely ventured into elisp 
> development much
> beyond maintaining my .emacs.  So I look to emacs documentation as a user, 
> not a developer.
> 
> OTOH I have been programming for just shy of 50 years.  Over that time I have 
> continually
> increased the size and scope of projects I could tackle primarily by looking 
> for ways to
> build and compose ever better abstractions.  Sometimes that has taken the 
> form of adopting
> a new programming language, sometimes a new methodology or disciple.
> 
> Conversely, one of the banes of my existence has been leaky abstractions.  
> For better
> or worse, based maining on the untyped nature of lisp and its culture of 
> describing how
> to interpret structures of various shapes, my overriding impression of the 
> lisp world in
> general and of elisp in particular is that they are rife with leaky 
> abstractions.
> 
> I commend Dmitry's desire to provide an opaque abstraction for a project.  
> Sadly, in
> this instance I suspect that such an effort is an attempt to swim against an 
> impossibly
> strong tide.  (If you cannot beat them, join them :-)

The issue at hand is not whether or not to use the abstractions.
Rather, it is how to use abstractions in a way that doesn't prevent
good documentation.