[PATCH] manual: Document getcontext uc_stack value on Linux [BZ #759]

[Adhemerval Zanella]

On 08/08/2017 15:30, Zack Weinberg wrote:
> On Tue, Aug 8, 2017 at 2:27 PM, Adhemerval Zanella
> <adhemerval.zanella@linaro.org> wrote:
>> On 11/07/2017 18:43, Adhemerval Zanella wrote:
>>> On 11/07/2017 17:25, Zack Weinberg wrote:
>>>> On Tue, Jul 11, 2017 at 2:28 PM, Adhemerval Zanella
>>>> <adhemerval.zanella@linaro.org> wrote:
>>>>>
>>>>> Right, I do not have a preference here about the wording but I do think
>>>>> we should at least document Linux behaviour (which originated the bug
>>>>> report). What about:
>>>>>
>>>>> @strong{Compatibility Note:} Depending on the operating system,
>>>>> information about the current context's stack may be in the
>>>>> @code{uc_stack} field of @var{ucp}, or it may instead instead be in
>>>>> architecture-specific subfields of the @code{uc_mcontext} field.
>>>>> On Linux the current context's stack returned on @code{uc_stack}
>>>>> is empty by default.
>>>>
>>>> I actually think we _shouldn't_ document Linux's behavior in this
>>>> case.  Without a great deal more verbiage about how to write code that
>>>> portably examines the result of getcontext, it's better to just say
>>>> "this information could be in two different places" than "this
>>>> information could be in two different places, and on system X it's in
>>>> this one."  Good code has to be prepared to look in both places.  That
>>>> is the best _short_ advice.
>>>
>>> Taking in consideration getcontext is deprecated and this is specific
>>> implementation detail I think it is still worth to mention Linux behaviour
>>> without the need of extending how to proper use this API (which should
>>> not be used in newer programs anyway and in my experience the program
>>> that still rely on such *context, libgo for instance, already have a
>>> lot of hacks for different systems). The manual imho should mainly
>>> document the current system supported and its idiosyncrasies.
>>>
>>
>> Zack do you still think we should not document Linux behaviour? I
>> understand your point that for document getcontext in a portable
>> way it would require more explanation, but I think the goal here
>> is just document this specific Linux difference for this deprecated
>> symbol.
> 
> I would still prefer to just say
> 
>>>>> @strong{Compatibility Note:} Depending on the operating system,
>>>>> information about the current context's stack may be in the
>>>>> @code{uc_stack} field of @var{ucp}, or it may instead be in
>>>>> architecture-specific subfields of the @code{uc_mcontext} field.
> 
> and no more.
> 
> zw
> 

Alright, I will use your suggestion then.