Fix this FAQ ! (was: [PEAR-BUG] Bug #923)

<pear-dev@lists.php.net> wrote : > ATTENTION! Do NOT reply to this email! > To reply, use the web interface found at > http://pear.php.net/bugs/bug.php?id=923&edit=2 > > > ID: 923 > Updated by: richy@php.net > Reported By: bmansion at mamasam dot com > Status: Open > Bug Type: Mail_IMAP > PHP Version: Irrelevant > New Comment: > > Honestly I don't *have* to do anything, as far as I'm conserned I've > done exactly what has been specified in the F.A.Q. page that I already > pointed out. > > If this is the way that the PEAR Group wants it done, then the > package.xml F.A.Q. page should reflect that. > > Two you *not caring* whether the user knows where your examples are or > not seems to defeat the purpose of contributing code in the first > place. I want my package to be both understood and used. > > Its confusing, the documentation doesn't say to do it that way and > there's nothing in the docs that says that I can't have it that way, in > fact quite the opposite it lays out that I've already got it right. > And quite frankly I don't see what it is hurting. Before we continue > this discussion you should have a look at the F.A.Q.. regardless of if > yours or other packages are doing it differently. To me a role="doc" > implies the complete offical documentation including highlighted source > code, method explaination, etc.... these are PHP source files, > therefore they should be labled role="php". > > My being new to PEAR, it would be quite helpful if all the little > pet-peaves and unspoken standards were all laid out flatly and plainly > in the official documentation. And yes, in plain enough terms that an > idiot could understand. Because it isn't always that obvious. The FAQ is wrong but if you should have looked at other package.xml files as I suggested. Examples must go in the docs/ directory. Use role="doc" for your example files in the package.xml I don't want an examples/ directory in my PEAR Mail/ directory. What if everyone starts doing things like that ? Where are all those examples going to end ? And to the person who wrote the FAQ, please fix it before new packages starts to really screw the PEAR project organization totally. TIA Bertrand Mansion Mamasam