Technically correct or conceptually easier?

Technically correct or conceptually easier?

[Bruno Félix Rezende Ribeiro]

[-- Attachment #1: Type: text/plain, Size: 4065 bytes --]


Hello folks,

I’d like to hear your thoughts on documentation that is (hopefully)
understandable, but technically inaccurate or even false.  The sort of
documentation for which correct interpretation depends on having "common
sense", whatever that means.

The form (describe-variable 'inhibit-read-only) gives:

  inhibit-read-only is a variable defined in ‘C source code’.
  Its value is nil

  Documentation:
  Non-nil means disregard read-only status of buffers or characters.
  If the value is t, disregard ‘buffer-read-only’ and all ‘read-only’
  text properties.  If the value is a list, disregard ‘buffer-read-only’
  and disregard a ‘read-only’ text property if the property value
  is a member of the list.

The first sentence of the documentation says:

  Non-nil means disregard read-only status of buffers or characters.

OK.  And what nil means?  I guess the omission of its meaning implies
its meaning is the exact opposite of the one given to a non-nil value;
and apparently this conjecture can be factually verified by
experimentation.

It seems to me that this kind of omission is common throughout the Lisp
documentation, being perhaps an implicit once-stated convention to avoid
redundancy.  This would be a gap filled by the "if, and only if,"
expression (a.k.a. iff or logical equivalence).  Yet the Lisp reference
manual suggests:

   • Avoid using “iff” (a mathematics term meaning “if and only if”),
     since many people are unfamiliar with it and mistake it for a typo.
     In most cases, the meaning is clear with just “if”.  Otherwise, try
     to find an alternate phrasing that conveys the meaning.

Fine.  Let that be.  This is not, however, the main problem I see with
the documentation of ‘inhibit-read-only’.  Its last sentence says:

  If the value is a list, disregard ‘buffer-read-only’ and disregard a
  ‘read-only’ text property if the property value is a member of the
  list.

Well, nil is a list.  Therefore, nil has not the opposite meaning of a
non-nil value for that variable --- what I’m sure is not what is meant,
otherwise it would be factually wrong.  If instead it were said:

  If the value is a *cons*, disregard ‘buffer-read-only’ and disregard a
  ‘read-only’ text property if the property value is a member of the
  *cons*.

That would be correct[1].  Nevertheless, I bet many people would find it
strange, specially because they tend to think of conses as ordered
pairs, and lists as something else --- downplaying their relationship as
a simple implementation detail.[2] Some people could argue that the use
of *cons* in that case was just an artificial (dirty) trick to exclude
nil and dodge the burden of explaining better.

This is an instance of the general dilemma I’m trying to convey: is it
better do document things with conceptual rigor and technical
correctness and leave people somewhat astray until they build their
theoretical maturity or to write documentation in a simplistic manner
(little bit off truth) but that tend to make people with yet naive
understanding more secure of its meaning (and therefore more
productive)?[3]

As my background is mathematics, I guess people may see what I’m
inclined to think.  I’m interested, though, on your view of this
subject.  What do you think?


Footnotes: 

[1] For the usual definition of membership, given by the ‘member’
function.  This is worth noting here because people could understand
(inconsistently) that membership for conses is something else entirely:

  (defun member-cons (elt cons)
    (or (equal elt (car cons))
        (equal elt (cdr cons))))

[2] A view that for Lisp I regard not only as inelegant but incorrect as
well.

[3] Albeit not instigating their growth nor expanding their view on the
complexity of the subject for the lack of conceptual puzzles or
surprises.

-- 
Bruno Félix Rezende Ribeiro (oitofelix) [0x28D618AF]
<http://oitofelix.freeshell.org/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 454 bytes --]

Re: Technically correct or conceptually easier?

[Stefan Monnier]

> The first sentence of the documentation says:
>
>   Non-nil means disregard read-only status of buffers or characters.
>
> OK.  And what nil means?  I guess the omission of its meaning implies
> its meaning is the exact opposite of the one given to a non-nil value;
> and apparently this conjecture can be factually verified by
> experimentation.

Yes, we often rely on the abuse of "if" to mean "if and only if".
Usually those abuses allow for less verbose text, so there's
a trade-off.  I think here the trade-off is worthwhile.  At some other
places we correctly add an explicit mention of what happens if it's nil.
And of course at yet other places we made the wrong call :-(

>   If the value is a list, disregard ‘buffer-read-only’ and disregard a
>   ‘read-only’ text property if the property value is a member of the
>   list.
>
> Well, nil is a list.

I think this case is a documentation error: it should say "a non-empty
list", although admittedly, the context makes it clearish what is meant.


        Stefan "who likes `iff`"

Re: Technically correct or conceptually easier?

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

    > Non-nil means disregard read-only status of buffers or characters.

It follows that nil means don't disregard that.

In general, if

    > Non-nil means do X

then nil means do things the usual way, and t means do X instead of
the usual way.

This practice makes hundreds of doc strings more succinct.  I don't
think that making them longer would be an improvement.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Technically correct or conceptually easier?

[chad]

[-- Attachment #1: Type: text/plain, Size: 1348 bytes --]

As a practical matter, could this specific instance be addressed by
something like "...if the value is a (non-nil) list, ...."?

On Thu, Apr 2, 2020 at 2:22 PM Stefan Monnier <monnier@iro.umontreal.ca>
wrote:

> > The first sentence of the documentation says:
> >
> >   Non-nil means disregard read-only status of buffers or characters.
> >
> > OK.  And what nil means?  I guess the omission of its meaning implies
> > its meaning is the exact opposite of the one given to a non-nil value;
> > and apparently this conjecture can be factually verified by
> > experimentation.
>
> Yes, we often rely on the abuse of "if" to mean "if and only if".
> Usually those abuses allow for less verbose text, so there's
> a trade-off.  I think here the trade-off is worthwhile.  At some other
> places we correctly add an explicit mention of what happens if it's nil.
> And of course at yet other places we made the wrong call :-(
>
> >   If the value is a list, disregard ‘buffer-read-only’ and disregard a
> >   ‘read-only’ text property if the property value is a member of the
> >   list.
> >
> > Well, nil is a list.
>
> I think this case is a documentation error: it should say "a non-empty
> list", although admittedly, the context makes it clearish what is meant.
>
>
>         Stefan "who likes `iff`"
>
>
>

[-- Attachment #2: Type: text/html, Size: 1799 bytes --]

Re: Technically correct or conceptually easier?

[Bruno Félix Rezende Ribeiro]

[-- Attachment #1: Type: text/plain, Size: 1085 bytes --]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>>   If the value is a list, disregard ‘buffer-read-only’ and disregard a
>>   ‘read-only’ text property if the property value is a member of the
>>   list.
>> Well, nil is a list.
> I think this case is a documentation error: it should say "a non-empty
> list", although admittedly, the context makes it clearish what is meant.

Fair enough.  Albeit ~(and (not null) list)~ and ~cons~ are the same
class of Lisp objects, perhaps the former appeals more to /intention,
intuition or common sense/ (and thus maybe it’s more appropriate for a
docstring)[1] than the latter --- even if formally more complex.


Footnotes: 

[1] Although I’m inclined to think that in situations like this, if the
very same objects are seem as somewhat distinct things because of
different (but equivalent) descriptions, the problem is with the human
understanding and bias towards reality: distinction without a
difference.

-- 
Bruno Félix Rezende Ribeiro (oitofelix) [0x28D618AF]
<http://oitofelix.freeshell.org/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]