On Wed, Apr 27, 2005 at 09:31:38AM -0400, Greg Troxel wrote:
> man pages.  Please specify in the Makefile/README or someplace which
> macro package, and that probably deserves somelooking into.  I
> suspect it's -man, rather than -mandoc.

I'm not sure, right now it is whatever the docbook/linuxdoc sgml
converter spat out. It looks like the ones that were in docbook format
look pretty good in nroff, but the linuxdoc ones that I converted
yesterday are pretty ugly and I noticed when trying to add the
documentation for -port to updatesrv.8 that manedit actually messes up
the formatting of those quite a bit when it saves the file back.

I think it both are using -man macros though.

>   The "official" versions of both manuals will be released
>   as HTML (both on-line browsable and as a tarball) along
>   with a PDF or PS version on our website, where the
>   on-line version has the ability to add user comments at
>   the bottom of each page (that Jan explored with some of
>   you on codalist).
> 
> Presumably you will use docbook for these, and that sounds fine.  I'd
> like to see the source released or perhaps just accessible via CVS.

Actually right now it is a mix of outdated linuxdoc and docbook-sgml
(probably docbook version 3). But we're most likely going to use
straight HTML for any future updates.

> I think that Coda would be better off in the long run with a bit more
> open development model.  I'm not asking you to give cvs commit privs
> to lots of people, or indeed anyone outside of CMU, but even if [cmu]
> just put the barest outline of tutorials in docbook cvs and invited
> patches.  I would avoid conflating 'blessed' and 'in cvs/released on
> coda website' - it seems easy enough to have a document status comment
> at the beginning.

Trying to keep the development as open as possible, CVS commit
mailinglist, viewcvs access to the repository, and anonymous cvs access.
However, I think one problem is that Coda is fairly complex as a whole,
and admittedly not quite well documented. The best documentation is
probably the various PhD theses that I actually rely on most in many
cases since they describe the higher-level design and intent of what the
code is doing.

Another problem is that bugs typically happen when you are trying to get
something else done, and the last thing on someones mind is to start
wading through code hunting for the problem. Working on the client can
be challenging at times, if some experimental client code is broken, I
can't even access my email anymore (and might even lose some). For
servers there is a similar development problem, you don't want to mess
up servers that store actual data, but not many people have a couple of
extra spare servers around if they want to try to work on some hard
server replication related problem (any takers to tackle cross-directory
rename resolution? ;).

And there are the minor things, like the main CVS repository being in
AFS, so it actually isn't all that easy to give commit privs to people
that do not have a CMU CS account. Even people that work with us during
the summer often can't get direct access.

>     Greg (coda user since 1997 or 1998 - don't remember any more)

Wow, just found my first email to codalist, that brings me back. I can't
believe it actually worked on that hardware.
    http://www.coda.cs.cmu.edu/maillists/codalist/codalist-1997/0111.html

Jan