doc: add linked cells description to man pages

The man pages previously described linking DCE cells to AFS cells.
OpenAFS and YFS also allow linking between two AFS cells. Update the
description of linked cells in CellServDB(5), aklog(1), and
fs_newcell(1) to refer to AFS instead of DCE.

Add a linked cell example to the CellServDB man page with an
explanation.

Change-Id: Ic9b1c643861b7307c09fcc5a1775f4abf4cb4155
Reviewed-on: http://gerrit.openafs.org/10342
Tested-by: BuildBot <buildbot@rampaginggeek.com>
Reviewed-by: Jeffrey Altman <jaltman@your-file-system.com>

doc/man-pages/README

@@ -235,10 +235,6 @@ Known Problems
   don't just report the deficiency again, but any contributions towards
   fixing it are greatly appreciated.
 
-   * Linked cells are currently documented in fs newcell as being only
-     for DCE, which is not correct.  That documentation, aklog, and the
-     CellServDB documentation needs to be updated.
-
    * We need a way to add links to other man pages (kinit most notably)
      without creating dangling links in the HTML output.  This probably
      means that the HTML conversion script needs to generate at startup

doc/man-pages/pod1/aklog.pod

@@ -106,7 +106,7 @@ normally won't be necessary.
 
 =item B<-linked>
 
-If the AFS cell is linked to a DCE cell, get tokens for both.
+If the AFS cell is linked to another AFS cell, get tokens for both.
 
 =item B<-noauth>
 

doc/man-pages/pod1/fs_newcell.pod

@@ -38,10 +38,10 @@ cell's entry from the kernel-resident list by providing no values for the
 B<-server> argument). To make a cell inaccessible, remove its entry from
 the F<CellServDB> file and reboot the machine.
 
-If the B<-name> argument names a DCE cell, then the B<-servers> argument
-names DFS Fileset Location (FL) Server machines. The B<-linkedcell>
-argument specifies the name of the AFS cell to link to a DCE cell for the
-purpose of DFS fileset location.
+The B<-linkedcell> argument specifies the name of the AFS cell to link to
+another AFS cell for the purpose of retrying volume lookups. When two
+cells are linked, a volume lookup in one cell that fails is retried in the
+linked cell.
 
 =head1 CAUTIONS
 
@@ -60,14 +60,13 @@ Specifies the fully-qualified cell name of the AFS or DCE cell.
 =item B<-servers> <I<primary servers>>+
 
 Specifies the fully-qualified hostnames of all AFS database server
-machines or DFS Fileset Location (FL) Server machines for the cell named
-by the B<-name> argument. If FL Server machines are specified, the local
-machine must be running the AFS/DFS Migration Toolkit Protocol Translator.
+machines for the cell named by the B<-name> argument.
 
 =item B<-linkedcell> <I<linked cell name>>
 
-Specifies the name of the AFS cell to link to a DCE cell for the purpose
-of DFS fileset location.
+Specifies the name of the AFS cell to link to another AFS cell for the
+purpose of retrying volume lookups. When two cells are linked, a volume
+lookup in one cell that fails is retried in the linked cell.
 
 =item B<-help>
 
@@ -120,10 +119,10 @@ machines C<db1.example.com> and C<db2.example.com>:
 
    % fs newcell -name example.com -servers db1.example.com db2.example.com
 
-The following example links the DCE cell C<dce.example.com> to the AFS cell
-C<example.com>. The AFS client contacts the Fileset Location (FL) servers
-C<db1.dce.example.com> and C<db2.dce.example.com> for fileset location
-information as it interprets a DFS pathname.
+The following example links the AFS cell C<dce.example.com> to the AFS cell
+C<example.com>. The AFS client contacts the Volume Location (VL) servers
+C<db1.dce.example.com> and C<db2.dce.example.com> for volume location
+information.
 
    % fs newcell -name dce.example.com \
        -servers db1.dce.example.com db2.dce.example.com \

doc/man-pages/pod5/CellServDB.pod

@@ -217,6 +217,23 @@ F<CellServDB> file and illustrates the required format.
    192.12.108.57        #testdb1.example.com
    192.12.108.55        #testdb2.example.com
 
+The following example shows entries for two linked cells in a client
+F<CellServDB> file. The a.example.com cell is linked to the b.example.com
+cell.
+
+   >b.example.com # B cell
+   192.12.108.57 # db1.b.example.com
+   >a.example.com b.example.com # A cell
+   192.12.105.2 # db1.a.example.com
+
+In such a setup, if a client is looking for a volume in cell a.example.com
+and that volume doesn't exist, the client will try to find that volume
+again in cell b.example.com. The order is important. You must list the
+cell being linked before the cell doing the linking.
+
+The Windows client supports linking in two directions. The UNIX client
+does not allow bidirectional linkage.
+
 =head1 SEE ALSO
 
 L<afsd(8)>,