Re: Module abstract: Is its length still limited?
On Mon, Nov 07, 2005 at 09:08:40PM -0500, Ricardo SIGNES wrote: * Andreas J. Koenig [EMAIL PROTECTED] [2005-11-07T17:29:50] I will be very happy if you guys decide something and let me know. I'll adjust the code for the forms on PAUSE then. Here's my official vote: (length $module_name + length $abstract + 3) should be under 80. This means that the whole header and abstract will fit in one line. That's more than 44 characters for short module names. Longer module names, which should be pretty descriptive, need shorter abstracts. Wombat - a framework for building reusable fruit-counting applications Application::Framework::FruitCounting - for reusable produce applications That seems sensible. Perhaps to further relax it, it could be noted that longer values will be accepted, but they will truncated with an ellipse (...) when displayed in a space constrained format, such as a e-mail, or other documents meant to be read in a terminal. I'm fine with rjbs proposal as-is for the simplicity. My refinement would likely require effort of several tool writers to implement, instead of having the authors simply be concise. Mark
Re: Module abstract: Is its length still limited?
Andreas J. Koenig wrote: On Tue, 08 Nov 2005 10:41:27 +1300, Sam Vilain [EMAIL PROTECTED] said: On Sun, 2005-11-06 at 07:51 +0100, Andreas J. Koenig wrote: So, the question I would now ask: How rigidly should I enforce the 44-character limit if I am guiding someone in the task of creating proper Perl modules? As the module list is dead, we cannot really argue in favor of 44 characters except with the one argument of tradition/best practice. I believe when 3815 authos have managed to describe their modules in 44 characters, then it should be doable for some other 3815000 modules too. Yes, let's keep it short. But how about increasing the limit to 60 or so? Many a time I would've liked an extra word or two. There's an old business advice that you shouldn't start an enterprize if you cannot describe its mission in a single sentence. I think its true for modules too. There are very few sentences that fit in 44 characters. 60 characters I think still honours this principle. I will be very happy if you guys decide something and let me know. I'll adjust the code for the forms on PAUSE then. It's not clear to me which guys get to make this decision. I don't know how the original 44-character limit came about. IMHO, 44 characters is nowadays too short and 60 maybe too short as well. I'd prefer to err on the side of generosity and say 100 characters. Or perhaps: Only as many characters as will fit in one line in a typical browser at a default font size on the author's home page on CPAN (68-ish). Or perhaps: the magic 78 recommended by Damian for lines in text editors. As you can see, this is largely a question of taste. But this decision can be informed by empirical research. Perhaps we should take a look at ABSTRACTs for distros written by very prolific CPAN contributors such as DCONWAY, AUTRIJUS, BDFOY, etc., and see what they have done in this regard, i.e., how long are their ABSTRACTs?
Re: Module abstract: Is its length still limited?
On Mon, 2005-11-07 at 21:08 -0500, Ricardo SIGNES wrote: * Andreas J. Koenig [EMAIL PROTECTED] [2005-11-07T17:29:50] I will be very happy if you guys decide something and let me know. I'll adjust the code for the forms on PAUSE then. Here's my official vote: (length $module_name + length $abstract + 3) should be under 80. This means that the whole header and abstract will fit in one line. That's more than 44 characters for short module names. Longer module names, which should be pretty descriptive, need shorter abstracts. Wombat - a framework for building reusable fruit-counting applications Application::Framework::FruitCounting - for reusable produce applications My feeling is that this wouldn't really work when the module name gets too long, for example when a namespace under which you are contributing has chosen verbose terms. For keeping your source code at 80 characters wide, it should be perfectly legal to wrap that line in the source; it's not a verbatim block so all Pod parsers SHOULD see it as a flowed paragraph. Whether or not this is true for all relevant parsers is another story. Personally I'd call it a bug if they don't follow the POD rules, though. I also feel that the total length of those two is somewhat irrelevant for its intended use - for instance, if you are browsing modules on search.cpan.org, the module names and abstracts are both flush left. Tabular format works better like that. I think the key question is more along the lines of, how much text do you want to see while you are reading the abstract for a whole bunch of modules? What length is about right? I suggested 60 because it's just a *little* bit longer, to allow for better word choices here and there, but still too short for rambling. Perhaps 80 is fine, too. I had a read through the modules by the authors listed in the other e-mail, AUTRIJUS, BDFOY, and DCONWAY, and I couldn't really see any obviously overly squeezed abstracts. Except perhaps QM for Quantum Mechanical. Can anyone find any examples of abstracts that they think are inadequate due to size restrictions? Sam.
