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