[2/2] manual/setjmp.texi: Improve clarity of Sys V context doc

Message ID 1393829881-22691-2-git-send-email-will.newton@linaro.org
State Accepted
Commit 6f918f367a40b2fceaaed6f9ae6aea18b52b2205
Headers show

Commit Message

Will Newton March 3, 2014, 6:58 a.m.
ChangeLog:

2014-03-03  Will Newton  <will.newton@linaro.org>

	* manual/setjmp.texi (System V contexts): Improve
	clarity and grammar of documentation.
---
 manual/setjmp.texi | 21 ++++++++++-----------
 1 file changed, 10 insertions(+), 11 deletions(-)

Comments

Ondřej Bílka March 3, 2014, 10:56 a.m. | #1
On Mon, Mar 03, 2014 at 02:58:01PM +0800, Will Newton wrote:
> ChangeLog:
> 
> 2014-03-03  Will Newton  <will.newton@linaro.org>
> 
> 	* manual/setjmp.texi (System V contexts): Improve
> 	clarity and grammar of documentation.
> ---
>  manual/setjmp.texi | 21 ++++++++++-----------
>  1 file changed, 10 insertions(+), 11 deletions(-)
> 
> diff --git a/manual/setjmp.texi b/manual/setjmp.texi
> index 3bef1b1..9446abc 100644
> --- a/manual/setjmp.texi
> +++ b/manual/setjmp.texi
> @@ -307,17 +307,16 @@ The function returns @code{0} if successful.  Otherwise it returns
>  @end deftypefun
>  
>  The @code{getcontext} function is similar to @code{setjmp} but it does
> -not provide an indication of whether the function returns for the first
> -time or whether the initialized context was used and the execution is
> -resumed at just that point.  If this is necessary the user has to
> -determine this herself.  This must be done carefully since the context
> -contains registers which might contain register variables.  This is a
> -good situation to define variables with @code{volatile}.
> +not provide an indication of whether @code{getcontext} is returning for
> +the first time or whether an initialized context has just been restored.
> +If this is necessary the user has to determine this herself.  This must

Written to promote role of woman it IT. Otherwise ok.
Michael Kerrisk (man-pages) March 5, 2014, 11:47 a.m. | #2
Ondrej,

Surprisingly, no-one called this...

On 03/03/2014 11:56 AM, Ondřej Bílka wrote:
> On Mon, Mar 03, 2014 at 02:58:01PM +0800, Will Newton wrote:
>> ChangeLog:
>>
>> 2014-03-03  Will Newton  <will.newton@linaro.org>
>>
>> 	* manual/setjmp.texi (System V contexts): Improve
>> 	clarity and grammar of documentation.
>> ---
>>  manual/setjmp.texi | 21 ++++++++++-----------
>>  1 file changed, 10 insertions(+), 11 deletions(-)
>>
>> diff --git a/manual/setjmp.texi b/manual/setjmp.texi
>> index 3bef1b1..9446abc 100644
>> --- a/manual/setjmp.texi
>> +++ b/manual/setjmp.texi
>> @@ -307,17 +307,16 @@ The function returns @code{0} if successful.  Otherwise it returns
>>  @end deftypefun
[...]
>> +If this is necessary the user has to determine this herself.  This must
> 
> Written to promote role of woman it IT. Otherwise ok.

Perhaps this was meant as a joke, but, even in that case, the remark is part of
the very problem that Will's text tries to address. For centuries, women have
been written out of the story. Witness the pervasive effect of that, when
even an intelligent person in a small way (wittingly or unwittingly) diminishes 
attempts to write themback into the story. As far as I can see, GNU projects
try to be more inclusive than that; remarks such as the above are not helpful
toward that goal.

Cheers,

