[OpenAFS-Doc] Re: First cut of HTML reference manual
Todd M. Lewis
Todd_Lewis@unc.edu
Fri, 27 Jan 2006 09:12:46 -0500
This is a multi-part message in MIME format.
--------------010103090103070500040304
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit
Russ Allbery wrote:
> I've just finished the first cut of an HTML conversion of the OpenAFS
> reference manual that's now maintained in POD.
Yeah!
> Please look this over and mail openafs-doc@openafs.org with anything that
> looks wrong. Also, now that we have pages up in HTML, now is the time for
> people to look them over and find any problems. Ideally, patches against
> the POD source are desired, but go ahead and send notes about any problems
> that you find so that at least we can accumulate a problem list to start
> working on.
I looked for a while, but couldn't find the POD source to make a patch
against. So I made a patch against the html (sorry).
Attached is a patch for the 'up' documentation to include stuff about
the "-m" flag. "-m" has been there for several years, but the
"usage..." message from 'up' may or may not include reference to it
depending on how many parameters are passed in. (I've submitted a
separate bug/patch for up.c to openafs-bugs for that.)
Not that 'up' is the the most important utility in the suite, but it's
great that there's somewhere to document the new (3 year old)
functionality. Thanks for your efforts.
--
+--------------------------------------------------------------+
/ Todd_Lewis@unc.edu 919-445-9302 http://www.unc.edu/~utoddl /
/ "He has no enemies, but is intensely disliked /
/ by his friends." - Oscar Wilde /
+--------------------------------------------------------------+
--------------010103090103070500040304
Content-Type: text/x-patch;
name="up.html-mountpoint.patch"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
filename="up.html-mountpoint.patch"
--- up.html-orig 2006-01-25 08:25:45.000000000 -0500
+++ up.html 2006-01-25 08:39:47.000000000 -0500
@@ -25,7 +25,7 @@
<h1><a class="u" href="#___top" title="click to go to top of document" name="SYNOPSIS">SYNOPSIS</a></h1>
-<p><b>up</b> [<b>-v</b>] [<b>-1</b>] [<b>-f</b>] [<b>-r</b>] [<b>-x</b>] <<i>source directory</i>> <<i>destination directory</i>></p>
+<p><b>up</b> [<b>-v</b>] [<b>-1</b>] [<b>-f</b>] [<b>-r</b>] [<b>-x</b>] [<b>-m</b>] <<i>source directory</i>> <<i>destination directory</i>></p>
<h1><a class="u" href="#___top" title="click to go to top of document" name="DESCRIPTION">DESCRIPTION</a></h1>
@@ -95,6 +95,15 @@
<dd>
<p>Sets the modification timestamp on each file to the time of the copying operation.</p>
+</dd><dt><a name="-m"><b>-m</b></a></dt>
+
+<dd>
+<p>Recognize and copy mount points rather than traversing the volumes
+they reference during the recursive copy operation. Without <b>-m</b>,
+up's default (questionable) behavior is to copy the contents of all
+volumes and subvolumes mounted under the source directory into the
+volume containing the destination directory.</p>
+
</dd><dt><a name="source_directory"><i>source directory</i></a></dt>
<dd>
--------------010103090103070500040304
Content-Type: text/html; charset=ISO-8859-1;
name="up.html"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
filename="up.html"
<html><head><title>up</title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<link rel="stylesheet" title="style" type="text/css" href="up_files/style.css" media="all"></head><body class="pod">
<!--
generated by OpenAFS::HTML v1.0,
using Pod::Simple::PullParser v2.02,
under Perl v5.008007 at Wed Jan 25 05:47:28 2006 GMT.
If you want to change this HTML document, you probably shouldn't do that
by changing it directly. Instead, see about changing the calling options
to OpenAFS::HTML, and/or subclassing OpenAFS::HTML,
then reconverting this document from the Pod source.
When in doubt, email the author of OpenAFS::HTML for advice.
See 'perldoc OpenAFS::HTML' for more info.
-->
<!-- start doc -->
<a name="___top" class="dummyTopAnchor"></a>
<h1><a class="u" href="#___top" title="click to go to top of document" name="NAME">NAME</a></h1>
<p>up - Recursively copy directories,
preserving AFS metadata</p>
<h1><a class="u" href="#___top" title="click to go to top of document" name="SYNOPSIS">SYNOPSIS</a></h1>
<p><b>up</b> [<b>-v</b>] [<b>-1</b>] [<b>-f</b>] [<b>-r</b>] [<b>-x</b>] [<b>-m</b>] <<i>source directory</i>> <<i>destination directory</i>></p>
<h1><a class="u" href="#___top" title="click to go to top of document" name="DESCRIPTION">DESCRIPTION</a></h1>
<p>The <b>up</b> command recursively copies the files and subdirectories in a specified source directory to a specified destination directory.
The command interpreter changes the destination directory and the files and subdirectories in it in the following ways:</p>
<ul><li><p>It copies the source directory's access control list (ACL) to the destination directory and its subdirectories,
overwriting any existing ACLs.</p></li><li><p>If the issuer is logged on as the local superuser root and has AFS tokens as a member of the group system:administrators,
then the source directory's owner (as reported by the <code>ls -ld</code> command) becomes the owner of the destination directory and all files and subdirectories in it.
Otherwise,
the issuer's user name is recorded as the owner.</p></li><li><p>If a file or directory exists in both the source and destination directories,
the source version overwrites the destination version.
The overwrite operation fails if the first (user) <code>w</code> (write) mode bit is turned off on the version in the destination directory,
unless the <b>-f</b> flag is provided.</p></li><li><p>The modification timestamp on a file (as displayed by the <code>ls -l</code> command) in the source directory overwrites the timestamp on a file of the same name in the destination directory,
but the timestamp on an existing subdirectory in the destination directory remains unchanged.
If the command creates a new subdirectory in the destination directory,
the new subdirectory's timestamp is set to the time of the copy operation,
rather than to the timestamp that the subdirectory has in the source directory.</p></li></ul>
<p>The up command is idempotent,
meaning that if its execution is interrupted by a network,
server machine,
or process outage,
then a subsequent reissue of the same command continues from the interruption point,
rather than starting over at the beginning.
This saves time and reduces network traffic in comparison to the UNIX commands that provide similar functionality.</p>
<p>The <b>up</b> command returns a status code of <code>0</code> (zero) only if it succeeds.
Otherwise,
it returns a status code of <code>1</code> (one).</p>
<p>This command does not use the syntax conventions of the AFS command suites.
Provide the command name and all option names in full.</p>
<h1><a class="u" href="#___top" title="click to go to top of document" name="OPTIONS">OPTIONS</a></h1>
<dl>
<dt><a name="-v"><b>-v</b></a></dt>
<dd>
<p>Prints a detailed trace to the standard output stream as the command runs.</p>
</dd><dt><a name="-1"><b>-1</b></a></dt>
<dd>
<p>Copies only the files in the top level source directory to the destination directory,
rather than copying recursively through subdirectories.
The source directory's ACL still overwrites the destination directory's.
(This is the number one,
not the letter <code>l</code>.)</p>
</dd><dt><a name="-f"><b>-f</b></a></dt>
<dd>
<p>Overwrites existing directories,
subdirectories,
and files even if the first (user) <code>w</code> (write) mode bit is turned off on the version in the destination directory.</p>
</dd><dt><a name="-r"><b>-r</b></a></dt>
<dd>
<p>Creates a backup copy of all files overwritten in the destination directory and its subdirectories,
by adding a <code>.old</code> extension to each filename.</p>
</dd><dt><a name="-x"><b>-x</b></a></dt>
<dd>
<p>Sets the modification timestamp on each file to the time of the copying operation.</p>
</dd><dt><a name="-m"><b>-m</b></a></dt>
<dd>
<p>Recognize and copy mount points rather than traversing the volumes
they reference during the recursive copy operation. Without <b>-m</b>,
up's default (questionable) behavior is to copy the contents of all
volumes and subvolumes mounted under the source directory into the
volume containing the destination directory.</p>
</dd><dt><a name="source_directory"><i>source directory</i></a></dt>
<dd>
<p>Names the directory to copy recursively.</p>
</dd><dt><a name="destination_directory"><i>destination directory</i></a></dt>
<dd>
<p>Names the directory to which to copy.
It does not have to exist already.</p>
</dd>
</dl>
<h1><a class="u" href="#___top" title="click to go to top of document" name="EXAMPLES">EXAMPLES</a></h1>
<p>The following command copies the contents of the directory <em>dir1</em> to directory <em>dir2</em>:</p>
<pre> % up dir1 dir2</pre>
<h1><a class="u" href="#___top" title="click to go to top of document" name="PRIVILEGE_REQUIRED">PRIVILEGE REQUIRED</a></h1>
<p>The issuer must have the <code>a</code> (administer) permission on the ACL of both the source and destination directories.</p>
<h1><a class="u" href="#___top" title="click to go to top of document" name="COPYRIGHT">COPYRIGHT</a></h1>
<p>IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.</p>
<p>This documentation is covered by the IBM Public License Version 1.0.
It was converted from HTML to POD by software written by Chas Williams
and Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.</p>
<!-- end doc -->
</body></html>
--------------010103090103070500040304--