[Bug: 21.4.16] make-glyph doc-string missing essential information
dak at gnu.org
Fri Feb 11 04:41:17 EST 2005
"Stephen J. Turnbull" <stephen at xemacs.org> writes:
>>>>>> "Ben" == Ben Wing <ben at 666.com> writes:
> >> Where exactly would you prefer that I put these two paragraphs?
> >> (i.e. if in the docs for `make-glyph', where?)
> 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.
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 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.
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
David Kastrup, Kriemhildstr. 15, 44793 Bochum
More information about the XEmacs-Beta