Re: The WineAPI wiki.
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 th
Re: The WineAPI wiki.
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. -- Francois Gouget http://fgouget.free.fr/ "Utilisateur" (nom commun) : Mot utilisé par les informaticiens en lieu et place d'"idiot".
Re: The WineAPI wiki.
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/index So 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 3) 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 th
Re: The WineAPI wiki.
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 3) 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. -- Francois Gouget http://fgouget.free.fr/ Avoid the Gates of Hell - use Linux.
Re: The WineAPI wiki.
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
Re: The WineAPI wiki.
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. -- Francois Gouget http://fgouget.free.fr/ Linux: It is now safe to turn on your computer.
Re: The WineAPI wiki.
On Mon, Aug 2, 2010 at 19:26, Max TenEyck Woodbury
wrote:
> On 08/02/2010 01:04 PM, Gert van den Berg wrote:
>
>> There seem to be several interfaces to retreive MSDN articles... Some
>> of those interface might be more stable / provide a way to retrieve a
>> current link? (Framing the content would probably not be allowed, but
>> retreiving links should be...)
>>
> If it *looks* like copying, it should be avoided.
What I meant is, that it would allow for things like some really nice
side-to-side postings of Wine's documentation and MSDN... It is
unlikely to be legal though... (And should therefore be avoided)
> I think it will be necessary to regenerate articles as the Wine project
> evolves. I regenerated the 'dlls' page after Alexandre's CVS run today.
> There was some new content so I saved the result. I've regenerated the
> individual DLL pages several times as I improved the generating
> scripts. Both activities put a load on me that I am trying to automate.
> In fact, if you look at the original post before it got hijacked into a
> discussion of the project name, it asks about a way to improve that
> automation.
>
> Since there will be fairly frequent semi-intelligent reviews of pages,
> such queries can probably be incorporated into that process.
>
> Can you help me with this, please?
I can give an overview of what I think... I might do a bit of
implementation, but finishing something bigger than a short script
when I have other things to do isn't always easy...
Sourceforge provides quite decent hosting in the project hosting space
as well... Automating things from there might be a good idea.
To handle MSDN, I can see the following (very) high level process:
Posted MSDN links gets converted to point to redirect system in the
project space. (The conversion retrieves and save some additional
data). The redirect system will redirect the user to relevant content
on current MSDN (allowing user to configure some parameters, such as
view type / language)
What I managed to figure out about MSDN content for the Web services
documentation this far:
1. Content is identified by a Content identifier, which can be any of
the following:
a. GUID
b. Short ID (Short (~8 character) unique identifier such as ms224917)
c. Alias ("Friendly string")
d. asset ID (Documented here:
http://msdn.microsoft.com/en-us/magazine/cc163541.aspx Can be used to
retrieve other (non-URL) identifiers)
e Content URL (The URL to an MSDN page)
2. A Content key uniquely identifies an article and consists of a
content identifier, locale and version
3 The version.identifies the various versions of the documented item.
e.g. the .NET version / VC++ version
4. Locale identifies preferred language
More detailed version:
1. Find MSDN URL and retrieve other identifiers (GetContent without a
locale seem to retreive almost all the metadata ("partial match" in
the docmentaiton))
2. Store data in database, with GUID / short ID / assetID as primary
key (they are always-present unique identifiers) other fields include
alias, current URL. (content table)
3. Other tables: Locales and versions. Mapping tables between content
and possible locales and versions hould also exist. The content table
should save when the data was last updated and it should be
automatically updated once it reaches a certain age and an user wants
to retreive the page / select a non-default locale / version.
4. Generate new link pointing to the redirector system. The redirector
system needs the unique content identifier (GUID / shortID / assetID)
and preferably a version. It should be able to take a parameter to
preview the URL (probably a smaller "options link") and allow the user
to choose other locales / versions and generate links to those. This
"content options" page should also allow problems with the
redirector's link to be reported. The reports should be used to update
the information for that link by querying it again from MSDN.
It might require several trips to MSDN to initially add an item / to
update versions and locales. This should possibly scheduled once the
data get really old (somewhere between 180 days and 1 year) and be run
on demand when someone requests the content from somewhere where they
might want to see the other versions / locales about half the
scheduled update age. This should keep the request volumes to MSDN
low...
MSDN changes and updates required:
1. Changes to web services interface: Update relevant parts (This
shouldn't be too serious as long as the entire interface is not
redesigned)
2. Link changes: Change how the URLs are generated from the
identifiers in the database (I don't see an easy way to request an URL
from the web services interface)
Other possible extensions: The "redirector" can build a more complete
view of what is available to allow documentation to be found easier
(the information should only be retrieved on demand and saved) and to
prevent duplicate trips to MSDN. (This should eventually provide a
nice "tree" of MSDN with r
Re: The WineAPI wiki.
On 08/02/2010 01:04 PM, Gert van den Berg wrote: There seem to be several interfaces to retreive MSDN articles... Some of those interface might be more stable / provide a way to retrieve a current link? (Framing the content would probably not be allowed, but retreiving links should be...) If it *looks* like copying, it should be avoided. (It might also work to try and retreive as much information about MSDN links when they are posted, in order to allow the links to be updated when the site stucture change?) (Doing a web service query everytime to retreive a link would probably be slow and inefficient...) I think it will be necessary to regenerate articles as the Wine project evolves. I regenerated the 'dlls' page after Alexandre's CVS run today. There was some new content so I saved the result. I've regenerated the individual DLL pages several times as I improved the generating scripts. Both activities put a load on me that I am trying to automate. In fact, if you look at the original post before it got hijacked into a discussion of the project name, it asks about a way to improve that automation. Since there will be fairly frequent semi-intelligent reviews of pages, such queries can probably be incorporated into that process. Can you help me with this, please? - Max
Re: The WineAPI wiki.
On Mon, Aug 2, 2010 at 18:16, Max TenEyck Woodbury wrote: > There should be links to the Microsoft documentation in each article, > but Microsoft has been known to move their documentation around without > maintaining redirects. To avoid being at Microsoft's mercy in this, a > summary (*not* a duplicate) of the Microsoft articles, which would be > fair use, should be maintained. There seem to be several interfaces to retreive MSDN articles... Some of those interface might be more stable / provide a way to retrieve a current link? (Framing the content would probably not be allowed, but retreiving links should be...) http://blogs.msdn.com/b/innovation/archive/2009/04/22/launching-low-bandwidth-loband-v1-and-new-ide-view.aspx Some more: http://blogs.msdn.com/b/innovation/archive/2009/10/26/launching-lightweight-beta-view-for-msdn-library.aspx Web service interface: http://services.msdn.microsoft.com/ContentServices/ContentService.asmx (possibly the most useful for building current links?) (It might also work to try and retreive as much information about MSDN links when they are posted, in order to allow the links to be updated when the site stucture change?) (Doing a web service query everytime to retreive a link would probably be slow and inefficient...) Gert
Re: The WineAPI wiki.
On 08/02/2010 11:18 AM, James Mckenzie wrote: Max TenEyck Woodbury wrote: On 08/02/2010 07:00 AM, Dmitry Timoshkov wrote: Max TenEyck Woodbury 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 should be named, the Windows32/Window64 API as implemented by Wine Documentation site. That is what it is. We have found shortcomings in the MSDN documentation (I'm dealing with this right now in one function call for Richedit.) This should be a collaborative site where Wine developers, Windows on Wine developers and others can place information on what Wine has implemented today, what needs to be implemented (with case code and discoveries) and what Wine cannot implement. Hmm, I may change the brief project description to match that. I will think about it... 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. AJ has stated that documenting the Windows API and internal API calls should NOT be documented just in the source. It bloats the source code terribly and can make code unreadable. I agree that this Wiki should only be used to document the external interfaces to Wine as we implement Windows32/Windows64 API/ABI calls and what we have found in our testing that is different than MSDN. We should NOT duplicate MSDN where is is proper, but rather have a note that states MSDN and other sources have been found to be proper. I disagree. Really good documentation includes 'Theory of Operation'. Of course we do not have that for the Microsoft code, but it *may* be helpful for our own code. I think documenting our test code would also be useful. There should be links to the Microsoft documentation in each article, but Microsoft has been known to move their documentation around without maintaining redirects. To avoid being at Microsoft's mercy in this, a summary (*not* a duplicate) of the Microsoft articles, which would be fair use, should be maintained. - Max
Re: The WineAPI wiki.
On 08/02/2010 11:25 AM, Dmitry Timoshkov wrote: Max TenEyck Woodbury 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
Re: The WineAPI wiki.
Max TenEyck Woodbury 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. -- Dmitry.
Re: The WineAPI wiki.
Max TenEyck Woodbury wrote: >Sent: Aug 2, 2010 4:25 AM >To: wine-devel@winehq.org >Subject: Re: The WineAPI wiki. > >On 08/02/2010 07:00 AM, Dmitry Timoshkov wrote: >> Max TenEyck Woodbury 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 should be named, the Windows32/Window64 API as implemented by Wine Documentation site. That is what it is. We have found shortcomings in the MSDN documentation (I'm dealing with this right now in one function call for Richedit.) This should be a collaborative site where Wine developers, Windows on Wine developers and others can place information on what Wine has implemented today, what needs to be implemented (with case code and discoveries) and what Wine cannot implement. >This has been discussed elsewhere on this mailing list. > Agreed. >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. AJ has stated that documenting the Windows API and internal API calls should NOT be documented just in the source. It bloats the source code terribly and can make code unreadable. I agree that this Wiki should only be used to document the external interfaces to Wine as we implement Windows32/Windows64 API/ABI calls and what we have found in our testing that is different than MSDN. We should NOT duplicate MSDN where is is proper, but rather have a note that states MSDN and other sources have been found to be proper. As to the griping, we need to be public with our progress. This eliminates confusion and also gives new developers a place to start. James McKenzie
Re: The WineAPI wiki.
On 08/02/2010 07:53 AM, Dmitry Timoshkov wrote: 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. 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
Re: The WineAPI wiki.
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. 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. -- Dmitry.
Re: The WineAPI wiki.
On 08/02/2010 07:00 AM, Dmitry Timoshkov wrote: Max TenEyck Woodbury 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
Re: The WineAPI wiki.
Max TenEyck Woodbury 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. -- Dmitry.
The WineAPI wiki.
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
