Re: fontsets/charsets documentation suggestion

[Eric Abrahamsen <girzel@gmail.com>]

On Jul 2, 2009, at 12:15 PM, Eli Zaretskii wrote:

>> From: Eric Abrahamsen <girzel@gmail.com>
>> Date: Wed, 1 Jul 2009 23:19:51 -0700
>>
>> 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.
>
> This is in the manual, see the node "Character Sets" and maybe the
> other nodes from its parent "Non-ASCII Characters", if you need more
> background.
>
> If something is missing or unclear, please post more specific gripes.

Hmm, I wonder if this is part of the problem. Section 26 of my Emacs  
Info file is 'International Character Set Support', and everything  
relevant seems to be under this heading. I don't see a 'Character  
Sets' or a 'Non-ASCII Characters' node. There's no index entry for  
'registry', neither does a grep of the info files for 'registry'  
produce any definition of the word as related to fonts. Am I looking  
in the wrong place? (I'm using a CVS build on Mac OSX, the ns  
Emacs.app version.)

>
>> 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*.
>
> Can you give a list of use-cases for which you'd like to have
> examples, and/or point out what is unclear or insufficiently detailed
> in the "Fontsets" node of the manual?

The existing examples would be clear if I'd gone into it actually  
understanding the difference between a charset, a script and a  
registry, and knowing which variables contained the possible values  
for each of these three concepts. My particular use-case was defining  
specific fonts for English/Latin, Chinese and Thai, and I did not  
understand where 'han' came from, and its relationship to 'chinese- 
gb2312' (I have since been directed to charset-script-alist). If I'm  
actually missing a chunk of the documentation this would be better.

There aren't any examples of using create-fontset-from-fontset-spec,  
and it would be nice to see one or two. The documentation for the  
function is technically correct, I'm sure, but is the kind of  
documentation that's only useful if you already understand how it  
works. Neither 26.15 Defining Fontsets nor the documentation say how  
you actually employ a fontset once you've made it. This has got to be  
one of the most complex areas of Emacs customization, and it would be  
nice to err on the side of too much hand-holding.

Thanks for your response, and I do hope that I'm just missing  
something...

Eric