Ticket # uu 1551524

[David A. De Graaf]

Paul Tomblin wrote:
> 
> Quoting David A. De Graaf (degraaf at rhsnet.com):
> > Paul Tomblin wrote:
> > > Quoting David A. De Graaf (degraaf at rhsnet.com):
> > > > ##  The word ``peer'' is required. <name> is a label for this peer. It is
> > > > ##  any string valid as a key. The body of a peer entry contains some number
> > > > ##  of key/value entries.
>              ^^^^^^^^^
> > > > 
> > > > Evidently, "some number" must be exactly one!
> > > 
> > Not in my wildest dreams did I imagine there was a "key" involved,
> 
> Really?  What's ambiguous about the bit I indicated above?
> 
> > The lesson, if any, is just that different people bring different
> > backgrounds to the interpretation, so a writer has to be really
> > careful in constructing instructions.
> 
> True.  Unfortunately in my experience programmers can't express themselves
> well enough to write well, and writers can't think well enough to understand
> the programs they are supposed to be documenting.
> 

Whoops!  This little discussion forced me to RTFM
and I must apologize for being obtuse because it says clearly:
   hostname:
      This  key  requires a string value. It is a list of
      hostnames separated by a comma. A hostname  is  the
      host's  FQDN,  or the dotted quad ip-address of the
      peer. If this key is not present in a  peer  block,
      the hostname defaults to the label of the peer.

This seems crystal clear.
Multiple hostnames can be given, but must be separated by exactly
one comma.
So I ran some experiments.
IT DOESN'T WORK!   Can a man page be WRONG???

Clearly, my original incoming.conf was wrong:
peer uunet {
      hostname: nntp-out1.uu.net
      hostname: nntp-out2.uu.net
    ...
      hostname: nntp-out15.uu.net
}

but this should work (but is declared a "syntax error"):
peer uunet {
      hostname: \
nntp-out1.uu.net,\
nntp-out2.uu.net,\
    ... 
nntp-out15.uu.net
}   

This is also declared a "syntax error":
peer uunet {
      hostname: nntp-out1.uu.net,nntp-out2.uu.net,...,nntp-out15.uu.net
}


The ONLY form that I've been able to get to work has exactly one
hostname per peer entry:

peer uunet1 {
  hostname:     nntp-out1.uu.net
}
peer uunet2 {
  hostname:     nntp-out2.uu.net
}
   ...


> If you can think of a better way to express the concept above, feel free to
> send it along to the inn-workers list.
> 
How about this:

##  Peer entries look like:
## 
##          peer <name> {
##               # body
##          }
## 
##  The word ``peer'' is required. <name> is a label for this peer. 
##  It is any string valid as a key.
##  The body contains key/value entries, including exactly one
##      hostname: <full_name>
##  plus other optional key/value entries specific to that host.


Unless I'm really off in left field, the man page for incoming.conf
is wrong and should also be fixed to, say:

   hostname:
      This key must be present in every peer entry. 
      It requires a string value which is
      a single host's FQDN, or its dotted quad ip-address.


And what do you suppose "Height keys are allowed:" means???
I guessed it was a typo: "Eight keys...";  but nine are listed.


-- 
	David A. De Graaf    DATIX, Inc.    Hilton Head Is., SC  
	degraaf at rhsnet.com       843-785-3136, -3156 (fax)