[Xcb] Wiki spring cleaning

[Ian Osgood]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Thanks for the feedback, Jamey!  Revised structure:

xcb (one screen introduction, index)
	Features (and comparison with Xlib)
	XcbApi
	XlibXcb (XCL)
	DevelopersGuide (availability, build instructions, resources)
		XmlXcb
		XcbToDo
		XcbRationale (and update)
		(XcbDevelopmentPlan... DELETED!)
	History (XCL, M4)
		XcbCompletedTasks
		usingxcb
	Publications (and acknowledgements)

More below...

On May 1, 2006, at 11:18 AM, Jamey Sharp wrote:

> Thanks, Ian! This plan looks great.
>
> I'm tempted to drop the word "XCB" from most of the page titles,  
> except
> things like XmlXcb and XlibXcb where it's part of the name. The extra
> namespacing feels annoyingly redundant. Doing so means auto-linking
> won't work for many of these names, but I think that's acceptable.

Right, that's a leftover from being embedded in the freedesktop.org  
wiki.

>
> On Mon, May 01, 2006 at 10:30:20AM -0700, Ian Osgood wrote:
>> xcb (one screen introduction, release download, index)
>> 	XcbApi
>
> Eventually I suppose we'll replace most of this with a link to the
> doxygen documentation...
>
>> 	XlibXcb
>
> I just want to make sure the XlibXcb page has a link to the XCL stuff,
> since that's where it came from.
>
>> 	XcbDevelopersGuide (availability, build instructions, resources)
>> 		XmlXcb
>> 		XcbToDo
>> 		XcbDevelopmentPlan (needs an update!)
>
> The development plan should just be deleted. We don't need no  
> steenkin'
> plan, no matter what the conclusion of the XCL paper says.
>
>> 		UsingXcb (needs update?)
>
> That's a piece of commentary of historical interest, I guess. It's not
> documentation: it's really just a proposal I wrote up right before
> giving a WIP talk about it at some USENIX conference, so I could  
> have a
> URL to point people at.
>
> I guess that means it goes under XcbHistory.
>
>> 	XcbHistory (papers, acknowledgements, XCL, M4)
>
> It'd be nice to have the papers on their own Publications page so I  
> can
> link to them. But while they are technically history, they should be
> directly linked from the main page. (They can be linked from History
> too, I don't care.) The academic products of this project are an
> important part of the work.
>
> Bart: As much as I appreciate PSU's CS department and USENIX for the
> support they've given us, does it really make sense to keep the
> acknowledgments around? Or should we be extending the list?

OK, the final sentence becomes:

The XCB project has a long [History], during which it produced many  
academic [Publications].

>> 		XcbCompletedTasks
>> 		XcbRationale
>
> I think rationale is developer's documentation. There's a lot of
> rationale that still ought to be documented, though, and what's there
> has become partially obsolete with Plan 7.
>
>> Proposed front page:
>>
>> The X protocol C-language Binding (XCB) is a replacement for Xlib
>> having the advantages of:
>> * Small footprint: ...
>
> We should probably produce a Features page or something, that gives a
> little more detail about these points and lists what we support as far
> as socket protocols, authentication types, ...
>
> This bullet list should then become a sentence or two on the front  
> page
> and a link to the Features page, I think.

OK, the first sentence becomes:

The X protocol C-language Binding (XCB) is a replacement for Xlib
[:Features: featuring] a small footprint, latency hiding, direct access
to the protocol, improved threading support, and extensibility.

The Features page would also be a natural place to put the stats
comparing XCB vs. Xlib sizes, latencies, etc.

>
>> You can obtain released versions of XCB from http://
>> xcb.freedesktop.org/dist .  Follow the instructions from the
>> XcbDevelopersGuide to build, except that you can use released
>> versions of the dependencies, and you don't need git, automake,
>> autoconf, or libtool.
>
> I guess we can refactor the build instructions into "run git and
> autofoo" and then a separate page of "make; make install", so that the
> instructions in this paragraph can simply point to the latter page.
>
>> The XcbApi is documented. There is also a [http://
>> gitweb.freedesktop.org/?p=xcb;a=tree;f=xcb/doc/tutorial tutorial].
>
> It's really a shame gitweb doesn't have cvsweb's *checkout*  
> feature. We
> should probably either put up a checkout of the tutorial (and the
> doxygen documentation?) at xcb.freedesktop.org, or point at Vincent's
> copy if he's keeping it up to date there.

I like that idea! Someone want to write a script to monitor the git
repository and automatically copy the tutorial pages to the right place?

>
> Thanks again for looking into this, Ian. It being a wiki, of  
> course, you
> can go ahead and get started, and we can shake it down over time.
>
> --Jamey
> _______________________________________________
> Xcb mailing list
> Xcb at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/xcb

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (Darwin)

iD8DBQFEVlqpHDwFgzc3zyIRAh3PAJ96YJTLrdZrGhKo85mnINjTquuQCACfQscn
pn3OWGwPmFgpTV/JQw3ibSU=
=ybWM
-----END PGP SIGNATURE-----