Documentation cleanup issues

Jeffrey M. Vinocur jeff at litech.org
Tue Dec 3 18:36:05 UTC 2002


On Mon, 2 Dec 2002, Russ Allbery wrote:

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

Any thoughts on a good way to do this?  It's a shame that we do the 
manpage installation with an explicit loop rather than by dependencies and 
general rules (I assume it's because non-GNU make has no way to prepend 
the installation path to a whole list of filenames?).


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

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.


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

Oh oh oh, the multiple auth: lines in one auth group (that was a 
regretable naming collision) are just shorthand that get expanded 
internally to a sequence of mostly-duplicate auth groups, aren't they.  
I'd forgotten about that.


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

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?


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


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

Does just running perldoc invoke stuff from podlators?  I didn't attempt 
the conversion properly, just ran perldoc itself on the file.  (You're 
right though, it doesn't do that on a recent system.)


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


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

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.

Will commit a fix as soon as the CVS server gets fixed.


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

Dunno :-/


-- 
Jeffrey M. Vinocur
jeff at litech.org



More information about the inn-workers mailing list