Documentation cleanup issues

[Jeffrey M. Vinocur]

Ok, I'm currently committing a bunch of changes to the documentation.  
They're mostly straightforward typo and rewording things, but in some
places I think the documentation was in error (based on my experience and
looking at the source), which I corrected.  If anybody wants to look over
it, the entire (rather large) diff is up at least temporarily at
http://www.litech.org/~jeff/inn-diffs/documentation.

I also tried to standardize a bunch of stuff which was inconsistent; for 
example I always use a comma before "and" in lists like "x, y, and z".  
People hold varying views on this sort of thing, but I figured standard 
was better than not.

I came across some issues that I couldn't resolve myself.  Some of this
could go in TODO, but hopefully a lot of them can be resolved trivially
and then we'll put the rest in TODO.  (I also made very sparse notes and
don't entirely remember what I meant.  *sigh*)


- When we have multiple manpages rolled into one (I'm thinking send-uucp
  and friends here), do we want to install them as symlinks so `man foo`
  always works even if foo is incorporated into some other manpage?

- There are some references to tally.unwanted(8), but no such manpage
  exists.  We need to either revise newslog.5 and tally.control.8, or 
  provide the missing manpage.

- Also referenced but nonexistent are newsrequeue and nntplink.

- It seems like we try to use foo(5) syntax to refer to the documentation
  for a file, and F<foo> syntax to refer to the actual file itself.  Is
  this perception correct?  If so, we should try to be more consistent
  about that usage.

- The URL for GUP in readme.pod is out of date, I think.  I saw a new one
  recently but forget where.

- I forget myself, but in readers.conf, are *all* auth groups containing
  an auth: line used, or just all the auth lines in the last matching
  auth group?  The documentation is contradictory on this.

- In "ovgrouppat" of inn.conf, "storing overview data will fail" is not
  sensical in this context, but I'd like to let somebody who wouldn't
  be guessing correct it.

- In the final "complicated" example of readers.conf, should the pattern
  "*,!example.*" be "*, at example.*" instead?  I think it probably should.

- For "ignorenewsgroups" of inn.conf, we no longer honor control messages
  in Subject headers, right?  (That entire paragraph could use some 
  clearing up, actually.)

- If I run `perldoc hook-perl.pod`, the reference to IPC::Open3::open3()
  gets rendered as "IPC:\fIs0:Open3::open3()" which I'm guessing must
  be not-our-fault.  Russ, I figured you might know.

- We refer to inn at isc.org in a few places, does that address actually
  go somewhere useful?

- There's still a lot of use of "wildmat" (instead of "uwildmat") in
  casual text; do we mean to change completely or only in direct
  references to the library routine?

- On my system, both the pod and the manpage for libinnhist are missing
  newlines in the summary at the top (between the struct fields, and
  between the #defines).  As a result, it looks really nasty.  I'd
  rather sacrifice the boldface and just use verbatim if that's what
  we have to do.

- I thought there was something odd going on with actsyncd passing -o,
  but I forget what.  Anyway, actsync and actsyncd really need to be
  separated.

- I wanted to ask if we assume $pathtmp is on the same partition as
  $pathincoming (presumably I saw some code that used this fact,
  although If orget what); if so we should document that somewhere.





-- 
Jeffrey M. Vinocur
jeff at litech.org