bug#6525: documentation of macro `with-silent-modifications' 1 typo + multi-horrid

[MON KEY]

On Wed, Jun 30, 2010 at 9:10 PM, Stefan Monnier
<monnier@iro.umontreal.ca> wrote:

>> ,---- (documentation 'with-silent-modifications)
>> |
>> | "Execute BODY, pretending it does not modifies the buffer.
>> | If BODY performs real modifications to the buffer's text, other than
>> | cosmetic ones, undo data may become corrupted.  Typically used
>> | around modifications of text-properties which do not really affect
>> | the buffer's content."
>> |
>> `----

> Docstrings should generally only document what the function/macro
> does, rather than how they're used.  So the "typical uses" I put
> here is actually a bad idea, tho it was just easier to do that than
> to try and describe what the macro does, {...}

Indeed, this may be so, but it certainly isn't any easier for me to
understand what it does.

I absolutely can not understand what is meant by the docstring.

Though, really, I typically do pretend at understanding these types of
things unless the content is not other than cosmetic such that it can
not perform any real modifications affecting my perspective of these
things :-P

> I don't know what atypical uses might be, and don't care about them

If it has typical usage then it has atypical usage. Presumably that
the macro exists suggests that there is a typical usage.  The macro
would go away if it didn't have a typical usage. That it doesn't
suggests  _someone_ cares about partitioning the typical from the
atypical usage whether you do or not.

If such usage is typical enough so as to support creation of the macro
it would seem reasonable to expect a resasonable documentation of what
it should be expected to do -- and, it should say so without over
reliance on vacuous terms like `pretending', `really', `typically',
`cosmetic', `real modifications', `content' etc.

> (at least until they come complaining about some undesirable part of
> the behavior).

Thats a nice long rope you've given users.
Maybe they get lost at the outer regions of that tether in which case
they aren't likely to come complaining...

What behaviour would you expect them to complain about if they can not
deduce from the docstring what it is they should expect this macro to
do?

>> around modifications of text-properties which do not really affect
>> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^|^^^^^^^^^^^^^^^^^^^^^^^^^
>>                          what is the affector txt-prop or the mod?
>
> Some other code: the caller would presumably know.

How could a caller modify text-properties which do not _really_ affect
the buffer? They either do affect whehter the buffer is modified or
they don't.

More precisely, what are the text-properties that do not _really_
affect a/the buffer?

>> the buffer's content.
>> ^^^^^^^^^^^^^|^^^^^^
>>    exactly what _is_ content - chars, tps, overlays, fields, faces?
>
> Can be any of it, depending on the case, because it's a conceptual

Whose conceptual notion, the callers, yours, or Emacs' vis a vis
`buffer-modified-p'?

> notion, rather than a technical one: typically "modify the buffer's
> content" means "saving the buffer results in a different file".

The use of `content' here is not good. The term is too "conceptually"
overloaded to be of any use in the context of which it is used.

>        Stefan

---
/s_P