bug#15852: 24.3.50; cperl-mode: Please audit the docstrings (before the next merge)

[Jambunathan K <kjambunathan@gmail.com>]

I am feeling like Drew Adams Junior.  But here I go.

----------------------------------------------------------------

For example, what exactly does older mean.  cperl-mode seems to have an
history of atleast a decade.  Please update docstring to the current
state of the package as on 2013.


> 10 matches for "older" in buffer: cperl-mode.el
>     526:Older version of this page was called `perl5', newer `perl'."
>     709:For best results apply to an older Emacs the patches from
>     775:  "Description of problems in CPerl mode specific for older Emacs versions.
>     789:Even with older Emacsen CPerl mode tries to corrects some Emacs
>     809:The solution is to upgrade your Emacs or patch an older one.  Note
>    1595:\(even with older Emacsen), `cperl-electric-lbrace-space' to t switches
>    4110:		      bb (char-after (1- (match-beginning b1))) ; tmp holder
>    5381:	(insert (make-string dc ?-)))))	; Placeholder (to avoid splitting???)
>    5827:		      ;; need to manually set 'multiline' for older font-locks
>    8823:    ;; Why needed???  With older font-locks???


----------------------------------------------------------------

I have never seen the term Emacxen used before.

> 5 matches for "\_<Emaxen\_>" in buffer: cperl-mode.el
>     747:Though with contemporary Emaxen CPerl mode should maintain the correct
>     825:with old Emaxen which do not support `syntax-table' property.
>     906:10) Uses a linear-time algorithm for indentation of regions (on Emaxen with
>     931:    A2) On capable Emaxen CPerl will use improved syntax-handling
>    1631:here-docs sections.  With capable Emaxen results of scan are used

----------------------------------------------------------------

Please remove

    Menu -> Perl -> Microdocs -> Praise, Problems etc.

They qualify to be in file's Commentary section. 

----------------------------------------------------------------

I have a bad feeling about docstrings in cperl-mode specifically C-h f
cperl-mode.

1. It reads like loosely and bad structured, developer notes.
2. Some of the docstrings are in passive voice.

----------------------------------------------------------------
In GNU Emacs 24.3.50.4 (i686-pc-linux-gnu, GTK+ Version 2.20.1)
 of 2013-11-09 on debian-6.05
Bzr revision: 115051 jan.h.d@swipnet.se-20131109111953-cysfi19meuidy96q
Windowing system distributor `The X.Org Foundation', version 11.0.10707000
System Description:	Debian GNU/Linux 6.0.5 (squeeze)