Re: Quick fix for syscall man page

[walter harms <wharms@bfs.de>]

Am 10.09.2019 10:26, schrieb Michael Kerrisk (man-pages):
> Hello Adam,
> 
> Thanks for jumping in.
> On 9/9/19 8:27 PM, Adam Borowski wrote:
>> On Mon, Sep 09, 2019 at 11:08:34AM +0200, walter harms wrote:
>>> Am 09.09.2019 10:52, schrieb Michael Kerrisk (man-pages):
>>>> [Adding Adam Borowski in CC, since he wrote the riscv text back at the
>>>> start of 2018, andand he may have a comment.]
>>
>> I don't know RISCV; I needed to learn how to issue syscalls to port
>> something -- so I've searched for relevant documentation, tested that it
>> indeed works, then submitted that line to make the man page complete.
>>
>>>> On Thu, 5 Sep 2019 at 18:35, Florin Blanaru <florin.blanaru96@gmail.com> wrote:
>>>>> http://man7.org/linux/man-pages/man2/syscall.2.html
>>>>>
>>>>> In the first table, for the riscv Arch/ABI, the instruction should be
>>>>> ecall instead of scall.
>>>>>
>>>>> According the official manual, the instruction has been renamed.
>>>>> https://content.riscv.org/wp-content/uploads/2017/05/riscv-spec-v2.2.pdf
>>
>> What matters for us, and the vast majority of programmers, is that the
>> rename predates merging into official releases of binutils.  Thus, there is
>> no reason to ever use the old name in actual code.
>>
>>> Maybe it would be helpful to add a "footnote" that this is a rename only.
>>> Otherwise people may get confused.
>>
>> I wonder, perhaps just a commit message would be enough?  The alias is
>> historic only; new documentation is supposed to use the new name.  Man pages
>> contain a lot of data that has been obsolete for decades -- it might be good
>> to avoid stuff that became obsolete before the official release.
>>
>> But it's up to you -- you know better what's your policy about historical
>> information.
> 
> On reflection, I agree. I'll trim this back to a note in the commit
> message only. (Nevertheless, thanks, Walter.)
> 

Just my view on this:

most people that work on this level may know about that. NTL they also
tend to stick what worked last time. IMHO is the note important since
this is a naming only, you look at the man page not at the archive when
you are in doubt.

Something like: "In 2017 scall war renamed as ecall" is a harmless note.

note; i am not a risc programmer. it is just a general concern.

re,
 wh

> Cheers,
> 
> Michael
> 
>>>> --- a/man2/syscall.2
>>>> +++ b/man2/syscall.2
>>>> @@ -196,7 +196,7 @@ mips        syscall v0      v0      v1      a3      1, 6
>>>> -riscv  scall   a7      a0      a1      -
>>>> +riscv  ecall   a7      a0      a1      -
>>
>>
>> Meow!
>>
> 
>