Documentation cleanup issues

[Russ Allbery]

Jeffrey M Vinocur <jeff at litech.org> writes:
> On Mon, 2 Dec 2002, Russ Allbery wrote:

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

> I did my best to update everything I saw to your desired syntax (which
> took me a long time to pick up on, but made a lot of sense as soon as I
> did), although I'm sure I missed some.

I'll try to add something about that to HACKING.

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

> Quick glance at line 222ish of storage/ov.c indicates that's correct,
> but is the point of ovgrouppat that we don't even try to store an
> overview entry for non-matching articles?

Right.

So the idea is that not storing overview information for a group that you
need overview information to expire is nonsensical, and we can just throw
an error and give up.  (The main use of ovgrouppat, IMO, is doing stuff
like storing and propagating cancel messages but not letting anyone read
them and not bothering to generate overview information for them, since
you're putting them all in a CNFS buffer anyway.)

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

> Huh, you're right.  Do you think the docs are clear on this point?

No, not really.

I wonder how hard it would be to fix this to do what ! and @ do everywhere
else in INN rather than documenting the current behavior, since it's very
counterintuitive right now, I think.

> Does just running perldoc invoke stuff from podlators?

It runs the pod2man that came with that perldoc, usually.  I think it
hard-codes the path rather than searching your PATH.

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

> So what do you think about the instance in "Reporting Bugs" of README?

It could definitely stand some rewording.  I'm not sure how best to phrase
inn at isc.org.  I'd really rather people not use it at all, actually, except
for things where they need to contact the maintainers directly rather than
a mailing list (some sort of huge security issue, for example).

> Ok, just wanted to be sure what the story was.  It's a shame that
> there's no good way to do this.  Also that you can't nest I<> inside of
> C<> and stuff.

Hm, you should be able to nest I<> inside of C<>, although it won't have
much effect on many translators.  Should work in HTML, though....

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

> Dunno :-/

Yup, we did:

revision 1.24
date: 2000/03/20 22:32:58;  author: kondou;  state: Exp;  lines: +9 -2
branches:  1.24.2;
frontends/rnews.c:
        - fixed spooling failure if pathtmp and pathincoming are not the same
          partition

So the second-to-last sentence of this:

=item I<pathtmp>

Where INN puts temporary files.  For security reasons, this is not the
same as the system temporary files directory (INN creates a lot of
temporary files with predictable names and does not go to particularly
great lengths to protect against symlink attacks and the like; this is
safe provided that normal users can't write into its temporary
directory).  It must be on the same partition as I<pathincoming> for
rnews(1) to work correctly.  The default value is set at configure time
and defaults to I<pathnews>/tmp.

should go away.  Doing this now.

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