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