From 13bacd44c743d7eedfd014f759255ab144d7e8e2 Mon Sep 17 00:00:00 2001
From: Christos Zoulas <christos@zoulas.com>
Date: Tue, 18 Apr 2006 17:26:54 +0000
Subject: [PATCH] Document the new 2 argument netgrp and netgrpd.

---
 doc/am-utils.texi | 40 +++++++++++++++++++++++++++++++---------
 1 file changed, 31 insertions(+), 9 deletions(-)

diff --git a/doc/am-utils.texi b/doc/am-utils.texi
index 7cb31c8..9bec66e 100644
--- a/doc/am-utils.texi
+++ b/doc/am-utils.texi
@@ -1792,9 +1792,11 @@ Always evaluates to false.  @i{ARG} is ignored.
 @cindex Mount selector; netgrp
 @cindex Selector; netgrp
 
-If the current host as determined by the value of @code{$@{host@}}
-(e.g., short host name) is a member of the netgroup @i{ARG}, this
-selector evaluates to true.  Otherwise it evaluates to false.
+The argument @i{ARG} of this selector is a netgroup name followed optionally
+by a comma and a host name. If the host name is not specified, it
+defaults to @code{$@{host@}}. If the host name (short name) is a member
+of the netgroup, this selector evaluates to true. Otherwise it evaluates
+to false.
 
 For example, suppose you have a netgroup @samp{ppp-hosts}, and for
 reasons of performance, these have a local @file{/home} partition, while
@@ -1806,6 +1808,25 @@ home/*  netgrp(ppp-hosts);type:=link;fs:=/local/$@{key@} \
         !netgrp(ppp-hosts);type:=nfs;rhost:=serv1;rfs:=/remote/$@{key@}
 @end example
 
+A more complex example that takes advantage of the two argument
+netgrp mount selector is given in the following scenario. Suppose
+one wants to mount the local scratch space from a each host under
+@file{scratch/<hostname>} and some hosts have their scratch space in a
+different path than others. Hosts in the netgroup @samp{apple-hosts}
+have their scratch space in the @file{/apple} path, where hosts
+in the netgroup @samp{cherry-hosts} have their scratch space in the
+@file{/cherry} path. For hosts that are neither in the @samp{apple-hosts}
+or @samp{cherry-hosts} netgroups we want to make a symlink pointing to
+nowhere but provide a descriptive error message in the link destination:
+
+@example
+scratch/*	netgrp(apple-hosts,$@{/key@});type:=nfs;rhost:=$@{/key@};\
+		    rfs:="/apple" \
+		netgrp(cherry-hosts,$@{/key@});type:=nfs;rhost:=$@{/key@};\
+		    rfs:="/cherry" \
+		type:=link;rfs:="no local partition for $@{/key@}"
+@end example
+
 @c ----------------------------------------------------------------
 @node netgrpd Selector Function, in_network Selector Function, netgrp Selector Function, Selectors
 @comment  node-name,  next,  previous,  up
@@ -1816,14 +1837,15 @@ home/*  netgrp(ppp-hosts);type:=link;fs:=/local/$@{key@} \
 @cindex Mount selector; netgrpd
 @cindex Selector; netgrpd
 
-If the current host as determined by the value of @code{$@{hostd@}} is a
-member of the netgroup @i{ARG}, this selector evaluates to true.
-Otherwise it evaluates to false.
+The argument @i{ARG} of this selector is a netgroup name followed optionally
+by a comma and a host name. If the host name is not specified, it
+defaults to @code{$@{hostd@}}. If the host name (fully-qualified name)
+is a member of the netgroup, this selector evaluates to true. Otherwise
+it evaluates to false.
 
 The @samp{netgrpd} function uses fully-qualified host names
-(@code{$@{hostd@}}) to match netgroup names, while the @samp{netgrp}
-function (@pxref{netgrp Selector Function}) uses short host names
-(@code{$@{host@}}).
+to match netgroup names, while the @samp{netgrp}
+function (@pxref{netgrp Selector Function}) uses short host names.
 
 @c ----------------------------------------------------------------
 @node in_network Selector Function, true Selector Function, netgrpd Selector Function, Selectors
-- 
2.34.1