bug#6821: Documentation: `insert' needs refilled

bug#6821: Documentation: `insert' needs refilled

[MON KEY]

Documentation: `insert' needs refilled.

,---- (documentation 'insert)
| Insert the arguments, either strings or characters, at point.
| Point and before-insertion markers move forward to end up
|  after the inserted text.
| Any other markers at the point of insertion remain before the text.
|
| If the current buffer is multibyte, unibyte strings are converted
| to multibyte for insertion (see `string-make-multibyte').
| If the current buffer is unibyte, multibyte strings are converted
| to unibyte for insertion (see `string-make-unibyte').
|
| When operating on binary data, it may be necessary to preserve the
| original bytes of a unibyte string when inserting it into a multibyte
| buffer; to accomplish this, apply `string-as-multibyte' to the string
| and insert the result.
|
| (fn &rest ARGS)
`----

At this sentence:

"Point and before-insertion markers move forward to end up
   after the inserted text."
 ^^

Problem verified current through Bzr-100972

--
/s_P\

bug#6821: Documentation: `insert' needs refilled

[Chong Yidong]

> "Point and before-insertion markers move forward to end up
>    after the inserted text."

Docstrings in Emacs have used this kind of indentation for ages.
It's idiosyncratic, but there's no harm keeping in.

bug#6821: Documentation: `insert' needs refilled

[MON KEY]

On Sat, Aug 14, 2010 at 7:25 PM, Chong Yidong <cyd@stupidchicken.com> wrote:
>> "Point and before-insertion markers move forward to end up
>>    after the inserted text."
>
> Docstrings in Emacs have used this kind of indentation for ages.
> It's idiosyncratic, but there's no harm keeping in.
>

OK.
Out of curiosity is there a particular reason/rationale for why this
type of BOL offset appears for only _some_ docstrings?

Also, what is threshold for determining when it _is_ reasonable to
notify that a doc needs refilled?

I ask because I have the impression that Emacs 23.2 seems to have more
occurrences of these "idiosyncratic"
indentations than previous versions (though this impression may be do
to increased familiarity w/ the docs.)

Indeed, w/ some docstring instances the anomalous indentation occurs
across multiple lines to an extent that it  can impede/hinder ones
ability to grok the doc.

--
/s_P\

bug#6821: Documentation: `insert' needs refilled

[Chong Yidong]

MON KEY <monkey@sandpframing.com> writes:

> I ask because I have the impression that Emacs 23.2 seems to have more
> occurrences of these "idiosyncratic" indentations than previous
> versions (though this impression may be do to increased familiarity w/
> the docs.)

Actually, I think most of these occurrences are old.

In general, I would not worry about the indentation; instead, focus on
the content of the docstrings.