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