On Tue, Jun 24, 2014 at 09:13:47AM +0200, Alexandre Ratchov wrote:
> On Tue, Jun 24, 2014 at 03:58:41AM +0400, Alexander Polakov wrote:
> > So I have been trying to write a new audio driver (for Xonar DS if
> > anyone interested) and therefore reading audio(9).
> >
> > I was confused for a while by the use of "will" here. I think it's not
> > clear enough that these functions should be called by the driver code.
> >
> > I'm not a native speaker, so may be it's just my lack of familiarity with
> > english idioms. Sorry for the noise if that's the case.
> >
>
> I see what you mean. As the manual describes the interface between
> two layers we may need to be more precise about who calls who.
> Wouldn't the following be less ambigous?
>
> When the hardware is ready to accept more samples the driver shall
> call the
> .Fa intr
> function with the argument
> .Fa intrarg .
>
the use of "will" is perfectly fine here - it's basically a conditional
sentence structure.
"shall" sounds awful. it sounds formal, dated, and like a document
produced by posix. please don;t make this change.
what is simpler, i think, and easier for most folks to understand, is
using a present tense:
When the hardware is ready to accept more samples,
the driver calls the
.Fa intr
function with the argument
.Fa intrarg .
it's all a matter of taste, i suppose, but present tense structure does
seem to be easier to read for non-native speakers (in my experience).
jmc
> > Index: audio.9
> > ===================================================================
> > RCS file: /cvs/src/share/man/man9/audio.9,v
> > retrieving revision 1.23
> > diff -u -r1.23 audio.9
> > --- audio.9 21 Jan 2014 03:15:46 -0000 1.23
> > +++ audio.9 23 Jun 2014 19:42:42 -0000
> > @@ -284,7 +284,7 @@
> > has been initiated (normally with DMA).
> > When the hardware is ready to accept more samples the function
> > .Fa intr
> > -will be called with the argument
> > +shall be called with the argument
> > .Fa intrarg .
> > Calling
> > .Fa intr
> > @@ -302,7 +302,7 @@
> > has been initiated (normally with DMA).
> > When the hardware is ready to deliver more samples the function
> > .Fa intr
> > -will be called with the argument
> > +shall be called with the argument
> > .Fa intrarg .
> > Calling
> > .Fa intr
> > @@ -437,7 +437,7 @@
> > .Fa blksize
> > sized block, the function
> > .Fa intr
> > -will be called with the argument
> > +shall be called with the argument
> > .Fa intrarg
> > (typically from the audio hardware interrupt service routine).
> > Once started, the transfer may be stopped using
> > @@ -459,7 +459,7 @@
> > .Fa blksize
> > sized block, the function
> > .Fa intr
> > -will be called with the argument
> > +shall be called with the argument
> > .Fa intrarg
> > (typically from the audio hardware interrupt service routine).
> > Once started, the transfer may be stopped using
>
