bug#1621: Please move cperl micro-docs to top of the cperl-mode.el file

[era eriksson]

On Fri, 20 Feb 2009 16:15:34 -0800, "Ilya Zakharevich"
<ilya@Math.Berkeley.EDU> said:
> On Fri, Feb 20, 2009 at 08:39:37PM +0200, era eriksson wrote:
> > How about a slight refactoring to make it more obvious where to 
> > look for the startup information?
> > 
> > Please find attached a proposed patch.  This is just a quick proof 
> > of concept; perhaps there is more startup-related information which 
> > could be moved to the new variable.
> 
> Again, I see no point in moving this information from the mode help.
> Why would one think it is an improvement?

This information is currently not in the mode help proper at all.  I
thought that this was by design.  I agree that moving it to the
`cperl-mode' documentation string from the `cperl-tips' documentation
would already be an improvement.

The name of `cperl-tips' I think suggests that it explains how to use
some slightly esoteric features, and by and large this holds true.  I
have been looking for the startup information on numerous occasions, and
more often than not ignored `cperl-tips' based on my interpretation of
what the name means.

Breaking out the setup / invocation information into its own clearly
labelled micro-doc would have the benefit of making it easy to refer to
it directly from e.g. the Commentary (as requested by the original
reporter) and other places (Info, Customize, etc) and separating it into
one coherent, rather short topic for those who are only looking for this
specific information.  The `cperl-tips' "micro-doc" has a rather oblique
label and covers a lot of different topics, making it rather long, in
spite of the "micro".

Especially for a feature which is likely to be the first and possibly
only time a new user tries to get to know cperl-mode, usability is of
critical importance.  If it's not blindingly obvious how to enable
cperl-mode by default, many potential users will simply give up on it.

/* era */

-- 
If this were a real .signature, it would suck less.  Well, maybe not.