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.
All agreed!
* 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.
Some small content changes are needed, but otherwise it would be nice to not make content changes in these commits.
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.
The former is a lot easier to understand IMHO.
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.
IMHO this will be easy to fix in the DSSSL and XSLT sheets. I have done these simple modifications before in the DSSSL sheets, and quite familiar with XSLT to do it (but the chance is now up for Mehdi).
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.
Agreed.
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 ? :)
IMHO it is pronounced as "foo and bar", so &listendand; has some base, but I am far from being a native English speaker.
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 ?)
Some translations modify the stuff (add one or more explanation paragraphs, etc), so it will not be easy to find out how and where to split. IMHO it is better to leave this task up to translation teams.
Goba
