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

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

[Jason A. Spiro]

Package: emacs
Severity: wishlist

Feature request forwarded from https://launchpad.net/bugs/99634 :

---------- Forwarded message ----------
From: Jason Spiro <jasonspiro3@gmail.com>
Date: 2007/3/31
Subject: [Bug 99634] Please move cperl micro-docs to top of the
cperl-mode.el file
To: jasonspiro3@gmail.com


Public bug reported:

Binary package hint: emacs-snapshot

I wanted to set Emacs to use cperl-mode instead of perl-mode, but I
didn't know how.  It turns out the answer was in the cperl-tips section
on line 710 of the file.

Please move the cperl micro-docs from the middle of the cperl-mode.el
Elisp file to the top of the file.  This will make more people see them.

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

[Stefan Monnier]

> Please move the cperl micro-docs from the middle of the cperl-mode.el
> Elisp file to the top of the file.  This will make more people see them.

I suggest we add some text in the Commentary that point people to the
docstrings below.  Moving the docstrings wholesale will increase the
merge burden when syncing with Ilya's version.


        Stefan

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

[Glenn Morris]

tags 1621 wontfix
stop

Stefan Monnier wrote:

>> Please move the cperl micro-docs from the middle of the cperl-mode.el
>> Elisp file to the top of the file.  This will make more people see them.
>
> I suggest we add some text in the Commentary that point people to the
> docstrings below.

There already is such text, indicated with capital letters and "<<<<<"
signs, no less.

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

[Emacs bug Tracking System]

Processing commands for control@emacsbugs.donarmstrong.com:

> tags 1621 wontfix
bug#1621: Please move cperl micro-docs to top of the cperl-mode.el file
There were no tags set.
Tags added: wontfix

> stop
Stopping processing here.

Please contact me if you need assistance.

Don Armstrong
(administrator, Emacs bugs database)

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

[Jason A. Spiro]

2008/12/18 Stefan Monnier <monnier@iro.umontreal.ca> wrote:
>> Please move the cperl micro-docs from the middle of the cperl-mode.el
>> Elisp file to the top of the file.  This will make more people see them.
>
> I suggest we add some text in the Commentary that point people to the
> docstrings below.  Moving the docstrings wholesale will increase the
> merge burden when syncing with Ilya's version.

Ilya, could you too please move the micro-docs from the middle of the
your cperl-mode.el Elisp file to the top of the file?  This will make
more people see the micro-docs.  And then I hope the GNU Emacs
maintainers will adopt your change downstream.

Please Reply to All.  By the way, I sent mail to this address
@ilyaz.org because I could not find any non-Perl-related address to
write to.

-- 
Jason Spiro: software/web developer, packager, trainer, IT consultant.
I support Linux, UNIX, Windows, and more. Contact me to discuss your needs.
+1 (416) 992-3445 / www.jspiro.com

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

[Ilya Zakharevich]

On Fri, Dec 19, 2008 at 01:06:44AM -0500, Jason A. Spiro wrote:
> Ilya, could you too please move the micro-docs from the middle of the
> your cperl-mode.el Elisp file to the top of the file?  This will make
> more people see the micro-docs.

Could you please explain to me the mental model of people who would
read the code of CPerl, but not the mode help, and would not explore
the mode menu?

Thanks,
Ilya

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

[Jason A. Spiro]

2008/12/20 Ilya Zakharevich <ilya@math.berkeley.edu>:
> Could you please explain to me the mental model of people who would
> read the code of CPerl, but not the mode help, and would not explore
> the mode menu?

I don't know why that mental model has happened.  But I know it
happened to me.  I don't expect help to be located halfway through a
Lisp file.  I expect it to be either in Info format or as docstrings
or near the top of the file.  :)

Remember, the change I am suggesting is an easy one to make.

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

[Jason A. Spiro]

2008/12/20 Ilya Zakharevich <ilya@math.berkeley.edu> wrote:
>
> Let me STILL try to get some clarification.  Did you not read the mode
> help, and/or investigated the mode menu, or you did but not noticed
> references to micro-docs?

IIRC I did not read the mode help or look at the mode menu.  I simply
looked for a Commentary section.

I hadn't used the mode much yet:  it definitely had been less than an
hour.  But in general, I almost never read mode help, and I seldom
look at mode menus.  I do sometimes read mode Info documentation, or
Lisp file Commentary sections.

P.S.  I added the original CC list back.  If you did not want me to do
this, please let me know.

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

[Lars Ingebrigtsen]

"Jason A. Spiro" <jasonspiro4@gmail.com> writes:

> I wanted to set Emacs to use cperl-mode instead of perl-mode, but I
> didn't know how.  It turns out the answer was in the cperl-tips section
> on line 710 of the file.

I've now added a more explicit reference in the comments in cperl-mode
as to where to find the microdocs in Emacs 28.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no