[OpenAFS-devel] pt_util documentation

[Marcus Watts]

Russ Allbery <rra@stanford.edu> writes:
...
> I have reformatted and edited this slightly and added it to the tree on
> the grounds that it's more comprehensive than what we have for Debian
> right now and I'd like to include it in the Debian package.  It's only in
> HEAD right now though in case you'd rather that I not pull it up yet; I
> wanted to give you a chance to object.
> 
> Unfortunately, I think we probably should include the copyright and
> license statement directly in the man page if it's necessary, since
> otherwise distributions like Debian get in trouble if the packages with
> the man pages don't all depend on a package that provides the copyright
> page.
> 
> I haven't yet studied Sam's man page in detail to be sure that this
> includes everything it has.
...

At a quick glance, I believe mine has everything Sam's had,
excepting for the GFDL license.  I also have more details,
examples, and warnings.

I've got a slightly updated copy:

/afs/umich.edu/group/itd/build/mdw/pt_util.pod
/afs/umich.edu/group/itd/build/mdw/umich.copyright.pod

and the 2 together as a patch (against cvs head of 20060913):
/afs/umich.edu/group/itd/build/mdw/afs-doc-ptutil.patch

(these don't have your edits -- sorry, I did these a while back.)

I got smarter about copyright -- the pod source has a copyright
statement that doesn't appear unless you look at the pod directly.
I believe this is sufficient; if you can't find the copyright
notice, then you can't legally make copies.  In modern copyright
law, works without an explicit copyright are assumed to have an implicit
copyright held by the author, and you can't safely make copies without
gaining permission of the copyright owner.  So, people who are smart
enough to find the pod source can easily figure out they can
make copies.  :-)  I left the separate pod page & pointer as well,
that way unless parts of the package gets dropped (why?) even people
who can't find the pod source can figure out what happened.  I think
either copyright mechanism would suffice by itself.

In the case of the University of Michigan, there is certainly nobody here
at umich that wants the copyright to be highly visible.  The main concern
folks here appear to have is the possibly of creating an implied warranty
(or otherwise profitting at the expense of the university's name), which
means if you mention the name of the University of Michigan, you're
stuck also including the big long warranty paragraph.  At one point, the
warranty was legally necessary; I've heard that's no longer true, but I don't
know what changed or if the University shares that belief.  Unfortunately,
that means you can't just include the 3 lines that assert the umich name,
and leave the permissions & warranty out; it's pretty much an all or nothing
deal.

If it helps any - the same legal reasoning that says the man pages
should display a copyright notice also says that the "pts" command
ought to spit out a copyright notice, everytime it is run.

Anyways, that's all I really want to say on copyright.  If you still
feel the copyright statement should be visible in its entirity, go for it.
It's also fine by me if you want to include this in 1.5 or 1.4.

I don't plan to make more changes to pt_util.pod in the near future.
I am more likely to do one of these things first:
	pt_util -initialize <admin>:<admin's-id>
	pts -localauth
the former would simplify the current ugly syntax, the later
should make it completely unnecessary.  I think the main problem
with "-localauth" for pts is specifying the id of the creator
for those operations that need to know that.  My workaround
for that will probably be that such objects will be either "self-created",
or created by "anonymous".  The later will duplicate the results of
the transarc "-noauth" directions.

					-Marcus Watts