> > One very good idea for the PHP manual is creating individual > > changelogs per function. This changelog would, for example, > > be used for new and changed parameters, changed behaviors such > > as default values, and various other changes. This would > > replace the massive use of <note> clutter in the PHP manual. > > Changelog entries could also be used in sections, like the > > session reference could use this. Perhaps reference sections > > could also list new functions. > > > > I have no specifics and believe Goba has done some preliminary > > work on this topic but am thinking this should be discussed > > at the doc meeting. What's the status on this wonderful idea? > > I have not done preliminary work on this. This seems to be a very good > idea, and would help structure our function documentation better. Joined > with the better explanation of parameters. You see we have parameters > explained now in free text. I prefer something like the XML functions > docs use, like http://php.net/xml_parse for example. All these things > are to make the docs a bit more formal, so users can find relevant > information quicker.
The topic of parameter layout is a good one too. Awhile ago I implemented parameter descriptions in a <table> for the setcookie docs: http://www.php.net/setcookie although it contains an example column as cookies are kinda "special and weird" :) This topic of parameter structure lives in the TODO as: - consider adding beautified table for parameter definitions and meanings. do this one extension at a time. - see: http://marc.theaimsgroup.com/?l=phpdoc&m=103658209317795 Use of <variablelist> like in the xml_parse() docs looks pretty good too. Back to the changelog, is it a simple matter of creating tables or should we do something else? For example, there has been talk of highlighting "stuff" specific to PHP versions (i.e. I say I use PHP 4.3.0 so it would highlight some stuff I really should read). If that was done, I assume we'd need some special ids or tags. Although personally I'm not concerned with the idea of version specific highlighting. Maybe everyone can ponder over this and the best way to layout both the changelog and parameter structure. Whether changelog information for a parameter should be inline with the parameter descriptions, not sure, as the changelogs will contain other information too. Regards, Philip -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
