fontsets/charsets documentation suggestion

[Eric Abrahamsen <girzel@gmail.com>]

Hi,

Pursuant to this [1] thread on the carbon Emacs mailing list, I'm  
writing in with a small request regarding the documentation for  
fontsets in Emacs 23. I know that fonts, fontsets and charsets are one  
of the more complicated aspects of Emacs, but I think for this exact  
reason the documentation for fontsets and charsets should be beefed  
up. Everything in the current docs is correct, but it is such a  
complicated issue that I think a more basic, ramped-up (almost  
tutorial-style) approach would be very helpful, particularly for  
readers unfamiliar with the issue to begin with. In detail:

1. Clearer separation of Linux, Windows and Mac font issues – they  
seem to be very different.

2. A glossary. What is a charset, what is a font registry, what is a  
script name symbol, what is encoding and how are these things related?  
A ground-up explanation of the ecology of bytes, encodings, charsets  
and fonts would be great. Even, dare I say it, a diagram. This stuff  
is very confusing.

3. What are the relevant functions and variables? As a non-expert user  
of middling programming ability, I was totally baffled by set-fontset- 
font and all the possible permutations of its arguments. Likewise for  
create-fontset-from-fontset-spec. Since those two functions seem to be  
the weapons of choice for font manipulation, their descriptions could  
stand to be about four times as long as they are, with LOTS more  
examples. And when you're trying to get your fontsets right  
(particularly with multiple languages), you need to see lists of  
possible charsets and registries. These lists are in variables like  
charset-list and charset-script-alist which *aren't mentioned in the  
docs*.

4. I think describe-char is the main tool people use for examining  
characters. If that's the case, it would be nice to have clearer  
correspondences between the information that describe-char produces,  
and the information that set-fontset-font et al consumes. For  
instance, describe-char now seems to report all characters as either  
ascii or unicode-bmp -- this is less helpful when you're trying to  
target a font to latin or han, for instance.

That was it. Emacs 23 is enormously better at handling multilingual  
environments, but it would be even easier with more in-depth  
documentation!

Thanks,
Eric

[1] http://groups.google.com/group/carbon-emacs/browse_thread/thread/a919ee739fe7c9fd