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

[Jambunathan K]

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)