Philip Olson wrote:
Hello'
A few concerns:
a) What sort of changes should be included when moving to the new doc style?
* Should we include Whitespace changes?
I'd say yes. Let's clean everything at once, we don't want to add more work for the translators.
* How about making the examples compliant to our coding standards?
Do I need to answer ? :)
* Insert markup like <type>, <constant>, <varname>, etc.?
Yes.
* Implement entities like example.output?
It's now or never imo !
* No content changes! (Don't follow my exif example on this)
This will be a problem. Actually, the 3 main informations (description, parameter, return value) are scrumbled. Switching to the new docs will mean at least some changes.
I tried to convert bc math functions, you can see the result here : http://didou.keliglia.com/bc.diff.txt
A problem I experienced BTW :
* in the description: should we start talking about the parameters and the return value ? For example, let's watch bcadd(), the description can be:
a) <function>bcadd</function> adds two arbitrary precision numbers and returns the result.
b) <function>bcadd</function> adds the <parameter>left_operand</parameter> to the <parameter>right_operand</parameter> and returns the sum.
What do you guys think about it ?
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!).
I can have a look at this. I played with XSL lately at work and I'd like to give it a try :) I'll keep you updated on 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.
I can only confirm that I'm +1.
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.
I don't think so. I think that you need to write it in the XML source the way you say it. BTW, what is the correct wording ? :)
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.
This is clearly the translators job as every translation team have its
own way of work (revcheck..). Also, you have to understand the translation to split an old document to the new style (where is the description of the first parameter ?)
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.
Ok for one function per line, but what is the problem with periods ?
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.
Agreed
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.
I'll have some XSLT tests tomorrow to see if I can help with the & switch.
didou
