Re: CVS commit: src

[yamt%mwd.biglobe.ne.jp@localhost (YAMAMOTO Takashi)]

> On Fri, Jan 29, 2010 at 12:24:56AM +0000, YAMAMOTO Takashi wrote:
>  > > > let's stop being too generic and go back to the change in question.
>  > > > do you think this man page is an appropriate place for these functions?
>  > > 
>  > > Given that they exist in several MD implementations and (I think) are
>  > > more or less the same in at least some of those, yes, provided they're
>  > > documented as a piece of internals.
>  > 
>  > "some MD implementations might have this for their internal use"?
>  > it sounds useless and confusing to me.
> 
> It has two legitimate audiences: (1) people bringing up new ports, who
> may not already know the ins and outs of making MD spl handling go,
> and who would be better off reading and understanding documentation
> than blindly cutting and pasting existing logic; and also (2) anyone
> looking to unify common MD code and make it MI.

i don't think it's what this man page is for.

having such documentation somewhere might be helpful, sure.  i even
suggested to put it as comments along the code.  however please don't
put them in this man page.

> 
> I don't see that this is a bad thing, and I don't see that these
> things change often enough to make updating such docs a maintenance
> problem. So I don't see what the downside is.

it confuses the main audiences of the man page.  (ones who want to learn
the interfaces)

> 
>  > > Of course, we could get rid of them and move to MI spl functions :-)
>  > > (see tech-kern, ad@ just found the thread and thereby reminded me of it)
>  > 
>  > we are discussing if we want to describe MD internal details in the
>  > man page of MI spl interfaces.

i don't understand what you meant by "MI spl functions".
what this man page describes is what can be used by MI code.
(except splraise and spllower, of course)

> 
> However, if you have an opinion on that thread it'd be good to hear
> it... there, of course :-)

i'm not sure which thread are you talking about.

YAMAMOTO Takashi

> 
> -- 
> David A. Holland
> dholland%netbsd.org@localhost