A few concerns: a) What sort of changes should be included when moving to the new doc style?
* Should we include Whitespace changes? * How about making the examples compliant to our coding standards? * Insert markup like <type>, <constant>, <varname>, etc.? * Implement entities like example.output? * No content changes! (Don't follow my exif example on this) b) Should we use parameter role="reference" in the methodsynopsis? DSSSL/XSLT does not understand this, is this a concern right now? Or should we just leave & until they do, or, actually alter the DSSSL/XSL (don't look at me to do this!). c) Will the constant list remain in the partintro? Right now the constants exist there and can be rather long so are we going to put this on its own page? I believe most feel it should be on its own page. d) Do we use &listendand; when only two functions exist? This is a minor detail but it looks a little funny: See Also foo(), and bar() Maybe something to let livedocs worry about? Most likely. e) Should non-translators also implement this style into translated docs? Since only structure is changed it seems anyone could implement this into any language tree. And lastly, some basic rules that should be kept in mind while converting the docs: 1) Do not end the see also with a period. And one <function> per line. 2) Use commas and &listendand; to separate 'see also' entries. 3) Do not end the refpurpose with a period, and keep them short. 4) Only the methodsynopsis may be wider than 78 characters. 5) Always use the PEAR coding standards. IMHO we should implement all of the above in the move except leave & for now, and move constants out of the part intro. If this is not how translators want it done then let's be sure to discuss that. Regards, Philip
