Re: audio(9) manual page
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 - 1.23 +++ audio.9 23 Jun 2014 19:42:42 - @@ -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
Re: audio(9) manual page
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 - 1.23 +++ audio.9 23 Jun 2014 19:42:42 - @@ -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
Re: audio(9) manual page
* Jason McIntyre j...@kerhand.co.uk [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.
audio(9) manual page
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 - 1.23 +++ audio.9 23 Jun 2014 19:42:42 - @@ -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