Michael
Ondřej Bílka March 5, 2014, 2:20 p.m. | #3
On Wed, Mar 05, 2014 at 12:47:47PM +0100, Michael wrote:
> Ondrej,
> 
> Surprisingly, no-one called this...
> 
> On 03/03/2014 11:56 AM, Ondřej Bílka wrote:
> > On Mon, Mar 03, 2014 at 02:58:01PM +0800, Will Newton wrote:
> >> ChangeLog:
> >>
> >> 2014-03-03  Will Newton  <will.newton@linaro.org>
> >>
> >> 	* manual/setjmp.texi (System V contexts): Improve
> >> 	clarity and grammar of documentation.
> >> ---
> >>  manual/setjmp.texi | 21 ++++++++++-----------
> >>  1 file changed, 10 insertions(+), 11 deletions(-)
> >>
> >> diff --git a/manual/setjmp.texi b/manual/setjmp.texi
> >> index 3bef1b1..9446abc 100644
> >> --- a/manual/setjmp.texi
> >> +++ b/manual/setjmp.texi
> >> @@ -307,17 +307,16 @@ The function returns @code{0} if successful.  Otherwise it returns
> >>  @end deftypefun
> [...]
> >> +If this is necessary the user has to determine this herself.  This must
> > 
> > Written to promote role of woman it IT. Otherwise ok.
> 
> Perhaps this was meant as a joke, but, even in that case, the remark is part of
> the very problem that Will's text tries to address. For centuries, women have
> been written out of the story. Witness the pervasive effect of that, when
> even an intelligent person in a small way (wittingly or unwittingly) diminishes 
> attempts to write themback into the story. As far as I can see, GNU projects
> try to be more inclusive than that; remarks such as the above are not helpful
> toward that goal.
> 
It was originally there. I just pointed that out.

Patch

diff --git a/manual/setjmp.texi b/manual/setjmp.texi
index 3bef1b1..9446abc 100644
--- a/manual/setjmp.texi
+++ b/manual/setjmp.texi
@@ -307,17 +307,16 @@  The function returns @code{0} if successful.  Otherwise it returns
 @end deftypefun
 
 The @code{getcontext} function is similar to @code{setjmp} but it does
-not provide an indication of whether the function returns for the first
-time or whether the initialized context was used and the execution is
-resumed at just that point.  If this is necessary the user has to
-determine this herself.  This must be done carefully since the context
-contains registers which might contain register variables.  This is a
-good situation to define variables with @code{volatile}.
+not provide an indication of whether @code{getcontext} is returning for
+the first time or whether an initialized context has just been restored.
+If this is necessary the user has to determine this herself.  This must
+be done carefully since the context contains registers which might contain
+register variables.  This is a good situation to define variables with
+@code{volatile}.
 
 Once the context variable is initialized it can be used as is or it can
-be modified.  The latter is normally done to implement co-routines or
-similar constructs.  The @code{makecontext} function has to be
-used to do that.
+be modified using the @code{makecontext} function.  The latter is normally
+done when implementing co-routines or similar constructs.
 
 @comment ucontext.h
 @comment SVID
@@ -325,7 +324,7 @@  used to do that.
 @safety{@prelim{}@mtsafe{@mtsrace{:ucp}}@assafe{}@acsafe{}}
 @c Linux-only implementations mostly in assembly, nothing unsafe.
 
-The @var{ucp} parameter passed to the @code{makecontext} shall be
+The @var{ucp} parameter passed to @code{makecontext} shall be
 initialized by a call to @code{getcontext}.  The context will be
 modified in a way such that if the context is resumed it will start by
 calling the function @code{func} which gets @var{argc} integer arguments
@@ -436,7 +435,7 @@  function fails it returns @code{-1} and sets @var{errno} accordingly.
 
 The easiest way to use the context handling functions is as a
 replacement for @code{setjmp} and @code{longjmp}.  The context contains
-on most platforms more information which might lead to less surprises
+on most platforms more information which may lead to fewer surprises
 but this also means using these functions is more expensive (besides
 being less portable).