The WineAPI wiki.

Max TenEyck Woodbury max at mtew.isa-geek.net
Thu Aug 5 11:16:42 CDT 2010


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 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



More information about the wine-devel mailing list