I was just wondering about one thing - whether it would be a good idea to tag the APIs in the documentation with the Pike version number where they appeared? That would enormously help in writing "portable" (as in cross-pike) scripts.
marek
It's a bit of effort to keep that updated. Wouldn't it be enough to have older manuals available? That's how I usually look things up when I have to get code working with various versions of Emacs and XEmacs.
/ Martin Stjernholm, Roxen IS
Previous text:
2003-02-07 00:05: Subject: API version tagging
I was just wondering about one thing - whether it would be a good idea to tag the APIs in the documentation with the Pike version number where they appeared? That would enormously help in writing "portable" (as in cross-pike) scripts.
marek
/ Brevbäraren
On Fri, Feb 07, 2003 at 01:10:01AM +0100, Martin Stjernholm, Roxen IS @ Pike developers forum scribbled:
It's a bit of effort to keep that updated. Wouldn't it be enough to
Well, actually not that much. You tag the API once - when you add it. I think it would be enough to start with Pike 7.5, since 7.4 was the first release with the autodocs.
have older manuals available? That's how I usually look things up when I have to get code working with various versions of Emacs and XEmacs.
Well, I guess it's ok for developers like us, but people coming in to learn pike wouldn't rather be happy if they had to jump between two (or more) sets of documentation.
marek
Well, I guess it's ok for developers like us, but people coming in to learn pike wouldn't rather be happy if they had to jump between two (or more) sets of documentation.
Why would someone new to Pike be interested in API changes in the first place?
/ Martin Nilsson (Åskblod)
Previous text:
2003-02-07 01:23: Subject: Re: API version tagging
On Fri, Feb 07, 2003 at 01:10:01AM +0100, Martin Stjernholm, Roxen IS @ Pike developers forum scribbled:
It's a bit of effort to keep that updated. Wouldn't it be enough to
Well, actually not that much. You tag the API once - when you add it. I think it would be enough to start with Pike 7.5, since 7.4 was the first release with the autodocs.
have older manuals available? That's how I usually look things up when I have to get code working with various versions of Emacs and XEmacs.
Well, I guess it's ok for developers like us, but people coming in to learn pike wouldn't rather be happy if they had to jump between two (or more) sets of documentation.
marek
/ Brevbäraren
Well, for one, all systems are not using the latest release. A lot of newcomers want to do Roxen/Caudium coding and are in some ways stuck to older versions of pike.
I've encountered very few newcommers that merly wants to take pike out for a spin...
/ Peter Lundqvist (disjunkt)
Previous text:
2003-02-07 01:26: Subject: Re: API version tagging
Well, I guess it's ok for developers like us, but people coming in to learn pike wouldn't rather be happy if they had to jump between two (or more) sets of documentation.
Why would someone new to Pike be interested in API changes in the first place?
/ Martin Nilsson (Åskblod)
Yes, but that isn't an answer to my question, is it?
/ Martin Nilsson (Åskblod)
Previous text:
2003-02-07 01:31: Subject: Re: API version tagging
Well, for one, all systems are not using the latest release. A lot of newcomers want to do Roxen/Caudium coding and are in some ways stuck to older versions of pike.
I've encountered very few newcommers that merly wants to take pike out for a spin...
/ Peter Lundqvist (disjunkt)
On Fri, Feb 07, 2003 at 01:30:01AM +0100, Martin Nilsson (Åskblod) @ Pike (-) developers forum scribbled:
Well, I guess it's ok for developers like us, but people coming in to learn pike wouldn't rather be happy if they had to jump between two (or more) sets of documentation.
Why would someone new to Pike be interested in API changes in the first place?
Because they would have started using Pike 7.4 and are interested in Pike 7.5, for example. Or any casual coder who wants to ensure that his/hers scripts will run on several machines with various pike versions. Or not-so-casual coders who want the same but are (understandably) to browse two huge docsets just to find the information that should be readily available at the first sight. Maybe I'm wrong, but such "details" also add up to the quality of software. And, as we all know, Pike's biggest problem has always been the lack of good documentation - since we have a way to change that now, why not do it?
marek
Compatibility issues should be taken care of by #pike.
I would be nice and swell if a complete paper trail of how all functions and classes changed throughout the ages, but I have some sceptisism how making it harder to write documentation would improve things. If there were hords of eager technical writers begging for CVS-access or at least someone who occasionally lended a hand it would be one thing, but as it is today I think our very limited resources are better spent elsewhere.
However, if you whop together something neat that takes the generated XML-files for autodoc from several Pike versions and presentes the changes between the versions we would all think of it as a good and noble deed.
/ Martin Nilsson (Åskblod)
Previous text:
2003-02-07 01:47: Subject: Re: API version tagging
On Fri, Feb 07, 2003 at 01:30:01AM +0100, Martin Nilsson (Åskblod) @ Pike (-) developers forum scribbled:
Well, I guess it's ok for developers like us, but people coming in to learn pike wouldn't rather be happy if they had to jump between two (or more) sets of documentation.
Why would someone new to Pike be interested in API changes in the first place?
Because they would have started using Pike 7.4 and are interested in Pike 7.5, for example. Or any casual coder who wants to ensure that his/hers scripts will run on several machines with various pike versions. Or not-so-casual coders who want the same but are (understandably) to browse two huge docsets just to find the information that should be readily available at the first sight. Maybe I'm wrong, but such "details" also add up to the quality of software. And, as we all know, Pike's biggest problem has always been the lack of good documentation - since we have a way to change that now, why not do it?
marek
/ Brevbäraren
On Fri, Feb 07, 2003 at 02:00:01AM +0100, Martin Nilsson (Åskblod) @ Pike (-) developers forum scribbled:
Compatibility issues should be taken care of by #pike.
How? Will future Pike versions implement new APIs for #pike 7.4 or others? If somebody uses a new API then no #pike will help them with older pikes out there.
I would be nice and swell if a complete paper trail of how all functions and classes changed throughout the ages, but I have some sceptisism how
Note, that I only meant one thing - when a given API appeared in Pike. That's pretty much 90% of the problematic cases, I'd say.
making it harder to write documentation would improve things. If there
http://www.php.net/manual/en/function.umask.php
do you know why, among other reasons, php is so popular? Because their documentation makes it easy for people to get acquainted with the language _and_ to know which APIs they can use to be backwards compatible. In the current state of things, when people using Pike have to run the same code under 0.6, 7.0, 7.2 and 7.4 (7.5 not counted yet), such information:
umask [0.6] (or whenever it appeared)
would be an enormous help for some.
were hords of eager technical writers begging for CVS-access or at least someone who occasionally lended a hand it would be one thing, but as it is today I think our very limited resources are better spent elsewhere.
It's a magic circle. You won't get more users by not writing documentation and if you don't get more users, nobody would be willing to improve the documentation. It's enough (IMHO) to add a committer's rule to the Pike CVS policy to tag new APIs with the current Pike version number - either in the autodoc or in some external file listing all the public APIs. I imagine it might be possible to write an API listing generator by writing a script that loads all the modules that are found in the standard Pike and does indices() on them writing all the methods to the listing file. Done once manually, it can be automated later on.
However, if you whop together something neat that takes the generated XML-files for autodoc from several Pike versions and presentes the changes between the versions we would all think of it as a good and noble deed.
Wouldn't the method I presented above be better? Is there any way to get the list of all the modules Pike can find? If so, then writing such a generator script wouldn't that hard, I guess.
marek
For what it's worth, I like the idea, however not to the extent that I would start hacking at it. As Martin Stjernholm has already mentioned, the version of a class/method/constant/variable's first appearance can not be thought of as the first version where the docs apply in full, but in my opinion (and yours, I presume) the information is still of some value.
Adding something to this effect was in the back of our minds when we invented the autodoc system, though it was not one of those things we had to have from the beginning, and since then nobody thought of it much. I would however welcome a tag noting the version of the first appearance.
/ Johan Sundström (a hugging punishment!)
Previous text:
2003-02-07 04:01: Subject: Re: API version tagging
On Fri, Feb 07, 2003 at 02:00:01AM +0100, Martin Nilsson (Åskblod) @ Pike (-) developers forum scribbled:
Compatibility issues should be taken care of by #pike.
How? Will future Pike versions implement new APIs for #pike 7.4 or others? If somebody uses a new API then no #pike will help them with older pikes out there.
I would be nice and swell if a complete paper trail of how all functions and classes changed throughout the ages, but I have some sceptisism how
Note, that I only meant one thing - when a given API appeared in Pike. That's pretty much 90% of the problematic cases, I'd say.
making it harder to write documentation would improve things. If there
http://www.php.net/manual/en/function.umask.php
do you know why, among other reasons, php is so popular? Because their documentation makes it easy for people to get acquainted with the language _and_ to know which APIs they can use to be backwards compatible. In the current state of things, when people using Pike have to run the same code under 0.6, 7.0, 7.2 and 7.4 (7.5 not counted yet), such information:
umask [0.6] (or whenever it appeared)
would be an enormous help for some.
were hords of eager technical writers begging for CVS-access or at least someone who occasionally lended a hand it would be one thing, but as it is today I think our very limited resources are better spent elsewhere.
It's a magic circle. You won't get more users by not writing documentation and if you don't get more users, nobody would be willing to improve the documentation. It's enough (IMHO) to add a committer's rule to the Pike CVS policy to tag new APIs with the current Pike version number - either in the autodoc or in some external file listing all the public APIs. I imagine it might be possible to write an API listing generator by writing a script that loads all the modules that are found in the standard Pike and does indices() on them writing all the methods to the listing file. Done once manually, it can be automated later on.
However, if you whop together something neat that takes the generated XML-files for autodoc from several Pike versions and presentes the changes between the versions we would all think of it as a good and noble deed.
Wouldn't the method I presented above be better? Is there any way to get the list of all the modules Pike can find? If so, then writing such a generator script wouldn't that hard, I guess.
marek
/ Brevbäraren
Le vendredi, 7 fév 2003, à 02:00 Europe/Paris, Martin Nilsson (Åskblod) @ Pike (-) developers forum a écrit :
Compatibility issues should be taken care of by #pike.
I think this is too easy to says "use #pike 7.x to have you old code works".
I just give you an little example: on caudium there is a server/config_action/ftpstatus.pike that use clone() call.
Adding a #pike 7.2 make it compile. But not running. This is not a big issue you know, but compatibility is not the unique solution. The solution is to make code that use non specific calls... And to be aware that such call are in all versions of Pike.
When I am doing some Pike code, for 7.2 and 7.4 for example, I have to check manualy in hilfe if " this interressing call in 7.4 does exist on 7.2 (or 7.0) and if it working well". Most times I have to dig into both pike 7.2 and 7.4 source code (even in C) to see the differences when I have no clues.
Another example, does Remote.client/server are working indently of pike version you have ? (eg does Remote.server - pike 7.4 - can have successfull connections from a Remote.client using pike 7.2 ?)
Mu 0,02€. /Xavier
That are the woes of not having a good manual for 7.2.
Another example, does Remote.client/server are working indently of pike version you have ? (eg does Remote.server - pike 7.4 - can have successfull connections from a Remote.client using pike 7.2 ?)
I at least have taken care to keep the protocol compatible (as long as the side running in the later version doesn't use new features in it). Doesn't it work?
/ Martin Stjernholm, Roxen IS
Previous text:
2003-02-07 14:22: Subject: Re: API version tagging
Le vendredi, 7 fév 2003, à 02:00 Europe/Paris, Martin Nilsson (Åskblod) @ Pike (-) developers forum a écrit :
Compatibility issues should be taken care of by #pike.
I think this is too easy to says "use #pike 7.x to have you old code works".
I just give you an little example: on caudium there is a server/config_action/ftpstatus.pike that use clone() call.
Adding a #pike 7.2 make it compile. But not running. This is not a big issue you know, but compatibility is not the unique solution. The solution is to make code that use non specific calls... And to be aware that such call are in all versions of Pike.
When I am doing some Pike code, for 7.2 and 7.4 for example, I have to check manualy in hilfe if " this interressing call in 7.4 does exist on 7.2 (or 7.0) and if it working well". Most times I have to dig into both pike 7.2 and 7.4 source code (even in C) to see the differences when I have no clues.
Another example, does Remote.client/server are working indently of pike version you have ? (eg does Remote.server - pike 7.4 - can have successfull connections from a Remote.client using pike 7.2 ?)
Mu 0,02. /Xavier
/ Brevbäraren
I much rather see time spent on getting the docs complete for the current version, though. Compared to that I think version info in the manual is of little value.
Perhaps this is brought up because there are no good manuals for older versions? I.e. people rather look in the latest manual because most things actually are documented there and then sees this problem when they find that the stuff mentioned in the docs doesn't exist in their version? Then the problem is the lack of good old manuals, and, well, the interest for writing complete manuals for 0.6, 7.0 and 7.2 is probably not overwhelming.. :\
/ Martin Stjernholm, Roxen IS
Previous text:
2003-02-07 01:47: Subject: Re: API version tagging
On Fri, Feb 07, 2003 at 01:30:01AM +0100, Martin Nilsson (Åskblod) @ Pike (-) developers forum scribbled:
Well, I guess it's ok for developers like us, but people coming in to learn pike wouldn't rather be happy if they had to jump between two (or more) sets of documentation.
Why would someone new to Pike be interested in API changes in the first place?
Because they would have started using Pike 7.4 and are interested in Pike 7.5, for example. Or any casual coder who wants to ensure that his/hers scripts will run on several machines with various pike versions. Or not-so-casual coders who want the same but are (understandably) to browse two huge docsets just to find the information that should be readily available at the first sight. Maybe I'm wrong, but such "details" also add up to the quality of software. And, as we all know, Pike's biggest problem has always been the lack of good documentation - since we have a way to change that now, why not do it?
marek
/ Brevbäraren
On Fri, Feb 07, 2003 at 02:15:01AM +0100, Martin Stjernholm, Roxen IS @ Pike developers forum scribbled:
I much rather see time spent on getting the docs complete for the current version, though. Compared to that I think version info in the manual is of little value.
I beg to differ.
Perhaps this is brought up because there are no good manuals for older versions? I.e. people rather look in the latest manual because most things actually are documented there and then sees this problem when they find that the stuff mentioned in the docs doesn't exist in their version? Then the problem is the lack of good old manuals, and, well, the interest for writing complete manuals for 0.6, 7.0 and 7.2 is probably not overwhelming.. :\
Indeed, and you are right about the reason. Precisely for that cause, the API introduction version should be listed in the docs.
marek
It's not just new functions. You have to add blurbs about added arguments too and other changed semantics etc. If it should remain readable it is a bit of extra work, in my experience.
/ Martin Stjernholm, Roxen IS
Previous text:
2003-02-07 01:23: Subject: Re: API version tagging
On Fri, Feb 07, 2003 at 01:10:01AM +0100, Martin Stjernholm, Roxen IS @ Pike developers forum scribbled:
It's a bit of effort to keep that updated. Wouldn't it be enough to
Well, actually not that much. You tag the API once - when you add it. I think it would be enough to start with Pike 7.5, since 7.4 was the first release with the autodocs.
have older manuals available? That's how I usually look things up when I have to get code working with various versions of Emacs and XEmacs.
Well, I guess it's ok for developers like us, but people coming in to learn pike wouldn't rather be happy if they had to jump between two (or more) sets of documentation.
marek
/ Brevbäraren
On Fri, Feb 07, 2003 at 01:40:01AM +0100, Martin Stjernholm, Roxen IS @ Pike developers forum scribbled:
It's not just new functions. You have to add blurbs about added arguments too and other changed semantics etc. If it should remain readable it is a bit of extra work, in my experience.
How often do you change arguments, though? And if you change them, then you can mark the version where it changed in the argument description - which you have to modify anyway.
marek
Fairly often (while backward incompatible changes are of course rare). It's much more common that I improve old functions in one way or the other than that I add new functions.
And if you change them, then you can mark the version where it changed in the argument description - which you have to modify anyway.
The only way to do it with negligible effort is to copy the old description and then update one of the copies. That's however a sure way of making the documentation unreadable and I definitely don't want the current docs cluttered up with compatibility stuff. That can be a set of notes at the bottom that are easy to skip, else I think it's better left out completely.
/ Martin Stjernholm, Roxen IS
Previous text:
2003-02-07 01:54: Subject: Re: API version tagging
On Fri, Feb 07, 2003 at 01:40:01AM +0100, Martin Stjernholm, Roxen IS @ Pike developers forum scribbled:
It's not just new functions. You have to add blurbs about added arguments too and other changed semantics etc. If it should remain readable it is a bit of extra work, in my experience.
How often do you change arguments, though? And if you change them, then you can mark the version where it changed in the argument description - which you have to modify anyway.
marek
/ Brevbäraren
That only works when comparing fully documented versions of Pike. I guess it would be possible to add more dummy-documentation (@fixme Document this function) so at least all prototypes can be read. It is however hard to figure out what is the actual API in some modules...
/ Martin Nilsson (Åskblod)
Previous text:
2003-02-07 01:09: Subject: API version tagging
It's a bit of effort to keep that updated. Wouldn't it be enough to have older manuals available? That's how I usually look things up when I have to get code working with various versions of Emacs and XEmacs.
/ Martin Stjernholm, Roxen IS
pike-devel@lists.lysator.liu.se
-
Johan Sundstr�m (a hugging punishment!) ＠ Pike (-) developers forum -
Marek Habersack -
Martin Nilsson (�skblod) ＠ Pike (-) developers forum
-
Martin Stjernholm, Roxen IS ＠ Pike developers forum
-
Peter Lundqvist (disjunkt) ＠ Pike (-) developers forum
-
Xavier Beaudouin