I have started the WineAPI wiki at
https://sourceforge.net/apps/mediawiki/wineapi/index.php?title=Main_Page
Some issues have come up that may need to be discussed here. In particular, there is going to be an 'Overview' section for many articles and I think the information to fill it in should come from the wine source tree. Specifically, I'd like to create 'Overview.wiki' files to contain this information.
- Max
Max TenEyck Woodbury max@mtew.isa-geek.net wrote:
I have started the WineAPI wiki at
https://sourceforge.net/apps/mediawiki/wineapi/index.php?title=Main_Page
You have chosen not very good name. There is no such a thing as Wine API, Wine implements Win32 API, and doesn't specify/add anything custom to it. The name "WineAPI" implies that Wine defines its own API which is not true, and is confusing.
On 08/02/2010 07:00 AM, Dmitry Timoshkov wrote:
Max TenEyck Woodburymax@mtew.isa-geek.net wrote:
I have started the WineAPI wiki at
https://sourceforge.net/apps/mediawiki/wineapi/index.php?title=Main_Page
You have chosen not very good name. There is no such a thing as Wine API, Wine implements Win32 API, and doesn't specify/add anything custom to it. The name "WineAPI" implies that Wine defines its own API which is not true, and is confusing.
This has been discussed elsewhere on this mailing list.
There is a lot of information specific to Wine, particularly its internal structure, that is not shared with Microsoft's product. Further, there is a little confusing and incorrect information in the Microsoft documentation. Bluntly, the Microsoft documentation is what they want it to be. We need to document what it really is.
We have tried to embed API documentation in the source code. That has not worked as well as it could. Alexandre Julliard has said as much. I think that having good documentation will help the project. Not having good documentation can and does hurt Wine in my opinion. I also think that trying to prevent the creation of that documentation might be harmful.
- Max
Max TenEyck Woodbury max@mtew.isa-geek.net wrote:
You have chosen not very good name. There is no such a thing as Wine API, Wine implements Win32 API, and doesn't specify/add anything custom to it. The name "WineAPI" implies that Wine defines its own API which is not true, and is confusing.
This has been discussed elsewhere on this mailing list.
There is a lot of information specific to Wine, particularly its internal structure, that is not shared with Microsoft's product.
Then "Wine internals" or "Wine architecture" would be more appropriate.
Further, there is a little confusing and incorrect information in the Microsoft documentation. Bluntly, the Microsoft documentation is what they want it to be. We need to document what it really is.
Regardless of the quality of Microsoft documentation it's still Win32 API, not a Wine API.
On 08/02/2010 07:53 AM, Dmitry Timoshkov wrote:
Max TenEyck Woodburymax@mtew.isa-geek.net wrote:
You have chosen not very good name. There is no such a thing as Wine API, Wine implements Win32 API, and doesn't specify/add anything custom to it. The name "WineAPI" implies that Wine defines its own API which is not true, and is confusing.
This has been discussed elsewhere on this mailing list.
There is a lot of information specific to Wine, particularly its internal structure, that is not shared with Microsoft's product.
Then "Wine internals" or "Wine architecture" would be more appropriate.
But it is NOT just the internals. I believe that good API documentations should include a 'Theory of Operation' section which describes how it is actually implemented. There should also be a section that documents regression and other tests. In other words, I hope this will become a *really* good set of API documentation. So 'Wine internals' would have been a bad name for the project. Similarly 'Wine architecture' is inappropriate.
This is not particularly a name I chose. The other discussions of this have also used 'WineAPI'. I did consider your objections that you have voiced previously. I understand that the target API is in fact the Win32API, but the Win32API is not something we control. We do control the actual API Wine uses. There will be differences between the WineAPI and the Win32API. When those differences are pointed out, I expect the WineAPI will be changed to match the Win32API. We are free to do that. We are *not* free to change the Win32API.
I think 'WineAPI' is an appropriate name and better than either of the names you suggested. If anyone comes up with a better name, I will try to get the Sourceforge project name changed, but the project is currently called 'wineapi'. So, for the moment, it is what it is.
Further, there is a little confusing and incorrect information in the Microsoft documentation. Bluntly, the Microsoft documentation is what they want it to be. We need to document what it really is.
Regardless of the quality of Microsoft documentation it's still Win32 API, not a Wine API.
And it is Microsoft's documentation and nominally documents their code. We have to document *our* code. There will be differences. Differences that I expect will be removed when found unless we can show that the Microsoft documentation is, in fact, incorrect.
You are setting up a 'straw man' argument. You are assuming that we can and *have* implemented the Win32 API correctly and that Microsoft's published documentation is completely correct. We have not and Microsoft has not. Our documentation will help us fix our code. We can not and should not even try to get try to get Microsoft fix their problems. From that your argument fails.
- Max
Max TenEyck Woodbury max@mtew.isa-geek.net wrote:
Further, there is a little confusing and incorrect information in the Microsoft documentation. Bluntly, the Microsoft documentation is what they want it to be. We need to document what it really is.
Regardless of the quality of Microsoft documentation it's still Win32 API, not a Wine API.
And it is Microsoft's documentation and nominally documents their code. We have to document *our* code. There will be differences. Differences that I expect will be removed when found unless we can show that the Microsoft documentation is, in fact, incorrect.
An API is Application Programming Interface, not the code or implementation details. The API is for application programmers, not for system's analists. If the Wine implementaion of win32 differs from Microsoft one - that's a bug, it's not worth documenting, it's worth a bug report and fixing.
On 08/02/2010 11:25 AM, Dmitry Timoshkov wrote:
Max TenEyck Woodburymax@mtew.isa-geek.net wrote:
Further, there is a little confusing and incorrect information in the Microsoft documentation. Bluntly, the Microsoft documentation is what they want it to be. We need to document what it really is.
Regardless of the quality of Microsoft documentation it's still Win32 API, not a Wine API.
And it is Microsoft's documentation and nominally documents their code. We have to document *our* code. There will be differences. Differences that I expect will be removed when found unless we can show that the Microsoft documentation is, in fact, incorrect.
An API is Application Programming Interface, not the code or implementation details. The API is for application programmers, not for system's analists. If the Wine implementaion of win32 differs from Microsoft one - that's a bug, it's not worth documenting, it's worth a bug report and fixing.
Your implication that I do not know wat 'API' stands for comes very close to being an insult. Please stop.
The readable title is 'Wine API *and related documentation*'. Documentation is used for many purposes. Application programmers use it, but system's analysts also use it. Telling me that it can not be used any way but your way is arrogant.
Implementation and documentation are two different things. Bugs can, and in some cases should, be documented. I am not asking you to do anything in particular. That would be arrogance on my part.
- Max
On Mon, 2 Aug 2010, Max TenEyck Woodbury wrote: [...]
You have chosen not very good name. There is no such a thing as Wine API, Wine implements Win32 API, and doesn't specify/add anything custom to it. The name "WineAPI" implies that Wine defines its own API which is not true, and is confusing.
This has been discussed elsewhere on this mailing list.
There is a lot of information specific to Wine, particularly its internal structure, that is not shared with Microsoft's product. Further, there is a little confusing and incorrect information in the Microsoft documentation. Bluntly, the Microsoft documentation is what they want it to be. We need to document what it really is.
I think such documentation should be open to all projects involved in the Win32 space such as Mingw, React OS, as well as Windows software developpers whenever they are irritated by an MSDN deficiency.
Sure there will be differences between how each project implements a given API, just like there are differences between the Windows 98, 2000 or Vista implementations. But I expect most of the documentation to be common to all so that the best approach would be to describe the reference behavior and then have notes describing the platform-specific differences.
However calling the Wiki 'WineAPI' is not very welcoming to other contributors and it would be a shame if each project ended up duplicating this huge effort just because of a naming issue.
On 08/04/2010 03:15 PM, Francois Gouget wrote:
On Mon, 2 Aug 2010, Max TenEyck Woodbury wrote: [...]
This has been discussed elsewhere on this mailing list.
There is a lot of information specific to Wine, particularly its internal structure, that is not shared with Microsoft's product. Further, there is a little confusing and incorrect information in the Microsoft documentation. Bluntly, the Microsoft documentation is what they want it to be. We need to document what it really is.
I think such documentation should be open to all projects involved in the Win32 space such as Mingw, React OS, as well as Windows software developpers whenever they are irritated by an MSDN deficiency.
Sure there will be differences between how each project implements a given API, just like there are differences between the Windows 98, 2000 or Vista implementations. But I expect most of the documentation to be common to all so that the best approach would be to describe the reference behavior and then have notes describing the platform-specific differences.
However calling the Wiki 'WineAPI' is not very welcoming to other contributors and it would be a shame if each project ended up duplicating this huge effort just because of a naming issue.
That is a very good point!
There several things that have to be coordinated however:
- This is not just the API documentation. It includes a great deal of information about the meta-structure of the Wine project. Easy access to that meta-information might be one of the more useful aspects of this sub-project.
- The detailed information is, at least initially, coming out of the Wine code. It is being generated using scripts. The scripts are very likely to be rerun when a file in the Wine repository changes. It may take a lot of effort to merge the new information with information from other sources.
- If the licenses are compatible, it should be possible to copy articles between projects. Also, the page tree structure is based on the structure of the Wine repository. Since the Wine repository structure is fairly stable, (new parts are added fairly often, but once a piece is in place for a while, it usually stays where it is. I could definitely be wrong about this!) links into the WineAPI wiki should also be stable.
- Max
On Wed, 4 Aug 2010, Max TenEyck Woodbury wrote: [...]
There several things that have to be coordinated however:
- This is not just the API documentation. It includes a great deal of information about the meta-structure of the Wine project. Easy access to that meta-information might be one of the more useful aspects of this sub-project.
I suspect some of that information is already present in the Wine Developer's Guide, in particular the section 'II. Wine Architecture':
http://www.winehq.org/docs/winedev-guide/index
So there the issue of where to put this information: in the developper guide, in the win32 api wiki or in a separate wiki. Even if it's in the win32 api wiki I think it could be set slightly apart.
Here's roughly what I have in mind:
1. Win32 API 1. Overview 2. acledit API 1. Overview 2. Functions 1. Func1 2. Func2 ... 3. Interfaces 1. Interface 1 1. Method1 2. Method2 ... 2. Interface 2 1. Method1 2. Method2 ... 4. Datastructures 1. Struct1 2. Struct2 3. Enum1 ... 3. aclui API ... 2. Standard Windows tools 1. attrib command line options 2. cacls command line options ... 3. General platform-specific notes 1. Windows 9x Talks about interaction with DOS, etc. 2. Windows 95 More Win 9x specific general notes 3. Windows NT and greater Kernel stuff 4. Wine 1. Wine architecture documentation 2. Wine-specific dlls 3. Wine-specific tools like winebuild, winemenubuilder, etc) 5. Mingw Stuff about Mingw, etc. 6. ReactOS Stuff about ReactOS, etc.
- The detailed information is, at least initially, coming out of the Wine code. It is being generated using scripts. The scripts are very likely to be rerun when a file in the Wine repository changes. It may take a lot of effort to merge the new information with information from other sources.
No matter what, if such a wiki is meant to be edited directly you won't be able to merge in data through scripts very long. It will soon have to stand on its own.
- If the licenses are compatible, it should be possible to copy articles between projects.
Yes, licensing is an important issue and one you must solve before accepting outside contributions.
To incorportate data from the Wine source it must be LGPL-compatible (e.g. GPL). To incorporate data from the Mingw or ReactOS source it must be compatible with their license (GPL?).
Even if copying articles from one project to another is technically legal, I think you cannot count on this as a means to avoid massive duplication of effort: as soon as you have over a hundred articles (once fully sutbbed out you should have way over 30000) the work involved for watching changes on each side and merging duplicate documentation will be overwhelming (and I suspect finding volunteers for it will be hard too).
Also, the page tree structure is based on the structure of the Wine repository.
The wiki should have its own structure, independent from Wine and anything else. I would also argue that the simpler it is, the less likely it is to change.
On 08/05/2010 03:56 AM, Francois Gouget wrote:
On Wed, 4 Aug 2010, Max TenEyck Woodbury wrote: [...]
There several things that have to be coordinated however:
- This is not just the API documentation. It includes a great deal of information about the meta-structure of the Wine project. Easy access to that meta-information might be one of the more useful aspects of this sub-project.
I suspect some of that information is already present in the Wine Developer's Guide, in particular the section 'II. Wine Architecture':
http://www.winehq.org/docs/winedev-guide/indexSo there is the issue of where to put this information: in the developer guide, in the win32 api wiki or in a separate wiki. Even if it's in the win32 api wiki I think it could be set slightly apart.
Here's roughly what I have in mind:
1. Win32 API 1. Overview 2. acledit API 1. Overview 2. Functions 1. Func1 2. Func2 ... 3. Interfaces 1. Interface 1 1. Method1 2. Method2 ... 2. Interface 2 1. Method1 2. Method2 ... 4. Datastructures 1. Struct1 2. Struct2 3. Enum1 ... 3. aclui API ... 2. Standard Windows tools 1. attrib command line options 2. cacls command line options ... 3. General platform-specific notes 1. Windows 9x Talks about interaction with DOS, etc. 2. Windows 95 More Win 9x specific general notes 3. Windows NT and greater Kernel stuff 4. Wine 1. Wine architecture documentation 2. Wine-specific dlls 3. Wine-specific tools like winebuild, winemenubuilder, etc) 5. Mingw Stuff about Mingw, etc. 6. ReactOS Stuff about ReactOS, etc.
Ah! That is where the misunderstanding is. You are thinking of this as a *document*, a single coherent document. That is not quite what this is. It is a collection of *pages*. Each page has a distinct name. Those names are what the scripts maintain. The pages will also contain sub-pages. Those sub-pages are where the user-editable content are stored. Once those sub-pages are created, the scripts will not touch them. (That answers the question in my original post by the way.)
There is also technical content. Such things as the names of the entry points, the return type, the number of parameters and their types. That information really should not be subject to debate. It is determined by the implementation. That might be something the scripts can maintain, however I will leave that maintenance until later.
- The detailed information is, at least initially, coming out of the Wine code. It is being generated using scripts. The scripts are very likely to be rerun when a file in the Wine repository changes. It may take a lot of effort to merge the new information with information from other sources.
No matter what, if such a wiki is meant to be edited directly you won't be able to merge in data through scripts very long. It will soon have to stand on its own.
You had better be wrong on this particular point. If you are in fact correct, it will be impossible to keep the technical information and structural information intact. I believe the descriptive and technical information can be put on seperate pages and sub-pages. The project is still in the planning and experimental phase. The details are in the process of being worked out.
- If the licenses are compatible, it should be possible to copy articles between projects.
Yes, licensing is an important issue and one you must solve before accepting outside contributions.
To incorportate data from the Wine source it must be LGPL-compatible (e.g. GPL). To incorporate data from the Mingw or ReactOS source it must be compatible with their license (GPL?).
Even if copying articles from one project to another is technically legal, I think you cannot count on this as a means to avoid massive duplication of effort: as soon as you have over a hundred articles (once fully sutbbed out you should have way over 30000) the work involved for watching changes on each side and merging duplicate documentation will be overwhelming (and I suspect finding volunteers for it will be hard too).
Whether the information comes out of the Wine code or other code, there could be problems. But that is not where most of the value of this project will lie. It will be in the descriptive information that does not come out of the code. It will be the material the individual contributers add.
I suspect that the meta-information will in fact have to be duplicated. It can be different for the different projects. For example Wine is similar to the Microsoft stuff at the file level. They each have DLLs with corresponding names. On the other hand, WinGW consists of a single DLL, if I understand its structure correctly. But building up the meta-structure is much less difficult than creating the descriptions. I hope the descriptive information can be shared.
Also, the page tree structure is based on the structure of the Wine repository.
The wiki should have its own structure, independent from Wine and anything else. I would also argue that the simpler it is, the less likely it is to change.
There is complication here no matter how it is done. There is simply too much stuff to keep it really simple. Category markers should be used extensively. Redirection links will be needed to provide views from different perspectives without having to actually replicate articles. The one thing that should not be done is impose a single person's opinion of how it must be done on everybody else. On the other hand, someone has to start this thing.
- Max
On Thu, 5 Aug 2010, Max TenEyck Woodbury wrote: [...]
Here's roughly what I have in mind:
1. Win32 API 1. Overview 2. acledit API 1. Overview 2. Functions 1. Func1 2. Func2 ... 3. Interfaces 1. Interface 1 1. Method1 2. Method2 ... 2. Interface 2 1. Method1 2. Method2 ... 4. Datastructures 1. Struct1 2. Struct2 3. Enum1 ... 3. aclui API ... 2. Standard Windows tools 1. attrib command line options 2. cacls command line options ... 3. General platform-specific notes 1. Windows 9x Talks about interaction with DOS, etc. 2. Windows 95 More Win 9x specific general notes 3. Windows NT and greater Kernel stuff 4. Wine 1. Wine architecture documentation 2. Wine-specific dlls 3. Wine-specific tools like winebuild, winemenubuilder, etc) 5. Mingw Stuff about Mingw, etc. 6. ReactOS Stuff about ReactOS, etc.Ah! That is where the misunderstanding is. You are thinking of this as a *document*, a single coherent document.
I am not thinking of this as a single document. Each of the above line would be a separate wiki page.
[...]
Those names are what the scripts maintain.
I'm not sure what there is to maintain.
The pages will also contain sub-pages. Those sub-pages are where the user-editable content are stored.
Do you mean that the documentation for an API like CreateFile() would be a collection of pages? That seems counterproductive to me.
There is also technical content. Such things as the names of the entry points, the return type, the number of parameters and their types. That information really should not be subject to debate. It is determined by the implementation.
Well, yes. That's what Func1, Func2 are above. And on their pages you would get the signature, general documentation of the function, description of what each parameter is for, links to the pages describing the types of the parameters if they're complex, what the function returns, finer points about how the function behaves in corner cases if appropriate, and platform-specific details about how it behaves.
That might be something the scripts can maintain, however I will leave that maintenance until later.
However while it would be easy for scripts to create a skeleton page, once the page exists and has been editied they may have a hard time changing stuff like correcting the type of an output parameter.
But I guess that's why you want to have sub pages I guess. Though I really would not want to have to go through multiple pages for each of the documentation aspects I mentioned above.
I suspect that the meta-information will in fact have to be duplicated. It can be different for the different projects. For example Wine is similar to the Microsoft stuff at the file level. They each have DLLs with corresponding names. On the other hand, WinGW consists of a single DLL, if I understand its structure correctly.
My mingw-runtime package has a lot of separate 'dlls': libaclui.a, libadvapi32.a, libgdi32.a, etc. Besides, how does that matter? CreateFile() is a kernel32 fnuction, no matter what, and the documentation should reflect that.
[...]
There is complication here no matter how it is done. There is simply too much stuff to keep it really simple. Category markers should be used extensively. Redirection links will be needed to provide views from different perspectives without having to actually replicate articles.
That's one of the things I don't like in msdn. Want do know what's the API provided by a given dll? Good luck with that because they seem bent on hiding that kind of information.
I think we should really have per-dll documentation and the general articles about 'how to do sound', 'what COM is' should be in a separate section. Otherwise your documentation of CoCreateInstance() is going to keep moving from OLE to COM to DCOM and to whatever today's fashionable marketing term is.
On 08/06/2010 05:44 AM, Francois Gouget wrote:
On Thu, 5 Aug 2010, Max TenEyck Woodbury wrote: [...]
Here's roughly what I have in mind:
1. Win32 API 1. Overview 2. acledit API 1. Overview 2. Functions 1. Func1 2. Func2 ... 3. Interfaces 1. Interface 1 1. Method1 2. Method2 ... 2. Interface 2 1. Method1 2. Method2 ... 4. Datastructures 1. Struct1 2. Struct2 3. Enum1 ... 3. aclui API ... 2. Standard Windows tools 1. attrib command line options 2. cacls command line options ... 3. General platform-specific notes 1. Windows 9x Talks about interaction with DOS, etc. 2. Windows 95 More Win 9x specific general notes 3. Windows NT and greater Kernel stuff 4. Wine 1. Wine architecture documentation 2. Wine-specific dlls 3. Wine-specific tools like winebuild, winemenubuilder, etc) 5. Mingw Stuff about Mingw, etc. 6. ReactOS Stuff about ReactOS, etc.Ah! That is where the misunderstanding is. You are thinking of this as a *document*, a single coherent document.
I am not thinking of this as a single document. Each of the above line would be a separate wiki page.
[...]
Those names are what the scripts maintain.
I'm not sure what there is to maintain.
I think we are almost in agreement. The problem is the numbers. The numbers *will* change as things evolve. Hopefully, the basic reference *names* will be fairly stable. There will also be indexes from different points of view and the indexes will have sub-pages that redirect to the appropriate basic page. Maintenance will consist of keeping those redirects up-do-date.
The pages will also contain sub-pages. Those sub-pages are where the user-editable content are stored.
Do you mean that the documentation for an API like CreateFile() would be a collection of pages? That seems counterproductive to me.
There is also technical content. Such things as the names of the entry points, the return type, the number of parameters and their types. That information really should not be subject to debate. It is determined by the implementation.
Well, yes. That's what Func1, Func2 are above. And on their pages you would get the signature, general documentation of the function, description of what each parameter is for, links to the pages describing the types of the parameters if they're complex, what the function returns, finer points about how the function behaves in corner cases if appropriate, and platform-specific details about how it behaves.
That might be something the scripts can maintain, however I will leave that maintenance until later.
However while it would be easy for scripts to create a skeleton page, once the page exists and has been editied they may have a hard time changing stuff like correcting the type of an output parameter.
But I guess that's why you want to have sub pages I guess. Though I really would not want to have to go through multiple pages for each of the documentation aspects I mentioned above.
I believe I understand your concern. From observation it is not going to actually be a problem. The sub-pages are 'transcluded' into the base page. The sub-pages will contain the section headings and when you edit the section, you in fact edit the sub-page. There is a problem that you end up on the sub-page when you finish editing. I'll add a link back to the main article page, and that should make the problem smaller.
I suspect that the meta-information will in fact have to be duplicated. It can be different for the different projects. For example Wine is similar to the Microsoft stuff at the file level. They each have DLLs with corresponding names. On the other hand, WinGW consists of a single DLL, if I understand its structure correctly.
My mingw-runtime package has a lot of separate 'dlls': libaclui.a, libadvapi32.a, libgdi32.a, etc. Besides, how does that matter? CreateFile() is a kernel32 fnuction, no matter what, and the documentation should reflect that.
OK, but they are called 'aclui' in the Wine repository, not 'libaclui.a'. I think each project will want to maintain seperate meta-structure sub-pages so we do not change something about another project's meta structure when we update our own meta-structure.
There is complication here no matter how it is done. There is simply too much stuff to keep it really simple. Category markers should be used extensively. Redirection links will be needed to provide views from different perspectives without having to actually replicate articles.
That's one of the things I don't like in msdn. Want do know what's the API provided by a given dll? Good luck with that because they seem bent on hiding that kind of information.
I think we should really have per-dll documentation and the general articles about 'how to do sound', 'what COM is' should be in a separate section. Otherwise your documentation of CoCreateInstance() is going to keep moving from OLE to COM to DCOM and to whatever today's fashionable marketing term is.
Yes, that is along the lines I planned on. The 'how to's would not be 'managed', but there would be indexes and redirects for each 'API' to the place where the documentation is. In particular, there should be a 'Category:API' sorted alphabetically with links to the correct page. If a 'how to' wants to link to a particular API, it would link to the sub-page of the API index and that would redirect to the actual page.
This does require planning and I am glad it is being discussed now, before things become too embedded to change.
- Max
-
Dmitry Timoshkov -
Francois Gouget -
Max TenEyck Woodbury