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

[MON KEY <monkey@sandpframing.com>]

documentation of macro `with-silent-modifications' lisp/subr.el
current through Bzr-100654

There is a typo @ "... does not modifies the buffer."
should be "... does not modify the buffer."

More generally the docstring is bordering on non-sensical.

,---- (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."
|
`----


Execute BODY, pretending it does not modifies the buffer.
^^^^^^^^^^^^^^|^^^^^^^^^^^^^^^^^^^^^ modify ^^^^^^|^^^^^
        what is a `pretend'                   which buffer?

If BODY performs real modifications to the buffer's text, other than
^^^^^^^^^^^^^^^^^|^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^|^^^^^^^^^^^^^^
    what is a non-real mod?                         ???

cosmetic ones, undo data may become corrupted.  Typically used
^^^|^^^^^^^^^^^^^^^^^^|^^^^^^^^^^^^^^^^^^^^^^^^^|^^^^^^^^^^^^^
what is non-cosmetic? |             what is an atypical usage?
                      |
         why not say `buffer-undo-list'?

around modifications of text-properties which do not really affect
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^|^^^^^^^^^^^^^^^^^^^^^^^^^
                         what is the affector txt-prop or the mod?
the buffer's content.
^^^^^^^^^^^^^|^^^^^^
   exactly what _is_ content - chars, tps, overlays, fields, faces?

--
/s_P\