Re: Quick fix for syscall man page

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

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.)

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!
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/