Re: [PHP-DOC] Proposal: CHANGELOG
* Thus wrote Philip Olson: typeinteger/type parameter role=ref choice=optwidth/parameter VS parameter role=ref choiceopt type=integerwidth/parameter Parameter has no type attribute, so only the former is possible. Ups, parameter also has no choice attribute, it is of paramdef. Which in turn can only be added inside a funcprototype according to the DocBook DTD. Couldn't we come up with some DocBook friendly alternative? A good idea would be to somehow reference the parameter already defined in the funcprototype, so only one place needs editing when parameters get changed. Then livedocs could resolve the reference and copy the parameter info (type, by reference, name) to the right place in the variablelist. We may need a livedocs person to tackle this as the structure is already in place. Using the same example we have the following in the methodsynopsis (split from one line to fit in this email): methodparam choice=opt typeint/typeparameter role=referencewidth/parameter /methodparam I added a patch to do this. http://www.powertrip.co.za/livedocs/ Curt -- First, let me assure you that this is not one of those shady pyramid schemes you've been hearing about. No, sir. Our model is the trapezoid!
Re: [PHP-DOC] Proposal: CHANGELOG
We may need a livedocs person to tackle this as the structure is already in place. Using the same example we have the following in the methodsynopsis (split from one line to fit in this email): methodparam choice=opt typeint/typeparameter role=referencewidth/parameter /methodparam I added a patch to do this. http://www.powertrip.co.za/livedocs/ Please notice Ilia at least about the existance of this livedocs patch queue :) [cc-ed] Goba
Re: [PHP-DOC] Proposal: CHANGELOG
On August 18, 2004 03:52 pm, Gabor Hojtsy wrote: We may need a livedocs person to tackle this as the structure is already in place. Using the same example we have the following in the methodsynopsis (split from one line to fit in this email): methodparam choice=opt typeint/typeparameter role=referencewidth/parameter /methodparam I added a patch to do this. http://www.powertrip.co.za/livedocs/ Please notice Ilia at least about the existance of this livedocs patch queue :) [cc-ed] Goba The patch has been applied with some revisions. Ilia
Re: [PHP-DOC] Proposal: CHANGELOG
typeinteger/type parameter role=ref choice=optwidth/parameter VS parameter role=ref choiceopt type=integerwidth/parameter Parameter has no type attribute, so only the former is possible. Ups, parameter also has no choice attribute, it is of paramdef. Which in turn can only be added inside a funcprototype according to the DocBook DTD. Couldn't we come up with some DocBook friendly alternative? A good idea would be to somehow reference the parameter already defined in the funcprototype, so only one place needs editing when parameters get changed. Then livedocs could resolve the reference and copy the parameter info (type, by reference, name) to the right place in the variablelist. We may need a livedocs person to tackle this as the structure is already in place. Using the same example we have the following in the methodsynopsis (split from one line to fit in this email): methodparam choice=opt typeint/typeparameter role=referencewidth/parameter /methodparam And in the parameter list refsect1 we have a few unique items, first: reftitle.parameters; And the parameter varlistentries each have this format: termparameterwidth/parameter/term So DSSSL would currently parse this as normal whereas livedocs might be able to add the extra information. Whether the existence of the parameters reftitle entity inside the refsect1 is enough for livedocs I don't know but I assume we wouldn't need to use ID's here. On a related note, I assume we'll now use role=reference within the methodparam's parameter tag instead of amp; Regards, Philip
Re: [PHP-DOC] Proposal: CHANGELOG
Type information and by reference passing should be included IMHO too. BTW the names of the parameters are missing from http://livedocs.phpp.org/index.php?l=enq=function.exif-thumbnail Livedocs does not handle parameters with amp; correctly, they show up blank. I'll clean exif up, and add the type information, and the ref although have we figured out a way to not confuse users with this yet? Meaning, not promote people to inapropriately pass parameters by reference at runtime. This still worries me. The rendering issues should be fixed in livedocs, and not the doc sources. (iii) The Change Log table has a rather wide first column -- this may in part be due to the long title, which I think is excessive: Version would be quite sufficient IMO. Agreed. This title should be generated with an entity anyway. There are entities named Version; and Description; in language-defs.ent, does this sound good? They are simply one word entities. Absolutely. Goba
Re: [PHP-DOC] Proposal: CHANGELOG
Type information and by reference passing should be included IMHO too. BTW the names of the parameters are missing from http://livedocs.phpp.org/index.php?l=enq=function.exif-thumbnail Livedocs does not handle parameters with amp; correctly, they show up blank. I'll clean exif up, and add the type information, and the ref although have we figured out a way to not confuse users with this yet? Meaning, not promote people to inapropriately pass parameters by reference at runtime. This still worries me. The rendering issues should be fixed in livedocs, and not the doc sources. Done. But if this information is shown it seems we'd also have to include all parameter information, like if it's optional. Look again at the exif_thumbnail() docs for how this might look: http://livedocs.phpp.org/index.php?l=enq=function.exif-thumbnail As far as rendering, right now amp; and [] are typed into the parameter listing and this feels dirty. If we could use a role with the parameter tag (Curt suggested this in irc) it might solve this. For example: [parameter role=refwidth/parameter] This way we'd not have to type amp; in the parameter listing, or in the methodsynopsis. For non-methodparam use we might either add a role like refopt or type it out: parameter role=ref choice=optwidth/parameter But anyway Goba what tags (if any) do you suggest for this? Regards, Philip
Re: [PHP-DOC] Proposal: CHANGELOG
Done. But if this information is shown it seems we'd also have to include all parameter information, like if it's optional. Look again at the exif_thumbnail() docs for how this might look: http://livedocs.phpp.org/index.php?l=enq=function.exif-thumbnail As far as rendering, right now amp; and [] are typed into the parameter listing and this feels dirty. If we could use a role with the parameter tag (Curt suggested this in irc) it might solve this. For example: [parameter role=refwidth/parameter] This way we'd not have to type amp; in the parameter listing, or in the methodsynopsis. For non-methodparam use we might either add a role like refopt or type it out: parameter role=ref choice=optwidth/parameter But anyway Goba what tags (if any) do you suggest for this? This last option seems to be fine with me. Goba
Re: [PHP-DOC] Proposal: CHANGELOG
http://livedocs.phpp.org/index.php?l=enq=function.exif-thumbnail As far as rendering, right now amp; and [] are typed into the parameter listing and this feels dirty. If we could use a role with the parameter tag (Curt suggested this in irc) it might solve this. For example: [parameter role=refwidth/parameter] This way we'd not have to type amp; in the parameter listing, or in the methodsynopsis. For non-methodparam use we might either add a role like refopt or type it out: parameter role=ref choice=optwidth/parameter But anyway Goba what tags (if any) do you suggest for this? This last option seems to be fine with me. Should go as far as adding the type here too? typeinteger/type parameter role=ref choice=optwidth/parameter VS parameter role=ref choiceopt type=integerwidth/parameter Regards, Philip
Re: [PHP-DOC] Proposal: CHANGELOG
parameter role=ref choice=optwidth/parameter But anyway Goba what tags (if any) do you suggest for this? This last option seems to be fine with me. Should go as far as adding the type here too? typeinteger/type parameter role=ref choice=optwidth/parameter VS parameter role=ref choiceopt type=integerwidth/parameter Parameter has no type attribute, so only the former is possible. Goba
Re: [PHP-DOC] Proposal: CHANGELOG
(ii) Parameter List: I'd like to see this kept as compact as possible, so I'd prefer to do without the vertical spacing between the parameter name and its description. (Also, if it were possible to merge the top and bottom dashed borders, that would be great!) However, I would like to see the type information repeated here, so I don't have to refer back to the proto if the associated description doesn't make it obvious to me (including an if it's a by-reference parameter). Type information and by reference passing should be included IMHO too. BTW the names of the parameters are missing from http://livedocs.phpp.org/index.php?l=enq=function.exif-thumbnail (iii) The Change Log table has a rather wide first column -- this may in part be due to the long title, which I think is excessive: Version would be quite sufficient IMO. Agreed. This title should be generated with an entity anyway. (iv) Return Values: fine (but, as an aside, I'd question the wording of this particular example -- I think it should be a general rule to quote the principal return value first, with out-of-range possibilities afterwards, so: Returns the embedded thumbnail, or FALSE if the image contains no thumbnail.) Yup! Overall this seems like the way to go. Very much agreed! Goba
Re: [PHP-DOC] Proposal: CHANGELOG
* Thus wrote Gabor Hojtsy: BTW the names of the parameters are missing from http://livedocs.phpp.org/index.php?l=enq=function.exif-thumbnail livedocs doesnt seem to like: parameteramp;width/parameter And is very picky with whitespace between methodparam as well. Curt -- First, let me assure you that this is not one of those shady pyramid schemes you've been hearing about. No, sir. Our model is the trapezoid!
Re: [PHP-DOC] Proposal: CHANGELOG
(ii) Parameter List: I'd like to see this kept as compact as possible, so I'd prefer to do without the vertical spacing between the parameter name and its description. (Also, if it were possible to merge the top and bottom dashed borders, that would be great!) However, I would like to see the type information repeated here, so I don't have to refer back to the proto if the associated description doesn't make it obvious to me (including an if it's a by-reference parameter). Type information and by reference passing should be included IMHO too. BTW the names of the parameters are missing from http://livedocs.phpp.org/index.php?l=enq=function.exif-thumbnail Livedocs does not handle parameters with amp; correctly, they show up blank. I'll clean exif up, and add the type information, and the ref although have we figured out a way to not confuse users with this yet? Meaning, not promote people to inapropriately pass parameters by reference at runtime. This still worries me. The new exif docs will be posted to phpdoc later today. (iii) The Change Log table has a rather wide first column -- this may in part be due to the long title, which I think is excessive: Version would be quite sufficient IMO. Agreed. This title should be generated with an entity anyway. There are entities named Version; and Description; in language-defs.ent, does this sound good? They are simply one word entities. Regards, Philip
RE: [PHP-DOC] Proposal: CHANGELOG
On 10 August 2004 23:53, Philip Olson wrote: I'll work on some examples, this is going to be good. Here's an example where: * Two new sections: Parameter listing and CHANGELOG * The parameter listing is a variablelist * The CHANGELOG is a table http://livedocs.phpp.org/index.php?l=enq=function.exif-thumbnail This looks pretty nice except the table has a title and we don't need that so next we'll use an informal table. Also, the following has a long description that pushes down the parameter listing but it doesn't appear to be a major (or common) problem: http://livedocs.phpp.org/index.php?l=enq=function.exif-read-data Oh, I like these! I have a few comments that I'd like to cast into the pool for discussion: (i) Personally, I'd like to see the Parameter Information and Change Log before the full description, so I'd go for something like: Definition(proto + *short* description of purpose -- the first para of each of these would suffice) Parameter List Change Log Return Values Description (the rest of the full description) However, YMMV! (ii) Parameter List: I'd like to see this kept as compact as possible, so I'd prefer to do without the vertical spacing between the parameter name and its description. (Also, if it were possible to merge the top and bottom dashed borders, that would be great!) However, I would like to see the type information repeated here, so I don't have to refer back to the proto if the associated description doesn't make it obvious to me (including an if it's a by-reference parameter). In keeping with point (i), I'd also prefer these entries to be a minimal description of purpose, with amplification if necessary (such as the table for the sections parameter in exif_read_data()) in the long Description section. (iii) The Change Log table has a rather wide first column -- this may in part be due to the long title, which I think is excessive: Version would be quite sufficient IMO. (iv) Return Values: fine (but, as an aside, I'd question the wording of this particular example -- I think it should be a general rule to quote the principal return value first, with out-of-range possibilities afterwards, so: Returns the embedded thumbnail, or FALSE if the image contains no thumbnail.) Overall this seems like the way to go. Yay! Go for it! Cheers! Mike - Mike Ford, Electronic Information Services Adviser, Learning Support Services, Learning Information Services, JG125, James Graham Building, Leeds Metropolitan University, Headingley Campus, LEEDS, LS6 3QS, United Kingdom Email: [EMAIL PROTECTED] Tel: +44 113 283 2600 extn 4730 Fax: +44 113 283 3211
RE: [PHP-DOC] Proposal: CHANGELOG
On Wed, 11 Aug 2004, Ford, Mike [LSS] wrote: Oh, I like these! I have a few comments that I'd like to cast into the pool for discussion: (i) Personally, I'd like to see the Parameter Information and Change Log before the full description, so I'd go for something like: Definition(proto + *short* description of purpose -- the first para of each of these would suffice) Parameter List Change Log Return Values Description (the rest of the full description) However, YMMV! I agree with this, but Changelog should be last. (ii) Parameter List: I'd like to see this kept as compact as possible, so I'd prefer to do without the vertical spacing between the parameter name and its description. Yes, it's too large now, and please no dashed borders, just stick to the style that was already used on the page. (iii) The Change Log table has a rather wide first column -- this may in part be due to the long title, which I think is excessive: Version would be quite sufficient IMO. Agreed. (iv) Return Values: fine (but, as an aside, I'd question the wording of this particular example -- I think it should be a general rule to quote the principal return value first, with out-of-range possibilities afterwards, so: Returns the embedded thumbnail, or FALSE if the image contains no thumbnail.) yeah! Derick
RE: [PHP-DOC] Proposal: CHANGELOG
Oh, I like these! I have a few comments that I'd like to cast into the pool for discussion: (i) Personally, I'd like to see the Parameter Information and Change Log before the full description, so I'd go for something like: Definition(proto + *short* description of purpose -- the first para of each of these would suffice) Parameter List Change Log Return Values Description (the rest of the full description) However, YMMV! I agree with this, but Changelog should be last. I thought about this but here's why I went with one description. First, the short definition (purpose) is already in the refpurpose of the function. Also, writing a summary for each would be a bit too difficult. As far as using just the first para, I think it'd be confusing having it so far apart from the rest of the description as they are often tied together. And something to keep in mind is long descriptions are rare. I agree return values should go after the parameter list. So here's my thoughts on the matter: Description (full) Parameter List Return Values Changelog Examples See Also The changelog has important information, enough so that it should go before the examples. I believe the only part that needs further discussion and thought is the Description. (ii) Parameter List: I'd like to see this kept as compact as possible, so I'd prefer to do without the vertical spacing between the parameter name and its description. Yes, it's too large now, and please no dashed borders, just stick to the style that was already used on the page. I'm not concerned with the look of livedocs right now and it uses the default livedoc style sheets (nothing was altered), just a simple variablelist. (iii) The Change Log table has a rather wide first column -- this may in part be due to the long title, which I think is excessive: Version would be quite sufficient IMO. Agreed. Sounds good. (iv) Return Values: fine (but, as an aside, I'd question the wording of this particular example -- I think it should be a general rule to quote the principal return value first, with out-of-range possibilities afterwards, so: Returns the embedded thumbnail, or FALSE if the image contains no thumbnail.) yeah! This is how functions are done currently, except a few, like this one ;) This rule will be added to the HOWTO although IIRC it's listed somewhere. Regards, Philip.
Re: [PHP-DOC] Proposal: CHANGELOG
I thought about this but here's why I went with one description. First, the short definition (purpose) is already in the refpurpose of the function. Also, writing a summary for each would be a bit too difficult. As far as using just the first para, I think it'd be confusing having it so far apart from the rest of the description as they are often tied together. And something to keep in mind is long descriptions are rare. I agree return values should go after the parameter list. So here's my thoughts on the matter: Description (full) Parameter List Return Values Changelog Examples See Also The changelog has important information, enough so that it should go before the examples. I believe the only part that needs further discussion and thought is the Description. Chagelog affects parameters, return values, and other types of behaviour, so it should be after the description of these IMHO. I am fine with Philip's above suggestion. Goba
Re: [PHP-DOC] Proposal: CHANGELOG
Gabor Hojtsy wrote: I thought about this but here's why I went with one description. First, the short definition (purpose) is already in the refpurpose of the function. Also, writing a summary for each would be a bit too difficult. As far as using just the first para, I think it'd be confusing having it so far apart from the rest of the description as they are often tied together. And something to keep in mind is long descriptions are rare. I agree return values should go after the parameter list. So here's my thoughts on the matter: Description (full) Parameter List Return Values Changelog Examples See Also The changelog has important information, enough so that it should go before the examples. I believe the only part that needs further discussion and thought is the Description. Chagelog affects parameters, return values, and other types of behaviour, so it should be after the description of these IMHO. I am fine with Philip's above suggestion. Fine with me too. Mehdi
Re: [PHP-DOC] Proposal: CHANGELOG
I'll work on some examples, this is going to be good. Here's an example where: * Two new sections: Parameter listing and CHANGELOG * The parameter listing is a variablelist * The CHANGELOG is a table http://livedocs.phpp.org/index.php?l=enq=function.exif-thumbnail This looks pretty nice except the table has a title and we don't need that so next we'll use an informal table. Also, the following has a long description that pushes down the parameter listing but it doesn't appear to be a major (or common) problem: http://livedocs.phpp.org/index.php?l=enq=function.exif-read-data Overall this seems like the way to go. The exif extension had an enormous number of changes in PHP 4.3.0 so keep that in mind. Thanks to Sean for hosting this wonderful version of livedocs! :) Regards, Philip
Re: [PHP-DOC] Proposal: CHANGELOG
If you expect a table layout, why overload simple paragraphs with attributes? If it is going to be a table, then para is not right for the markup IMHO. It does not fit semantically and does not fit into DocBook either. BTW I have not checked, but I don't think docbook has a version attribute which applies to para :) What would be the problem with using table markup for changelogs? The idea was to allow other formatting by livedocs but if we want to go table then let's just do that and do so with a list of role entities inside of language-defs.ent (similar to the reftitle entities). Well, as far as I have seen, you intend to start implementing these changelogs before livedocs goes really live, so these need to be sensibly rendered with the DSSSL / XSLT tools we use currently. If it is a table and it gets some special mark via a role or something, it can still be displayed differently later in livedocs if needed. I copied the version tag from your example! :) It was an intentionally dumb example with dumb tag names :) A table feels better for the changelog, still not sure about the parameter listing. The manual may look nice with the parameter list using a varlist while the changelog uses a table. Both using table would be a lot of tables! Agreed. I'll work on some examples, this is going to be good. Good. Goba
Re: [PHP-DOC] Proposal: CHANGELOG
Okay this sounds good, let's do it! The following would go right along with our new refsect1 style, does it appear doable? refsect1 reftitle.changelog; para role=changed-behavior version=4.3.0 foo() is binary safe. /para para role=changed-parameter version=4.2.0 The length parameter is optional with a default value of 1024. /para para role=new-parameter version=4.1.0 length /para /refsect1 The above would output something similar to: CHANGELOG --- |Version | Role | Description | --- |4.3.0| |foo() is binary safe.| --- |4.2.0| |The length parameter is optional | | | |with a default value of 1024 | --- |4.1.0| |length | --- Also, the changelog would go below the return value refsect. If the above format won't work please provide a specific style so we can implement ASAP! Through time we may add additional roles. If you expect a table layout, why overload simple paragraphs with attributes? If it is going to be a table, then para is not right for the markup IMHO. It does not fit semantically and does not fit into DocBook either. BTW I have not checked, but I don't think docbook has a version attribute which applies to para :) What would be the problem with using table markup for changelogs? The use of present tense seems appropriate here although one could debate using past tense. Currently the manual uses past tense AFAIR (became optional, etc) Goba
Re: [PHP-DOC] Proposal: CHANGELOG
The above would output something similar to: CHANGELOG --- |Version | Role | Description | --- |4.3.0| |foo() is binary safe.| --- |4.2.0| |The length parameter is optional | | | |with a default value of 1024 | --- |4.1.0| |length | --- Also, the changelog would go below the return value refsect. If the above format won't work please provide a specific style so we can implement ASAP! Through time we may add additional roles. If you expect a table layout, why overload simple paragraphs with attributes? If it is going to be a table, then para is not right for the markup IMHO. It does not fit semantically and does not fit into DocBook either. BTW I have not checked, but I don't think docbook has a version attribute which applies to para :) What would be the problem with using table markup for changelogs? The idea was to allow other formatting by livedocs but if we want to go table then let's just do that and do so with a list of role entities inside of language-defs.ent (similar to the reftitle entities). I copied the version tag from your example! :) A table feels better for the changelog, still not sure about the parameter listing. The manual may look nice with the parameter list using a varlist while the changelog uses a table. Both using table would be a lot of tables! I'll work on some examples, this is going to be good. Regards, Philip
Re: [PHP-DOC] Proposal: CHANGELOG
changelog changedparameter parameterlength/parameter version4.2.0/version para Became optional with a default value of 1024. /para /changedparameter ... /changelog Maybe it's not generic enough, could we cover every condition? changedbehavior, newparameter, etc. Thoughts? As the TODO suggests we planned to introduce roles, and not new tags. In fact we are currently not using any nonDocBook tags. It would be good to investigate the available docbook tags to mark up a changelog. BTW I think the detail of the changelog you provided above is too much. We only need filtering for versions IMHO. The, like somesecttag id=.changes para role=changed-parameter version=4.2.0 The length parameter became optional with a default value of 1024. /para /somesecttag This exact tagging would of course mean that the rendering system need to handle the 4.2.0 version mark, and need to prepend it before the paragraph (at least :). Otherwise we are unable to do it with the current DSSSL sheets. I am not completely unable to tweak DSSSL sheets in such a simple situation copying and customizing existing stuff :) Okay this sounds good, let's do it! The following would go right along with our new refsect1 style, does it appear doable? refsect1 reftitle.changelog; para role=changed-behavior version=4.3.0 foo() is binary safe. /para para role=changed-parameter version=4.2.0 The length parameter is optional with a default value of 1024. /para para role=new-parameter version=4.1.0 length /para /refsect1 The above would output something similar to: CHANGELOG --- |Version | Role | Description | --- |4.3.0| |foo() is binary safe.| --- |4.2.0| |The length parameter is optional | | | |with a default value of 1024 | --- |4.1.0| |length | --- Also, the changelog would go below the return value refsect. If the above format won't work please provide a specific style so we can implement ASAP! Through time we may add additional roles. The use of present tense seems appropriate here although one could debate using past tense. Regards, Philip
Re: [PHP-DOC] Proposal: CHANGELOG
Now as to the CHANGELOG, I am guessing nobody will implement it in DSSSL (I know I won't) so focusing on livedocs may end up happening. Livedocs or bust, 2004! Or 2005, 2006, 2007,. I don't mind focusing on livedocs, because I have some free time now. But I would like to have the oficial website to test it to receive some feedback. I'll send some patches to Ilia to correct some bugs I've noted, and I'll try to implement the ooclass tag correctly. We can equally provide a link to another site, if someone opts to set up livedocs, and says he has the CPU and bandwidth to serve testers. Some people already host public livedocs instances, like John and Curt. Goba
Re: [PHP-DOC] Proposal: CHANGELOG
What it will contain: 1) Parameter changes (new, modified, ...) 2) Function changes (new features, new behaviors, ...) 3) PHP Version info for each change From TODO: new roles: seealso, newparameter, and changedparameter. That idea is similar and here's one of the threads on the topic: http://marc.theaimsgroup.com/?l=phpdocm=105612826212630 So rather than just sticking this information in a changelog we'll want to have php version ids for each change so that parsing them would be easier (like creating one huge changelog list somewhere per php version, and adding ability to highlight changes since a given PHP version via my.php and CSS). Any ideas on implementing this or should we just keep it simple and write plain old para's? I prefer implementing per version but not sure how yet, do you? :) Implementing my.php can be done later but also be planned for. Having this information in each parameters definition would get a little messy so we probably should keep definitions and changelog entries seperate. Parameter definitions would describe the current behavior. A possible format: changelog changedparameter parameterlength/parameter version4.2.0/version para Became optional with a default value of 1024. /para /changedparameter ... /changelog Maybe it's not generic enough, could we cover every condition? changedbehavior, newparameter, etc. Thoughts? As the TODO suggests we planned to introduce roles, and not new tags. In fact we are currently not using any nonDocBook tags. It would be good to investigate the available docbook tags to mark up a changelog. BTW I think the detail of the changelog you provided above is too much. We only need filtering for versions IMHO. The, like somesecttag id=.changes para role=changed-parameter version=4.2.0 The length parameter became optional with a default value of 1024. /para /somesecttag This exact tagging would of course mean that the rendering system need to handle the 4.2.0 version mark, and need to prepend it before the paragraph (at least :). Otherwise we are unable to do it with the current DSSSL sheets. I am not completely unable to tweak DSSSL sheets in such a simple situation copying and customizing existing stuff :) Goba
Re: [PHP-DOC] Proposal: CHANGELOG
A partial proposal: CHANGELOG refsect1 What it will contain: 1) Parameter changes (new, modified, ...) 2) Function changes (new features, new behaviors, ...) 3) PHP Version info for each change From TODO: new roles: seealso, newparameter, and changedparameter. Of course this is a good idea, but I don't know how hard is the implemetation. With this we could have costumized manuals for each php version (with livedocs). My only concern is how to implement all this... My docbook knowledge isn't good, as well as XSLT, dsssl, etc... Do anyone have enough time to implement this at 100%? I don't have many ideas for you (yet). I'm gonna think on the subject later. This would be great and it's a perfect time to implement because when people update old docs to the new refsect1 style we would also implement these changelog entries! Woohoo!!! What is the new refsext1 style? The credits tag?... Nuno
Re: [PHP-DOC] Proposal: CHANGELOG
A partial proposal: CHANGELOG refsect1 What it will contain: 1) Parameter changes (new, modified, ...) 2) Function changes (new features, new behaviors, ...) 3) PHP Version info for each change From TODO: new roles: seealso, newparameter, and changedparameter. Of course this is a good idea, but I don't know how hard is the implemetation. With this we could have costumized manuals for each php version (with livedocs). We'll have to be careful here because we don't want person A reading person B's version of the manual and getting confused. I was thinking of only differentiated CSS stylesheets but maybe you mean something like that. Just as long as different manual builds aren't floating around. My only concern is how to implement all this... My docbook knowledge isn't good, as well as XSLT, dsssl, etc... Do anyone have enough time to implement this at 100%? I don't have many ideas for you (yet). I'm gonna think on the subject later. The lack of a DSSSL and XSLT guru has plagued our work for years so perhaps the use of livedocs will change all of that. If not implemented in DSSSL we'd have to wait until livedocs becomes official. Of course both would be ideal :) This would be great and it's a perfect time to implement because when people update old docs to the new refsect1 style we would also implement these changelog entries! Woohoo!!! What is the new refsext1 style? The credits tag?... Each manual page is split up in sections, see language-defs.ent for a list of entities and the exif/mysqli docs for examples. Some of the mysqli docs list examples after the see also so we'd want to change that unless everyone feels that a change in order is needed. I don't! I committed a new doc skeleton to the HOWTO as well. I was fairly certain this was agreed upon but don't remember any official call for votes. Now as to the CHANGELOG, I am guessing nobody will implement it in DSSSL (I know I won't) so focusing on livedocs may end up happening. Livedocs or bust, 2004! Regards, Philip
Re: [PHP-DOC] Proposal: CHANGELOG
This would be great and it's a perfect time to implement because when people update old docs to the new refsect1 style we would also implement these changelog entries! Woohoo!!! What is the new refsext1 style? The credits tag?... Each manual page is split up in sections, see language-defs.ent for a list of entities and the exif/mysqli docs for examples. Some of the mysqli docs list examples after the see also so we'd want to change that unless everyone feels that a change in order is needed. I don't! I committed a new doc skeleton to the HOWTO as well. I was fairly certain this was agreed upon but don't remember any official call for votes. Oh, I remember of seeing a discussion about the structure used in mysqli docs (which is like PEAR). I think we shouldn't do a mass change of the structure or translators kill us! We could implement it from time to time in new extensions or in re-written pages. Now as to the CHANGELOG, I am guessing nobody will implement it in DSSSL (I know I won't) so focusing on livedocs may end up happening. Livedocs or bust, 2004! Or 2005, 2006, 2007,. I don't mind focusing on livedocs, because I have some free time now. But I would like to have the oficial website to test it to receive some feedback. I'll send some patches to Ilia to correct some bugs I've noted, and I'll try to implement the ooclass tag correctly. Nuno
[PHP-DOC] Proposal: CHANGELOG
A partial proposal: CHANGELOG refsect1 What it will contain: 1) Parameter changes (new, modified, ...) 2) Function changes (new features, new behaviors, ...) 3) PHP Version info for each change From TODO: new roles: seealso, newparameter, and changedparameter. That idea is similar and here's one of the threads on the topic: http://marc.theaimsgroup.com/?l=phpdocm=105612826212630 So rather than just sticking this information in a changelog we'll want to have php version ids for each change so that parsing them would be easier (like creating one huge changelog list somewhere per php version, and adding ability to highlight changes since a given PHP version via my.php and CSS). Any ideas on implementing this or should we just keep it simple and write plain old para's? I prefer implementing per version but not sure how yet, do you? :) Implementing my.php can be done later but also be planned for. Having this information in each parameters definition would get a little messy so we probably should keep definitions and changelog entries seperate. Parameter definitions would describe the current behavior. A possible format: changelog changedparameter parameterlength/parameter version4.2.0/version para Became optional with a default value of 1024. /para /changedparameter ... /changelog Maybe it's not generic enough, could we cover every condition? changedbehavior, newparameter, etc. Thoughts? This would be great and it's a perfect time to implement because when people update old docs to the new refsect1 style we would also implement these changelog entries! Woohoo!!! Regards, Philip
Re: [PHP-DOC] Proposal: CHANGELOG
I like the theory, its always handy to tell what has changed between version x and version y. The implementation on the other hand, will be a bit more interesting i think. Nathan. On Wednesday 28 July 2004 12:25, Philip Olson wrote: A partial proposal: CHANGELOG refsect1 What it will contain: 1) Parameter changes (new, modified, ...) 2) Function changes (new features, new behaviors, ...) 3) PHP Version info for each change From TODO: new roles: seealso, newparameter, and changedparameter. That idea is similar and here's one of the threads on the topic: http://marc.theaimsgroup.com/?l=phpdocm=105612826212630 So rather than just sticking this information in a changelog we'll want to have php version ids for each change so that parsing them would be easier (like creating one huge changelog list somewhere per php version, and adding ability to highlight changes since a given PHP version via my.php and CSS). Any ideas on implementing this or should we just keep it simple and write plain old para's? I prefer implementing per version but not sure how yet, do you? :) Implementing my.php can be done later but also be planned for. Having this information in each parameters definition would get a little messy so we probably should keep definitions and changelog entries seperate. Parameter definitions would describe the current behavior. A possible format: changelog changedparameter parameterlength/parameter version4.2.0/version para Became optional with a default value of 1024. /para /changedparameter ... /changelog Maybe it's not generic enough, could we cover every condition? changedbehavior, newparameter, etc. Thoughts? This would be great and it's a perfect time to implement because when people update old docs to the new refsect1 style we would also implement these changelog entries! Woohoo!!! Regards, Philip
