Outdated information in documentation perlmodlib #15157
Comments
From justin@purestblue.comThis is a bug report for perl from justin@purestblue.com, perldoc perlmodlib Still outdated in current version seen at http://perldoc.perl.org/perlmodlib.html perlmodlib suggests module developers go to nntp newsgroup comp.lang.perl.misc for module naming advice. I've been subscribed to that group for many years, and it has very, very little traffic these days, I doubt it would be a good source of assistance for naming. Here are the sentances in question (for easy searching): "If in any doubt ask for suggestions in comp.lang.perl.misc." In addition, pause.perl.org suggests the mailing lists modules@perl.org and module_authors@perl.org. I think these are a suggestions (though I am not subscribed and do not know how many are - I'm sure you're better placed to tell), and perhaps #perl on irc.perl.org Flags: Site configuration information for perl 5.20.2: Configured by Debian Project at Fri Jan 1 13:02:25 UTC 2016. Summary of my perl5 (revision 5 version 20 subversion 2) configuration: Locally applied patches: @INC for perl 5.20.2: Environment for perl 5.20.2: |
From @jkeenanOn Sat Jan 30 09:05:35 2016, justin@purestblue.com wrote:
There are certainly many parts of 'perlmodlib' which could be improved. However, in the interest of having a focused discussion and keeping the lifespan of a bug ticket as short as possible, I am only going to focus on the part of the document which the OP cited. Patch attached. Please review. Given where we are in the annual release cycle, I'll be looking to apply this patch in seven days unless there are serious objections. Thank you very much. -- |
From @jkeenan0001-Update-guidance-on-naming-of-modules.patchFrom 4d5e03b23bc2b87cdd36b268fba1f910a8e43d3b Mon Sep 17 00:00:00 2001
From: James E Keenan <jkeenan@cpan.org>
Date: Sun, 7 Feb 2016 07:58:29 -0500
Subject: [PATCH] Update guidance on naming of modules.
Delete reference to comp.lang.perl.misc. Add references to module-authors
list/newsgroup and to PAUSE.
For: RT # 127435
---
pod/perlmodlib.PL | 12 +++++++++---
1 file changed, 9 insertions(+), 3 deletions(-)
diff --git a/pod/perlmodlib.PL b/pod/perlmodlib.PL
index 608b64e..aa6b18c 100644
--- a/pod/perlmodlib.PL
+++ b/pod/perlmodlib.PL
@@ -1223,7 +1223,6 @@ Module names should begin with a capital letter.
Having 57 modules all called Sort will not make life easy for anyone
(though having 23 called Sort::Quick is only marginally better :-).
Imagine someone trying to install your module alongside many others.
-If in any doubt ask for suggestions in comp.lang.perl.misc.
If you are developing a suite of related modules/classes it's good
practice to use nested classes with a common prefix as this will
@@ -1244,6 +1243,12 @@ To be portable each component of a module name should be limited to
11 characters. If it might be used on MS-DOS then try to ensure each is
unique in the first 8 characters. Nested modules make this easier.
+For additional guidance on the naming of modules, please consult:
+
+ http://pause.perl.org/pause/query?ACTION=pause_namingmodules
+
+or send mail to the <module-authors@perl.org> mailing list.
+
=item *
Have you got it right?
@@ -1253,8 +1258,9 @@ picked an interface design that will cause problems later? Have
you picked the most appropriate name? Do you have any questions?
The best way to know for sure, and pick up many helpful suggestions,
-is to ask someone who knows. Comp.lang.perl.misc is read by just about
-all the people who develop modules and it's the best place to ask.
+is to ask someone who knows. The <module-authors@perl.org> mailing list
+is useful for this purpose; it's also accessible via news interface as
+perl.module-authors at nntp.perl.org.
All you need to do is post a short summary of the module, its
purpose and interfaces. A few lines on each of the main methods is
--
1.9.1
|
|
The RT System itself - Status changed from 'new' to 'open' |
From @rjbsOn Sun Feb 07 05:12:20 2016, jkeenan wrote:
Thanks, Jim, looks good. I wonder whether we would benefit from a cross-reference here to perlmodstyle (which mentions prepan) or perlnewmod. This wonderment makes me think that a bigger overhaul would be useful. I plan to do nothing about it myself, and if you do nothing either, I think that's fine. Perhaps you will feel suddenly quite inspired to make a change of some sort, though. If all you do is apply this patch in a few days, you still get my thumbs up. ;) -- |
From @jkeenanOn Sun Feb 07 19:17:19 2016, rjbs wrote:
Thanks, pushed to blead in commit f94c6c5 -- |
|
@jkeenan - Status changed from 'open' to 'resolved' |
Migrated from rt.perl.org#127435 (status was 'resolved')
Searchable as RT127435$
The text was updated successfully, but these errors were encountered: