Re: [Gnu-arch-users] new documentation progress

[John A Meinel]

Tom Lord wrote:
> I've been working up some new docs in "handbook" format.
> It's not done yet but there's enough to get the sense:
>
>   http://www.seyza.com/src/docs-tla/my/id.html
>
> and
>
>   http://www.gnuarch.org/src/docs-tla/my/id.html
>
> I'm open to "early feedback" at this stage although
> the development pace for these docs is very fast
> so it won't be "early" for long :-)
>
> -t

I would suggest re-ordering the tutorial slightly. You have "creating
local mirrors" coming before "checking out a project".
While local mirrors are nice, until we get write-through in tla
mainline, I think they cause more confusion to beginners than their
performance improvements.

I agree with Anand's suggestions for local directories ~/arch/archives,
~/arch/mirrors (I might to ~/arch/revlib 'cause it's shorter).

I don't know that you need to have my-id, my-revision-library, and
my-default-archive before you do a checkout, but since people I've
worked with don't use a revlib, it might be fine to just tell them "do
this step first".

You might want to mention that "my-default-archive" is similar to the
environment variable CVSROOT, though you may not want to mention cvs
similarities/differences.

In:
http://www.gnuarch.org/src/docs-tla/checkout/checkout.html

You have category + branch = "project". Is that the official naming
structure? Because at least in the code this is called a "package" with
c+b+v = package_version, I don't know what c+b+v+r is but a+c+b+v+r =
"fully qualified revision name".

It might be good just to have a glossary with the official naming of all
the different pieces of the namespace. I believe it was posted to the
mailing list once, but it is probably good to have a refresher.


In http://www.gnuarch.org/src/docs-tla/checkout/tree-state.html
You say to inspect the history with "tla revisions -r -s". It *might* be
better to have them use "tla logs -r -s" since that uses the local
information rather than connecting to the archive. Which means it is
*much* faster. But I suppose it doesn't handle revisions which aren't in
the local tree yet. I still vote for "tla logs", though.

5.1
has a link to http://www.gnuarch.org/src/docs-tla/my/archiveloc.html
which should be 2.2, but 2.2 is:
http://www.gnuarch.org/src/docs-tla/my/archloc.html

(no "ive") I would probably recommend actually changing 2.2 to include
the ive, since it seems more complete.

You defined $ARCHIVE_DIR in previous places you might want to define
$ARCHIVE_NAME to do something similar to address@hidden
Maybe not, though.

Just a quick runthrough and some suggestions.

John
=:->

signature.asc
Description: OpenPGP digital signature