The WineAPI wiki.

Max TenEyck Woodbury max at mtew.isa-geek.net
Fri Aug 6 08:55:28 CDT 2010


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



More information about the wine-devel mailing list