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
