Hi,
At the moment we have a very outdated version of the auto-generated "make htmlpages" Wine API documentation at http://source.winehq.org/WineAPI/ I want to fix this. * *I believe that the API documentation is important for a number of reasons: 1. It might provide info to ISVs that might think about porting an app to Wine as to whether the APIs that they use are implemented or not. 2. It provides info about undocumented functions. 3. It provides an alternative source to MSDN in case it becomes unavailable for whatever reason. 4. It spreads the word about Wine through high search engine rankings, making it more likely that someone will stumble upon Wine and start coding for fun. * *It appears that this was previously generated at release time by the wine_release script (http://cvs.winehq.org/cvsweb/tools/wine_release), but was disabled over 2 years ago. I was wondering what the reason was, but I guess it is that it takes a long time to build and a lot of CPU time. We don't really want the WineHQ web server to be running at 100% CPU for ~20 minutes while it builds the API documentation.
Therefore I propose that I could send a tarball of the documentation to Newman every release, every month, or after a major update of the documentation (whichever is sooner) and he can put it up in the appropriate location. Alternatively, we could also put the auto-generated docs in cvs and generate diffs.
Alexandre, any comments about how the release process should work with regard to the Wine API documentation? Newman, which method of updating would you prefer? Any one else have any comments at all about this?
Thanks,
On 11/8/05, Robert Shearman rob@codeweavers.com wrote:
*I believe that the API documentation is important for a number of reasons:
- It might provide info to ISVs that might think about porting an app
to Wine as to whether the APIs that they use are implemented or not. 2. It provides info about undocumented functions. 3. It provides an alternative source to MSDN in case it becomes unavailable for whatever reason. 4. It spreads the word about Wine through high search engine rankings, making it more likely that someone will stumble upon Wine and start coding for fun.
Any one else have any comments at all about this?
I agree with you on each of these points and think the docs should be updated again.
-- James Hawkins
Robert Shearman wrote:
*It appears that this was previously generated at release time by the wine_release script (http://cvs.winehq.org/cvsweb/tools/wine_release), but was disabled over 2 years ago. I was wondering what the reason was, but I guess it is that it takes a long time to build and a lot of CPU time. We don't really want the WineHQ web server to be running at 100% CPU for ~20 minutes while it builds the API documentation.
I agree the docs should be built, maybe we could use the sf.net compile farm to do it?
Ivan.
On Wed, 09 Nov 2005 00:38:19 +0100, Robert Shearman rob@codeweavers.com wrote:
We don't really want the WineHQ web server to be running at 100% CPU for ~20 minutes while it builds the API documentation.
couldn't it just be niced down to a low priority ? Even if it took a day to compile.
On 11/9/05, wino@piments.com wino@piments.com wrote:
On Wed, 09 Nov 2005 00:38:19 +0100, Robert Shearman rob@codeweavers.com wrote:
We don't really want the WineHQ web server to be running at 100% CPU for ~20 minutes while it builds the API documentation.
couldn't it just be niced down to a low priority ? Even if it took a day to compile.
I don't think it would be hard to write a script to compile it depending on what's been modified. Then it shouldn't take more than a few seconds to generate html for one or two changed files. It could either do it dynamically, or once a day or something. The system could be built into a nice interface with several features. I would propose things such as: - Keyword database for searches. We could even have an xmlrpc script to complete people's searches as they type them (like Google suggest). - Either an editable content area on each page (wiki-style) or user comment posting - Ability to put a function under one or more categories, and the ability to have categories inside other categories. - List functions by file / directory.
I have done a lot of php programming, I might be able to help make such a system. Is there much interest in something like this?
n0dalus.
Robert Shearman rob@codeweavers.com writes:
*It appears that this was previously generated at release time by the wine_release script (http://cvs.winehq.org/cvsweb/tools/wine_release), but was disabled over 2 years ago. I was wondering what the reason was, but I guess it is that it takes a long time to build and a lot of CPU time. We don't really want the WineHQ web server to be running at 100% CPU for ~20 minutes while it builds the API documentation.
It doesn't really take that much time actually, only a couple of minutes, that's not a problem. I've added it to the release script.
On Wed, 2005-11-09 at 05:31 -0600, Alexandre Julliard wrote:
Robert Shearman rob@codeweavers.com writes:
*It appears that this was previously generated at release time by the wine_release script (http://cvs.winehq.org/cvsweb/tools/wine_release), but was disabled over 2 years ago. I was wondering what the reason was, but I guess it is that it takes a long time to build and a lot of CPU time. We don't really want the WineHQ web server to be running at 100% CPU for ~20 minutes while it builds the API documentation.
It doesn't really take that much time actually, only a couple of minutes, that's not a problem. I've added it to the release script.
Cool, that works for me. Since today was a release day it is all updated now. Enjoy.
-
Alexandre Julliard -
Ivan Leo Puoti -
James Hawkins -
Jeremy Newman -
n0dalus -
Robert Shearman -
wino＠piments.com