[V] Update the docstring for make-char

[Aidan Kehoe]

 Ar an naoú lá déag de mí na Samhain, scríobh Stephen J. Turnbull: 

 >  > Certainly in the character set standards, but not _in the arguments to
 >  > the function._ Which is the most important thing for the docstring to
 >  > describe.
 > 
 > True.  In the argument to the function, they're actually 31-bit signed
 > integers, which will be and'ed with 0x7F, then shifted into a 30-bit
 > unsigned quantity.  How you get 7-bit unsigneds out of that, I don't
 > know. :-)

I call them integers in the patch, I don’t specify their size. Calling them
octets says ‘we are treating them as eight bits’--just as the term is used
in the networking RFCs--and that is false.

 >  > Seven bits are not an octet, and up to now we’ve only mentioned that
 >  > we treat the arguments as seven bits in the examples, and we’ve never
 >  > stated it explicitly.
 > 
 > The calculation using arithmetic `and' is an optimization; the intent
 > is that the code point arguments may be in the range 0x00-0xFF, ie,
 > they are octets which will be interpreted as the GR register in either
 > a 7-bit code or an 8-bit code. 

Uh-huh. I knew that, but it’s not currently explained in the docstring.
Whence my patch. 

 > Outside of that range it is an error (although we actually don't detect
 > and signal it).

That is, it’s not an error, in any real sense of the word.

 >  >  > Also, the editorial commentary, such as references to the
 >  >  > unfortunate difference from MIME, doesn't belong in docstrings. 
 >  >  > Docstrings should explain how to use the function to somebody who
 >  >  > already knows how XEmacs works, not try to explain how XEmacs
 >  >  > works.
 >  > 
 >  > ?!???! I’m really surprised to see that from you. Why would anyone
 >  > need to read the docstring of make-char if they already knew how
 >  > XEmacs worked in this aspect of things? The argument list would
 >  > suffice.
 > 
 > Indeed.  Examples of the arguments, and the fact that a character from
 > a unibyte set has only two arguments while a double byte set has
 > three; 

which is not 100% obvious only because this is Mule and an insane
alternative is entirely possible, and is exactly what’s done in CCL. But the
uninformed user won’t know that. 

 > explanation of the fact that the arguments are ISO-ized values
 > in the range 32-127 and not ku-ten values in the range 1-96, etc, are
 > appropriate.  Explanation of the difference between coding systems and
 > charsets is not.  Someone who is working with Mule code had better have
 > studied a lot more than just the docstrings! 

That barrier to entry is part of why so few people are working with Mule
code!

 > Also, since many MIME charsets have all kinds of junk (modality) in them
 > that is not at all set-like, the XEmacs usage is more intuitive, though
 > less familiar.

“Less familiar” _means_ “less intuitive.” 

 > What's unfortunate is that MIME doesn't follow XEmacs's usage!

Given MIME’s mindshare, putting it like that will read as insufferable to
the outsider.

 >  > There was a similar discussion on the philosophy of doc strings
 >  > over at:
 > 
 > I don't know if that is the one I participated in, but I've been in
 > such threads.  My position is that anything that helps the user format
 > the arguments and use the result correctly can go into the docstring,
 > which includes the domain and range of the function, usage examples,
 > invariants it satisfies, etc.  I see no reason why the text of a
 > docstring can't go directly into the manual, and the labor saved is a
 > strong justification for writing docstrings in manual style.  But the
 > general design philosophy of abstract types and the data structures
 > that implement them should be reserved for the manual.  

F1 f cons RET (and I will veto you taking the explanations out!):

`cons' is a built-in function
  -- loaded from "/home/aidan/xemacs-21.5/src/alloc.c"
(cons CAR CDR)

Documentation:
Create a new cons cell, give it CAR and CDR as components, and return it.

A cons cell is a Lisp object (an area in memory) made up of two pointers
called the CAR and the CDR.  Each of these pointers can point to any other
Lisp object.  The common Lisp data type, the list, is a specially-structured
series of cons cells.

The pointers are accessed from Lisp with `car' and `cdr', and mutated with
`setcar' and `setcdr' respectively.  For historical reasons, the aliases
`rplaca' and `rplacd' (for `setcar' and `setcdr') are supported.


 > The GNU style
 > as I understand it would rule out examples and invariants and things
 > like that.

-- 
Santa Maradona, priez pour moi!