audio(9) manual page

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

audio(9) manual page

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

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

Reply | Threaded
Open this post in threaded view
|

Re: audio(9) manual page

Alexandre Ratchov-2
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 .

> 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

Reply | Threaded
Open this post in threaded view
|

Re: audio(9) manual page

Jason McIntyre-2
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
>

Reply | Threaded
Open this post in threaded view
|

Re: audio(9) manual page

Alexander Polakov
* Jason McIntyre <[hidden email]> [140625 00:41]:

> On Tue, Jun 24, 2014 at 09:13:47AM +0200, Alexandre Ratchov wrote:
> > 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).

I agree, this one looks even better.