Max TenEyck Woodbury max@mtew.isa-geek.net 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 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 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
On 08/02/2010 11:18 AM, James Mckenzie wrote:
Max TenEyck Woodburymax@mtew.isa-geek.net wrote:
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 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
On Mon, Aug 2, 2010 at 18:16, Max TenEyck Woodbury max@mtew.isa-geek.net 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-bandwidt...
Some more: http://blogs.msdn.com/b/innovation/archive/2009/10/26/launching-lightweight-...
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
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
On Mon, Aug 2, 2010 at 19:26, Max TenEyck Woodbury max@mtew.isa-geek.net 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 reliable links to the content)
Gert
-
Gert van den Berg -
James Mckenzie -
Max TenEyck Woodbury