[cairo] Cairo documentation

[Carl Worth]

On Mon, 25 Jun 2007 12:17:08 +0200, Nis Martensen wrote:
>  - The following URLs (from http://cairographics.org/documentation/) are
>    currently "403 Forbidden":
> 	http://cairographics.org/TODO
> 	http://cairographics.org/ROADMAP
> 	http://cairographics.org/BIBLIOGRAPHY

Now that (finally) the new wiki is running, I've gone and fixed
these. (The old capitalized names now redirect permanently to
lowercase names.)

Also, please note that the above URLs no longer fetch data from the
files that exist within the "cairo" source-code repository. Instead,
the data has been copied to live within the wiki itself. The old setup
was in place just because I wanted to make it easy to keep the pages
up to date with "git push" since editing the old wiki was so
painful. But now that all pages in the wiki can be maintained with
git, that problem no longer exists.

So now there's a new issue of what to do with the now-stale copies
that exist in the library's repository. One option would be to just
remove them from source control and maybe fetch them from cairo-www
just before creating tar files. Another option could be to create a
cairo-documentation repository that both cairo-www and cairo could
pull in as a sub-module.

>  - Both the start page and http://cairographics.org/news/ do not mention
>    the 1.4.8 release. Is the note on the bottom of the start page still
>    up to date?

These should be all up to date now.

>  - Looking for documentation on how to get started with cairo, I started
>    by looking into the doc/tutorial directory of the source distribution.
>    Unfortunately, this was not helpful:

Oh, my. I didn't realize that stuff was there.

>    It looks as if it was planned to put some of the demos here, but this
>    work was stalled? Should the README be updated to reflect the current
>    status?

What that actually was was a talk that I gave at one time, (and at the
time of that talk, there was actually something at
http://cairographics.org/tutorial). And yes, I _had_ planned at the
time to turn what I did into something that people could use without
me there talking about it, but it definitely did stall.

I really hadn't realized that we were shipping these stale doc bits.

Frankly, I consider cairo's state of documentation to be extremely
embarrassing. All we've got is several false starts and nothing
cohesive. (The most complete thing we have is the API reference but I
consider that as only useful for someone who has already _learned_
cairo and just needs to reference some details. I don't consider it at
all useful for _learning_ cairo in the first place.)

So I still consider cairo entirely undocumented, but I really would
like to see that get fixed. And I'd love for the new wiki to be a
place for that to happen. Oh! One big thing I forgot to mention. The
old wiki made it excruciatingly painful to upload images so the
website has basically never had any, (which is awful for a
graphics-related website of course). With ikiwiki this is now really
easy, (at least as long as one uses the git interface instead of the
web interface). So I'd love to see the smattering of different
tutorial links on cairographics.org/tutorial become quickly obsolete
by folding the best content that they contain into a new wiki-based
cairographics.org/tutorial.

>  - It would be nice if the cairo-demo programs were more easily
>    accessible---For example, if they could be downloaded via git or as a
>    tarball.

Yes. And for the ones that make sense, we should have a nice web
interface to be able to view both code and resulting images online,
(see notes at cairographics.org/todo about integrating old /samples
and cairo-demo into the wiki).

>  - Finally I found some typos in some READMEs. Patch attached.

Thanks. I've committed this locally so this will get pushed out later,
(when I come to terms with the new external-pixman-library-requiring
cairo).

-Carl
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://cairographics.org/archives/cairo/attachments/20070704/06807fe0/attachment.pgp