[cairo] Cairo documentation

[Behdad Esfahbod]

On Thu, 2007-07-05 at 07:37 -0700, Carl Worth wrote:
> On Thu, 05 Jul 2007 09:45:30 -0400, Behdad Esfahbod wrote:
> > On Wed, 2007-07-04 at 10:10 -0400, Carl Worth wrote:
> >
> > Umm, I'm not sure I like this.  Yeah, I definitely don't.
> >
> > What if, we put the web stuff inside cairo's main git repo?
> 
> That seems easy, but it does get tricky... (see below).
> 
> > Say, cairo/www?  Doesn't have to go into tarballs, but at least we can drop
> > cairo/TODO etc and move them in www/, then make "make dist" copy them
> > into cairo/ just for the tarball.
> 
> Actually, I would like to have something even in the distributed tar
> file. Remember I recently pointed out that I'd like for people to be
> able to step directly into a "doc" directory and start reading. So one
> trick is that some of the documentation wants to live at different
> places in the source repository, (like things like TODO up at the
> toplevel), and another is that the .mdwn extension isn't obviously
> inviting to a new reader.
> 
> So we could fix that by putting everything where it is most natural in
> the source repository, and then make the update hook script that
> generates the web page move things to where it expects them, (and
> perhaps add a .mdwn extension).
> 
> The biggest problem though, is that the wiki is setup to be
> world-editable. I'm totally comfortable doing that for descriptive
> text for documentation/web pages, but I don't feel as comfortable
> making our canonical source-code repository writable from the web.
> (Right now, the source code lives on an entirely separate machine from
> any web-facing stuff, since we generally don't trust any of it
> completely.)
> 
> Suggestions?

Definitely not put cairo source under the wiki, though that would be an
interesting concept.  How about the git external module thingie?  Can we
make the source tree fetch the web tree automatically as a separate git
repo?

> Do we have two repositories and commit to both with moderation for
> moving web-based commits from one to the other?

Umm. That may be too much.

> -Carl

Cheers,
-- 
behdad
http://behdad.org/

"Those who would give up Essential Liberty to purchase a little
 Temporary Safety, deserve neither Liberty nor Safety."
        -- Benjamin Franklin, 1759