bug#11440: E-Lisp manual - customization

bug#11440: E-Lisp manual - customization

[Andrew Kurn]

> 
> (In E-Lisp) I find myself confused by the treatment of Customization and Faces . . .
> 
> I find the chapter in the E-Lisp manual on /Customization/ problematic.  It seems
> to be directed at the user-level and not programmer-level.
> 
> Ideally, it should start out by saying what a customization is actually before
> it ever gets around to defining "Common Keywords" and other ad-hoc machinery.
> So, the first paragraph of the chapter should have a careful definition with
> links to the thingies that a customization is made of or works on.
> 
> I would like a link to "user options" at least, and one to self-quoting
> variables (eg :slant) would help.
> 
> ---
> 
> Please tell me when customization takes place.  Faces seem to be
> synthesized from customization data magically, in some way beyond
> my control.
> 
> 
> ---
> 
> Similarly, the section /Faces/ in /Display/.
> 
> I would start with /Attribute Functions/, so that the machinery that
> does the work is exposed, then /Standard Faces/ and /Face Attributes/
> so that we see what the machinery works on, then /Defining F/, which
> is customization, and attempts to insulate programmers from making
> mistakes.
> 
> Inserting customization too early makes the exposition confusing,
> makes it hard to see what is fundamental.  The mistake I made was modifying
> the customization properties of faces, rather than the faces themselves.
> 
> (In my present mood, I would remove customization from Emacs completely,
> although I can imagine some would be upset.  Still, I wonder what its
> real value is, how many actually need it and use it.)
> 
> ---
> 
> That's my rant for today,
> 
> Andrew
> 
> 

bug#11440: E-Lisp manual - customization

[Chong Yidong]

Andrew Kurn <kurn@sfu.ca> writes:

> I find the chapter in the E-Lisp manual on /Customization/
> problematic.  It seems to be directed at the user-level and not
> programmer-level.
> 
> Ideally, it should start out by saying what a customization is
> 
> I would like a link to "user options" at least, and one to
> self-quoting variables (eg :slant) would help.
> 
> Similarly, the section /Faces/ in /Display/.
> ...
> I would start with /Attribute Functions/

I've updated the manual to address most of these points.