Documentation cleanup issues

[Russ Allbery]

Jeffrey M Vinocur <jeff at litech.org> writes:

> - 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?

Yes, please.

> - 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.

Since there's no tally.unwanted any more (I seem to recall that innreport
now does this), we should remove references to the man page.

> - Also referenced but nonexistent are newsrequeue and nntplink.

These have both been retired and the man pages for them should go away.

> - 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?

Yes, that's what I'd been trying to do, but I'd not gone back and done any
of the other files beyond the ones I'd converted to POD.

Similarly, I was using B<program> to refer to the program and program(8)
or program(1) to refer to its man page, but that too isn't done
consistently, and there are even POD pages that just use program(8)
everywhere.

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

I think Debian reorganized their package systems; I'd have to poke around
to figure out where things went.

> - 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.

All auth groups that match the incoming hostname are collected, and then
they're walked in reverse order, and the first one that returns a user
identity is used.  This means that multiple auth: lines may be tried until
one of them works.

> - 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.

I believe it means that INN blows chunks and throttles itself if you do
that (have groups that don't have self-expire functionality not listed in
ovgrouppat and turn on groupbaseexpiry).  But I don't remember for sure;
I'd have to check the code.

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

I don't believe @ makes sense in this context (or to be more precise, if I
remember correctly, ! acts like @ would when someone tries to crosspost a
message).

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

Right.

> - 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.

That sounds like a pretty old version of pod2man (Pod::Man, actually).  I
think I fixed that a while back, and it doesn't do that for me.

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

Kind of.  It goes to Katsuhiro and I personally, but it's not archived and
isn't the best place to ask questions.

> - 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?

Only direct references, I think.  The NNTP standard still talks about
wildmats.

> - 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.

Agreed.  POD doesn't deal with this currently; you have to use verbatim if
you're documenting things that you don't want to have word-wrap, and you
can't use bold inside verbatim.

> - 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.

Agreed.

> - 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.

It's mentioned in the inn.conf man page under pathtmp because rnews used
to require it, but I think we've actually fixed that in rnews, haven't we?

-- 
Russ Allbery (rra at stanford.edu)             <http://www.eyrie.org/~eagle/>

    Please send questions to the list rather than mailing me directly.
     <http://www.eyrie.org/~eagle/faqs/questions.html> explains why.