Ben> Or can you suggest any other way to repartition the info Ben> currently split across `make-glyph', `make-image-specifier', Ben> `make-image-instance', `set-glyph-property', Ben> `specifier-instance', etc.? We've been going around this bush with David since 2001 without much progress. We have added a fairly extensive tutorial example and somewhat reorganized the docs to no avail for him, although others have commented on the improvement. If you want to help David specifically, the best bet is to implement the GNU image API, and be prepared for preview-latex, AUCTeX, and x-symbol to find all the places where the emulation doesn't match the originals. This would probably make XEmacs somewhat more popular with all of the applications that use images. -- Institute of Policy and Planning Sciences http://turnbull.sk.tsukuba.ac.jp University of Tsukuba Tennodai 1-1-1 Tsukuba 305-8573 JAPAN Ask not how you can "do" free software business; ask what your business can "do for" free software.

"Stephen J. Turnbull" <stephen(a)xemacs.org&gt; writes: Sigh. You are mixing up things here. My complaints in 2001 were about the general lack of documentation of the mechanisms all in all. My complaint now was about the doc string of a particular function. The doc string of a particular function is not the place to explain, say, what a specifier or locale is, though it may be a good idea to mention a set of possible values to ease usage. But the doc string of a particular function should contain what is particular to this function. In this case I was asking for documentation what set of values can be returned (where "returned" can also imply throwing an error). Namely something like "can return a glyph specifier or nil", or "will return a glyph specifier or thrown an error". If you bothered reading my reports instead of just crying "it is David again, let us all bash him", then that would be great, thank you. If you want to help XEmacs specifically, the best bet is not bashing contributors every time they point out some small thing which they think could need improvement. I have by now reached the state where I find it one of the most unpleasant things when I find that I need some help or advice or should report a problem with XEmacs, because I know that half of the XEmacs bigwigs will start bashing me the moment I open the mouth, mostly unconnected to what I am trying to report. This bug report was _not_, I report _not_ about choice or documentation of the general image API. I did not even look at that, and it is irrelevant to the report. The report was about a very simple shortcoming of the doc string of a single function. No, I don't expect this function to explain the whole image framework of XEmacs. That's what the Lispref manual is for. But regardless of what the doc string chooses to explain or not, what the function does as opposed to other functions belong in there. And the set of return values/semantics are part of that, just as the set of arguments are. What is so fscking hard about "can return a specifier or nil" or "will either return a valid specifier or throw an error"? Is it really impossible to get off your damn high horse and when having a simple deficiency pointed out to just say "Thanks for reporting this oversight. Fixed." (that's the way things tend to happen with Emacs most of the time) instead of first telling me that I am stupid ("it doesn't take an Einstein") for not finding that information somewhere scattered around elsewhere, that nobody would want to have this information anyhow, then going into rants complaining that I have previously reported a problem in seemingly offending ways and so should not be entitled to report another one without getting sarcastic remarks all over the board? What is eating you people? Is it really impossible to simply report a problem without getting bashed to pieces or ignored every fscking single time? -- David Kastrup, Kriemhildstr. 15, 44793 Bochum

"Stephen J. Turnbull" <stephen(a)xemacs.org&gt; writes: I asked about the return semantics. To quote: Namely: what happens if the specifier refers to image files that are not existent, that are broken, or that are in a format that XEmacs does not support? Does make-glyph return nil? Does it return a glyph that later triggers some error when being used? Does make-glyph throw an error itself? At what point of time do :file ... and similar properties actually get evaluated? In short: what does make-glyph return or throw under what basic error conditions? Maybe this question was to broad. But the fact remains that the make-glyph doc string does not mention what gets returned. It says that the function creates a glyph, period. It does not even say that this glyph is the return value of make-glyph. And it does not say whether I can rely on the return value being a glyph. In 160+ lines of (very appreciated) comment. In contrast, a somewhat corresponding Emacs function (though much less powerful) is documented as create-image is a compiled Lisp function in `image'. (create-image FILE-OR-DATA &optional TYPE DATA-P &rest PROPS) Create an image. FILE-OR-DATA is an image file name or image data. Optional TYPE is a symbol describing the image type. If TYPE is omitted or nil, try to determine the image type from its first few bytes of image data. If that doesn't work, and FILE-OR-DATA is a file name, use its file extension as image type. Optional DATA-P non-nil means FILE-OR-DATA is a string containing image data. Optional PROPS are additional image attributes to assign to the image, like, e.g. `:mask MASK'. Value is the image created, or nil if images of type TYPE are not supported. That is all. Notice the last sentence? And no, I did not actively dig through the functions from XEmacs and Emacs, noticed that here was a single case where I could make fun of you and reported it in shere spitefulness. And I did not check that there was an Emacs function I could mention later that just happened to mention the return value. Whatever. What does the function return, never mind the error cases? In short, do I have a guarantee that whatever it returns (when not throwing an error) can be used as a glyph specifier later on? If you refuse to say what the function can return, then it is impossible to guess when and where a program might fail or react surprisingly. Calling me "not an Einstein" for not figuring out that what make-glyph will return should rather be gleened from the doc string of another function mentioned in passing. Yup, in rather different ways. I am still of the opinion that a function should document its return value. In any form or extent you desire, but it should at least say _anything_ about it. And make-glyph does not. Not a single word. One can guess that it will return the glyph that it creates. _If_ it creates one. And you'll tell me it would not take an Einstein to guess that, I suppose. But documentation strings are not supposed to be an IQ test. In the time you took bashing me in this thread, you could have added a single sentence about what make-glyph returns 20 times over. Somebody asked in comp.emacs.xemacs recently whether XEmacs was dead and he should switch over, and I told him thanks, we have enough trolls of our own. But he does have a point. I won't cede it publicly, since you are perfectly capable of shooting yourself in your own foot and I should leave the business of killing XEmacs to you, but he has a point. The amusing thing is that for the average XEmacs developers, I am pretty much synonymous with Stallman because of my ravings. Nobody gets the small difference, namely that Stallman is mad at the XEmacs developers for not killing it off, and I am mad at the XEmacs developers for killing it off. When the developers see their main task in explaining why XEmacs is perfect instead of accepting even the most basic suggestions for improvement, it is effectively dead. Since it stops catering for its users unless they are developers, too. The usual reaction on the Emacs list for a report of documentation somebody did not understand is incredibly long-winded and partly aggravating bickering _between_ half a dozen developers about just what wording should be most clear. And the usual reaction on the XEmacs list at least for me has been rather uniformly incredibly long-winded and partly aggravating bickering _from_ half a dozen developers about why there is no need to change anything. -- David Kastrup, Kriemhildstr. 15, 44793 Bochum