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

[Ilya Zakharevich <ilya@Math.Berkeley.EDU>]

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.

Oups, did not realize this; sorry!  I agree; >> TODO.

Thanks,
Ilya

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...

;-)