[SvnBook] #67: [PATCH] Hanchrow review [appc:appd]
SvnBook
noreply at red-bean.com
Fri Aug 10 21:11:04 CDT 2007
#67: [PATCH] Hanchrow review [appc:appd]
-------------------------+--------------------------------------------------
Reporter: cmpilato | Owner: nobody
Type: enhancement | Status: new
Priority: normal | Milestone: 1.5
Component: content | Version:
Keywords: |
-------------------------+--------------------------------------------------
From: Eric Hanchrow <offby1 at blarg.net>
{{{
Index: appc-webdav.xml
===================================================================
--- appc-webdav.xml (revision 2737)
+++ appc-webdav.xml (working copy)
@@ -20,7 +20,7 @@
<sect1 id="svn.webdav.basic">
<title>Basic WebDAV Concepts</title>
- <para>This section provides a very brief, very general overview to
+ <para>This section provides a very brief, very general overview of
the ideas behind WebDAV. It should lay the foundation for
understanding WebDAV compatibility issues between clients and
servers.</para>
@@ -50,9 +50,8 @@
<varlistentry>
<term>Resources</term>
<listitem>
- <para> WebDAV lingo refers to any server-side object
- (that can be described with a URI) as a
- <firstterm>resource</firstterm>.</para>
+ <para> Any server-side object
+ that can be described with a URI.</para>
</listitem>
</varlistentry>
@@ -187,7 +186,7 @@
performs a <literal>CHECKOUT</literal> on each
resource it wishes to change and sends
<literal>PUT</literal> requests. Finally, the client
- performs a <literal>CHECKIN</literal> resource, or
+ performs a <literal>CHECKIN</literal> on the resource, or
sends a <literal>MERGE</literal> request to check in
all resources at once.</para>
</listitem>
@@ -238,7 +237,7 @@
<para>The original WebDAV standard has been widely successful.
Every modern computer operating system has a general WebDAV
client built-in (details to follow), and a number of popular
- standalone applications are also able to speak WebDAV —
+ standalone applications are also able to speak WebDAV—
Microsoft Office, Dreamweaver, and Photoshop to name a few. On
the server end, the Apache webserver has been able to provide
WebDAV services since 1998 and is considered the de-facto
@@ -319,7 +318,7 @@
standard. A typical DeltaV server will reject an ignorant
WebDAV client attempting to do a <literal>PUT</literal> to a
file that's under version control. To change a
- version-controlled file, the server expects a series proper
+ version-controlled file, the server expects a series of proper
versioning requests: something like
<literal>MKACTIVITY</literal>, <literal>CHECKOUT</literal>,
<literal>PUT</literal>, <literal>CHECKIN</literal>. But if the
@@ -332,7 +331,10 @@
<para>Because so many operating systems already have integrated
WebDAV clients, the use case for this feature borders on
- fantastical: imagine an office of ordinary users running
+ fantastical:
+ <!-- let's not go crazy here. In practice it seems
+ autoversioning isn't all that useful. -->
+ imagine an office of ordinary users running
Microsoft Windows or Mac OS. Each user <quote>mounts</quote>
the Subversion repository, which appears to be an ordinary
network folder. They use the shared folder as they always do:
@@ -365,7 +367,7 @@
number of automatically committed revisions. For example, when
saving data, many clients will do a <literal>PUT</literal> of a
0-byte file (as a way of reserving a name) followed by another
- <literal>PUT</literal> with the real filedata. The single
+ <literal>PUT</literal> with the real data. The single
file-write results in two separate commits. Also consider that
many applications auto-save every few minutes, resulting in even
more commits.</para>
@@ -435,6 +437,9 @@
offerings, as well as their general category, can be found in
the sections that follow.</para>
+ <!-- this table might be more useful if it was sorted by the
+ second column ("Category") first, and then by the first column
+ ("Software"). -->
<table id="svn.webdav.clients.tbl-1">
<title>Common WebDAV Clients</title>
<tgroup cols="3">
@@ -528,8 +533,7 @@
<sect2 id="svn.webdav.clients.standalone">
<title>Standalone WebDAV applications</title>
- <para>A WebDAV application is a program which contains built-in
- functionality for speaking WebDAV protocols with a WebDAV
+ <para>A WebDAV application is a program which speaks WebDAV
protocols with a WebDAV
server. We'll cover some of the most popular programs with
this kind of WebDAV support.</para>
@@ -567,14 +571,14 @@
<para>Cadaver is a bare-bones Unix commandline program for
browsing and changing WebDAV shares. Like the Subversion
client, it uses the neon HTTP library—not surprisingly,
- both neon and cadaver are written by the same author. Cadaver
+ since both neon and cadaver are written by the same author.
Cadaver
is free software (GPL license) and is available at <ulink
url="http://www.webdav.org/cadaver/"/>.</para>
<para>Using cadaver is similar to using a commandline FTP
program, and thus it's extremely useful for basic WebDAV
debugging. It can be used to upload or download files in a
- pinch, and also to examine properties, copy, move, lock or
+ pinch, and also to examine properties, and to copy, move, lock
or
unlock files:</para>
<screen>
@@ -620,7 +624,7 @@
<para>Some popular file explorer GUI programs support WebDAV
extensions which allow a user to browse a DAV share as if it
- was just another directory on the local computer, and allowing
+ was just another directory on the local computer, and to perform
basic tree editing operations on the items in that share. For
example, Windows Explorer is able to browse a WebDAV server as
a <quote>network place</quote>. Users can drag files to and
@@ -651,7 +655,12 @@
a new implementation of Web Folders, known as the <quote>WebDAV
mini-redirector</quote>. The new implementation is a
filesystem-level client, allowing WebDAV shares to be mounted
- as drive letters. Unfortunately, this implementation is
+ as drive letters.
+ <!-- may I just interject: _this_ is why Free Software is
+ great: a technical writer can speak the unvarnished truth
+ when needed. If this book were for a commercial product,
+ Ben wouldn't have been allowed to say that, and users would
suffer. -->
+ Unfortunately, this implementation is
incredibly buggy. The client usually tries to convert http
URLs (<literal>http://host/repos</literal>) into UNC share
notation (<literal>\\host\repos</literal>); it also often
@@ -709,7 +718,9 @@
version in January 2005, available at
<ulink url="http://support.microsoft.com/?kbid=892211"/>.
In particular, this release is known to fix a bug whereby
- browsing a DAV share shows an unexpected infinite
+ browsing a DAV share <!-- woudln't it be simpler to say just
+ "hangs" or "crashes", as the case may be? -->
+ shows an unexpected infinite
recursion.</para>
</sect3>
@@ -752,7 +763,7 @@
filesystem module, typically within the operating system's
kernel. This means that the DAV share is mounted like any
other network filesystem, similar to mounting an NFS share on
- Unix, or attaching an SMB share as drive-letter in Windows.
+ Unix, or attaching an SMB share as a drive letter in Windows.
As a result, this sort of client provides completely
transparent read/write WebDAV access to all programs.
Applications aren't even aware that WebDAV requests are
Index: appd-third-party-tools.xml
===================================================================
--- appd-third-party-tools.xml (revision 2737)
+++ appd-third-party-tools.xml (working copy)
@@ -7,7 +7,7 @@
linkend="svn.developer.usingapi.otherlangs"/>) make it a likely
candidate for use as an extension or backend to other pieces of
software. For a listing of many third-party tools that are using
- Subversion functionality under-the-hood, check out the Links page on
the
+ Subversion functionality under the hood, check out the Links page on
the
Subversion website (<ulink
url="http://subversion.tigris.org/project_links.html"/>).</para>
}}}
--
Ticket URL: <http://svnbook.red-bean.com/trac/ticket/67>
SvnBook <http://svnbook.red-bean.com/>
More information about the svnbook-dev
mailing list