bug#61325: 30.0.50; Jokes in GNUS manual

[Po Lu]

Ihor Radchenko <yantar92@posteo.net> writes:

> Po Lu via "Bug reports for GNU Emacs, the Swiss army knife of text
> editors" <bug-gnu-emacs@gnu.org> writes:
>
>>>> 3.16 Group Topics
>>>>
>>>>     If you read lots and lots of groups, it might be convenient to group
>>>>     them hierarchically according to topics.  You put your Emacs groups 
>>>> over
>>>>     here, your sex groups over there, and the rest (what, two groups or 
>>>> so?)
>>>>     you put in some misc section that you never bother with anyway.  You 
>>>> can
>>>>     even group the Emacs sex groups as a sub-topic to either the Emacs
>>>>     groups or the sex groups—or both!  Go wild!
>>>
>>> Thanks.
>>> I also partially understand the joke.
>>> My main problem is the last sentence, which I am not sure if it is
>>> technical or still part of the joke.
>>>
>>>     You can even group the Emacs sex groups as a sub-topic to either the
>>>     Emacs groups or the sex groups—or both!
>>>
>>> The paragraph structure is basically:
>>>
>>>  <technical description><joke><half joke, half technical description>
>>>
>>> Such structure is difficult to understand, especially if the joke itself
>>> is not understood.
>> ...
>>> Not when the jokes stay on the way of understanding the technical parts.
>>
>> They do not.  End of discussion.
>
> I kindly disagree. 3.16 Group Topics section was difficult to
> understand _for me_ precisely because of the jokes. I will elaborate
> below.
>
>> Where I come from, it is generally said that a person who deliberately
>> tries to find problems with something is trying to ``pick pricks''.
>> They are usually able to find some problems, because the problems they
>> report tend to, by definition, rely on their own testimony: ``I don't
>> understand'', ``I'm offended by'', etc.
>>
>> Such people generally ruin the day for everyone else wherever they
>> appear.
>
> Upon hearing about the problem and checking the specifically indicated
> sections in the manual, I tend to agree with the person being offended.
> Not because I am not offended (I am not), but because, as I stated
> earlier, I believe that jokes should not complicate the understanding.
>
>> Whoever reported the problem with the Gnus manual, which has not seen
>> other such reports in over 20 years, certainly sounds like one such
>> individual.  And if you don't understand the manual, then it is not a
>> problem with the jokes therein.  Just read it again until you do.
>> How many people can understand the following sentence without reading it
>> at least once or twice?
>
> Absence of bug reports does not imply that the manual is easy to
> understand. I do not say that it is incomprehensible, but the examples I
> pointed to do make it harder to understand. Won't it be an improvement
> to make the manual easier to understand for more people?
>
>>                          XcmsCIELabClipL
>>
>>   This brings the encountered out-of-gamut color specification into the
>>   screen's color gamut by reducing or increasing CIE metric lightness
>>   (L*) in the CIE Lab color space until the color is within the
>>   gamut. If the Psychometric Chroma of the color specification is beyond
>>   maximum for the Psychometric Hue Angle, then while maintaining the
>>   same Psychometric Hue Angle, the color will be clipped to the CIE Lab
>>   coordinates of maximum Psychometric Chroma. See
>>   `XcmsCIELabQueryMaxC'. No client data is necessary.
>>
>> Is color management, thus, an evil which should be persecuted by hordes
>> of crusaders?
>
> I do not see any problem with the provided paragraph. Yes, it contains a
> lot of unfamiliar terms, but they appear to be necessary to describe the
> technical information. In contrast, jokes do not convey any new
> information. They are good to have as an _occasional_ distraction - a
> break that may be necessary to simplify understanding; but not good when
> they make understanding more difficult.
>
> Imagine a joke inserted into your example, on top of all other
> unfamiliar terms:
>
>> This brings the encountered out-of-gamut (not gonad, mind you) color
>> specification into the screen's color gamut by reducing or
>> increasing (let's not think further) CIE metric lightness (L*) in the
>> CIE Lab color space until the color is within (mmm...) the gamut.
>
> Would you find it helpful or at least neutral to have these extra jokes
> when trying to understand the above sentence?

I didn't see ``let's not think further'' in the Gnus manual.  And no,
your additions do not make it harder for me to understand that sentence.