To provide a little wood for the fire I created a list of all the uppercase headings that are in the Perl modules that presently reside on my system. The semi unique uppercase list is at 745! What I would like is to define a list of "Must Have" headings out of the 745+ being used.
Now this list is not filtered and if someone would like to filter it down and send it back I will create a web page with links to each filtered list. The URL for now is: http://www.gina.net/rough_headings.txt I have left them raw at this point since there are some interesting ones in there and different spellings as well, which as a bad speller I can appreciate. :) NOTE: I did nothing to the content, it is the same case it was in the documentation it was extracted from. I only used the uppercase =head1 entries. Any head1 with lower case was excluded and only =head1 tags were grepped. Aaron On Thu, 2002-08-01 at 13:05, Nigel Hamilton wrote: > > > > > > It should do more than just let a developer browse the > > > documentation, and make things looks cohesive - it should help 'enforce' > > > it. > > > > > > I hear screams of .... TMTOWTDI ... but read on ... > > > > > > Can I humbly suggest, for a module/class/package to bear the P5EE > > > mark it must be first 'compiled' with the documentation generator. > > > > > > It should also encourage/enforce: > > > > > > > > Encourage the module author to follow a convention, but more ideally a > > system needs to be created that can take existing documentation and > > break into its parts and then put stubs in for the missing EE attributes > > and then members of the P5EE group can edit and revise the information > > via a browser and then once approved by the "doc-king" the revised > > documentation would be automatically emailed back to the module author. > > > Agreed. For it to work, it needs to be backward compatible with perldoc, > and intially needs to be *really* minimal. > > I like the idea of auto-emailing the module authors a url to their > p5eedoc - they may get to like it! > > That's the first stage. But then as things develop I think the p5eedoc > utility should help *encourage* p5ee coding standards, syntax conventions > etc. > > > > > > I don't envision anything that forces a module maintainer to modify > > their documentation as being effective in this community. > > > > P5EE is, in my mind, a resource for the best in class of modules and > > more glue to get you going then it is an enforcer. > > > > Agreed. > > 'Enforce' may be too strong a word - but there does need to be a way for > the p5ee 'standards' to propagate - and I think the documentation tool > can do it - but from the outset it needs to apply the 'stamp' of p5ee. > > > > > 1. p5ee naming conventions > > > 2. p5ee syntax style > > > 3. a module is not P5EE 'certified' unless it compiles into peedoc > > > > Modules can be P5EE 'certified' if P5EE certified documentation is > > available, but it doesn't have to ship with the module, we would prefer > > it does, but I don't see it being easy to get every developer to buy > > into the P5EE concept at first. > > > > Hmmm ... agreed. I think a simple perldoc->p5eedoc translator > should happen first - that uses perldoc and source parsing to create the > documentation - it needs to be really minimal. > > > > > 4. auto generated PDF documentation (for boardroom consumption) > > > > There are already several modules available that will turn POD into PDF > > so this would simply require our P5EE approved/certified docs be > > converted via a cron job or some automated system. > > > > Cool. > > > > * 5. be used in conjunction with a web-based IDE (for code > > > editing, browsing, testing, publishing packages to/from > > > p5ee.org, cvs) > > > > > > The p5ee documentation 'compiler' could be released in versions > > > ... with the initial versions being very 'lite' - and then gradually > > > asserting the values/tenets of the P5EE mark - as adoption takes off > > > (fingers crossed). > > > > > > > At this point my "idea" doesn't go beyond standard pod tags. One thing > > that I think P5EE has to do before it goes beyond the current set of > > tools is prove the weakness of the existing ones. P5EE is about > > leveraging Perl in its present form to produce Enterprise grade > > applications. Everything one needs to do this already exists, what > > doesn't exist is a coding standard or a verification system that > > packages being used are relatively bug free and secure along with more > > aggressive regression testing of new module releases. But those topics > > are for down the road. > > > > Yes, But I think the road could start with the p5eedoc > translator/documenter. > > Ideally I'm thinking of a command line tool that will 'bless' a > module as p5ee. > > > NIgel > > > > -- > Nigel Hamilton > Turbo10 Metasearch Engine > > email: [EMAIL PROTECTED] > tel: +44 (0) 207 987 5460 > fax: +44 (0) 207 987 5468 > ________________________________________________________________________________ > http://turbo10.com Search Deeper. Browse Faster. > > >
