RE: [PHP-DOC] Re: [PHP-DEV] Summer of Code

> -----Original Message----- > From: Gabor Hojtsy [mailto:gabor@hojtsy.hu] > Sent: 16 April 2006 10:15 > To: Jared.Williams1@ntlworld.com > Cc: 'PHPdoc' > Subject: Re: [PHP-DOC] Re: [PHP-DEV] Summer of Code > > Hi, > > [Internals list left out of the loop, since they have nothing > to do with discussions on Livedocs] > > Jared Williams wrote: > >>+1 for someone cleaning up livedocs to a ready-to-deploy state :) > > > > How about moving away from using system entities to construct the > > manual and using Xinclude instead? (See the mysql ref > manual docbook > > sources) This would make the base pages independent from > each other, and loadable into a DOMDocument, which could be > transformed with xslt. > > 1. Livedocs needs to run on PHP 4, whether you like this or > not. Most mirror sites still run PHP 4, and livedocs' primary > goal is to get deployed on mirror sites. Ah, that's a big hurdle then. > 2. Until we can completely forget DSSSL, constructs supported > by that toolchain should be used. I tried to look into > XInclude support in DSSSL, but was unable to find proof or > negative information on it. > [DSSSL tools generate the php.net manual pages, the > downloadable HTMLs and the basic CHM version, nearly all > things usable now :)] Would have to pre-process with xmllint to resolve Xincludes first. > 3. The DocBook XSLT sheets should also be compatible with the > change, since those generate the advanced CHMs now. > 4. All phpdoc tools, check scripts, etc. working with system > entities should be updated. > 5. Such a fundamental change should be made in all > translations at the same time, since all translations are > dependant on the English files being in the same environment. Think the changes to manual can be automated. Use xmllint on the current manual to with -noent option to create "before" manual as a single docbook. Alter /phpdoc/scripts/file-entities.php.in to output <!ENTITY name "<include xmlns=..>"> instead of system entities. And a script to do the same dir scan, adding a header to each .xml. Then use xmllint -noent -xinclude to create an "after" manual to compare with "before". > If these are all solvable, then we can look into some simple > use case where we see the advantages of using XInclude. BTW > Livedocs uses PHP transformations instead of some > transformation language, because it is supposedly faster, not > because it is not possible to do standard transformations on > phpdoc AFAIK. > Gabor >