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

[era eriksson]

On Sat, 21 Feb 2009 14:53:49 -0800, "Ilya Zakharevich"
<ilya@Math.Berkeley.EDU> said:
> On Sat, Feb 21, 2009 at 12:54:41PM +0200, era eriksson wrote:
> > > > 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.
<...> 
> P.S.
> 
> > 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".
> 
> I expect that most people would explore Micro-docs from the mode menu.
> So putting this info there would be chicken-and-egg problem: to access
> the info on enabling the mode, they would need to enable the mode.
> 
> If this info is clearly visible in the mode help, do you think it
> still makes sense to duplicate it in the micro-docs?  Like
> 
>   What is this mode you are using?  I did not see it before...  How to
>   enable it?  Oh, it has a mode menu...
> 
> ;-)

Sorry for this late reply; missed your PS originally.

I do think it makes sense to keep it in the micro-docs.  If nothing
else, it's easy to refer newcomers to it, and even if you did manage to
somehow set it up on your own, you might want to review the "official"
way to do it, perhaps while idly browsing the micro-docs looking for
neat stuff you didn't originally understand how to set up.

Another thing I've been meaning to propose would be for cperl-mode to
offer to install itself into your .emacs when you invoke it for the
first time, sort of like how (put 'dangerous-command 'disabled nil)
occasionally gets added to your .emacs after asking for permission. 
(IIRC narrow-to-region is one of these "dangerous" commands, and some of
the horizontal scrolling commands which I never use except by mistake.)

Do you think it would be appropriate to remove the +wontfix tag from
this bug?  (Not sure whether or not this bug applies to upstream Emacs
or your code at this point, and how the two are being coordinated, if at
all.)

/* era */

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