Re: [V] Update the docstring for make-char
Aidan Kehoe writes:
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.:-)
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. Outside of that range it is an error
(although we actually don't detect and signal it). The original
motivation was convenience for those who think of the euro sign in
ISO-8859-15 as (make-char 'latin-iso8859-15 #xA4) rather than as
(make-char 'latin-iso8859-15 #x24).
Note that there's no way to do this with say KOI8-R; it only makes
sense with the ISO-8859 sets (and to some extent with the double-byte
EUC encodings of Asian sets. It really is intimately tied to the ISO
standards.
> 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; 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! 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.
What's unfortunate is that MIME doesn't follow XEmacs's usage!
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. The GNU style
as I understand it would rule out examples and invariants and things
like that.
_______________________________________________
XEmacs-Patches mailing list
XEmacs-Patches(a)xemacs.org
http://calypso.tux.org/cgi-bin/mailman/listinfo/xemacs-patches