On Tue, Oct 21, 2008 at 14:44, Maciek Sokolewicz <[EMAIL PROTECTED]> wrote: > Hannes Magnusson wrote: >> >> On Mon, Oct 20, 2008 at 21:45, Philip Olson <[EMAIL PROTECTED]> wrote: >>> >>> On 19 Oct 2008, at 12:41, Hannes Magnusson wrote: >>> >>>> Hi all >>>> >>>> I created and uploaded a new package on our PEAR-channel, doc.php.net, >>>> called "pman". >>> >>> There is one problem: >>> >>> philip$ pear install doc.php.net/pman >>> downloading pman-1.0.0.tgz ... >>> Starting to download pman-1.0.0.tgz (3,810,407 bytes) >>> ..........done: 3,810,407 bytes >>> ERROR: bad md5sum for file >>> /usr/local/pear/PEAR/docs/pman/man3/DomDocument.xinclude.3.gz >>> philip$ >>> >>> Hannes and I determined it's likely due to a case insensitive file system >>> because the following exists inside phd/package-pman.xml: >>> >>> <file baseinstalldir="php.net" name="man3/DomDocument.xinclude.3.gz" >>> role="doc" /> >>> <file baseinstalldir="php.net" name="man3/DOMDocument.xinclude.3.gz" >>> role="doc" /> >>> >>> One for Dom, and the other for domxml. Let's see what a Windows user has >>> to >>> say... I use Mac. >> >> >> And as of yet I have no idea how we can fix this. >> >> both ext/domxml (PHP4) and ext/dom (PHP5) define the "DOMDocument" >> class and the "xinclude" method. >> Fortunately the ext/domxml docs haven't been upgraded to use the new >> OO-doc-style so there IDs are still "function.domdocument-xinclude" >> while the ext/dom ID is "domdocument.xinclude" hence not causing any >> conflicts. >> >> However, the unix man-page output format uses the <refname> to >> generate the filenames, not the IDs, so you can write "pman strpos" >> rather then "pman function.strpos". >> >> Short of renaming the ext/domxml refname to intentionally include an >> typo I have no idea how we can fix this :( >> >> Btw: Since ext/domxml and ext/dom are so alike (both defining the >> exact same classnames and the only difference in the methodnames are >> camelCased vs under_scored) the documentation search for end-users >> (either via php.net/short-syntax-lookup or via the "search" box) is >> really sucky experience, never exactly knowing if they are browsing >> the ext/dom or ext/domxml docs :( >> This problem will partially be fixed by fixing the version >> information, but then new problem arises: If a user has the >> domelement->get_elements_by_tag_name page open and sees it is PHP4... >> how is he supposed to know there is an PHP5 alternative? >> >> My vote goes to removing the ext/domxml docs, PHP4 is dead anyway and >> those so crappy unfortunate needing to read PHP4 code (for whatever >> reason, upgrading maybe) and check the manual for "WTF is going on" >> will have to search "the attic" or something.... >> >> -Hannes > > Or perhaps we could make our documentation based on PHP version like the > mysql manual does. So we have a "different" manual for PHP6, PHP 5(.3), 5.2, > one for PHP 4, etc. Then we could include /domxml in the PHP4 manual, and > the dom in the PHP5 and 6 ones. You could add a small dropdown box at the > top like we have with languages now to choose the PHP version you're looking > into. You could also have that stored in a cookie via my php.net > functionality. > I'm pretty sure phD can be modified to output docs specific to versions if > we properly assign versions and changelogs to all functionality.
Totally. I would really appreciate semi-version-specific manual, and I think we've discussed it in the passed... The actual markup change wouldn't have to be that dramatic, adding few version attributes here and there would probably do the trick - and then new options to PhD "--only-php5" "--all-versions" "--php5-and-greater" or whatever.. The biggest problem would be the naming convention really, function.strpos-php5.php? or function.strpos.php?version=5? What about the html chunked output? -Hannes
