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.
I like the idea of adding more structure information into the XML files too. This is why I am trying to push the see also lists too. We still have the option to render them as they were paras, while we gain much with the specific markup.
In this case having PHP versions in the XML source too as changelog relevancy identifiers can help users. Especially now with PHP 5 related changes, which get documented, without PHP 5 being production ready. If users would be able to see those changes, notes, etc. regarding PHP 5 in lightgray for example they would easily span across them with their eyes. The same is for PHP 3 stuff, while you are using PHP 4, etc. We had a request from a user to have his PHP version as a setting in my php.net, and so we can mark functions not available in his PHP version specially. That is not possible, because we have the version info as a string in the text [in the HTML output] and not in some better form.
Goba
-- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
