Skip to contentSkip to conversation

docs/zh_CN: Update arch/riscv/vm-layout.rst translation

PATCH In review Yukai Wu 3 participants 7 messages Aug 29 – Aug 30

Subsystems (3)
lore
Share & tools
lore

Yukai Wu

author
#0 lore raw

PATCH 1/1 docs/zh_CN: Update arch/riscv/vm-layout.rst translation

Update Documentation/arch/riscv/vm-layout.rst translation.

Update the translation through commit 954260ff5a46 ("Revert "RISC-V: mm: Document mmap changes"")

---
 .../zh_CN/arch/riscv/vm-layout.rst             | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)
Documentation/translations/zh_CN/arch/riscv/vm-layout.rst +9 -9
index 4b9f4dcf6c19..0d0ec8ea5d05 100644
@@ -15,7 +15,7 @@ RISC-V Linux上的虚拟内存布局
 :作者: Alexandre Ghiti <[email protected]>
 :日期: 12 February 2021
 
-这份文件描述了RISC-V Linux内核使用的虚拟内存布局。
+这份文件描述了 RISC-V Linux 内核使用的虚拟内存布局。
 
 32位 RISC-V Linux 内核
 ======================
@@ -28,9 +28,9 @@ TODO
 64位 RISC-V Linux 内核
 ======================
 
-RISC-V特权架构文档指出,64位地址 "必须使第63-48位值都等于第47位,否则将发生缺页异常。":这将虚
-拟地址空间分成两半,中间有一个非常大的洞,下半部分是用户空间所在的地方,上半部分是RISC-V Linux
-内核所在的地方。
+RISC-V 特权架构文档指出,64 位地址“必须使第 63-48 位值都等于第 47 位,否则将发生缺页异常。”:
+这将虚拟地址空间分成两半,中间有一个非常大的洞,下半部分是用户空间所在的地方,上半部分是 RISC-V
+Linux 内核所在的地方。
 
 RISC-V Linux Kernel SV39
 ------------------------
@@ -52,11 +52,11 @@ RISC-V Linux Kernel SV39
                                                               | 内核空间的虚拟内存,在所有进程之间共享:
   ____________________________________________________________|___________________________________________________________
                     |            |                  |         |
-   ffffffc6fee00000 | -228    GB | ffffffc6feffffff |    2 MB | fixmap
-   ffffffc6ff000000 | -228    GB | ffffffc6ffffffff |   16 MB | PCI io
-   ffffffc700000000 | -228    GB | ffffffc7ffffffff |    4 GB | vmemmap
-   ffffffc800000000 | -224    GB | ffffffd7ffffffff |   64 GB | vmalloc/ioremap space
-   ffffffd800000000 | -160    GB | fffffff6ffffffff |  124 GB | 直接映射所有物理内存
+   ffffffc4fea00000 | -236    GB | ffffffc4feffffff |    6 MB | fixmap
+   ffffffc4ff000000 | -236    GB | ffffffc4ffffffff |   16 MB | PCI io
+   ffffffc500000000 | -236    GB | ffffffc5ffffffff |    4 GB | vmemmap
+   ffffffc600000000 | -232    GB | ffffffd5ffffffff |   64 GB | vmalloc/ioremap space
+   ffffffd600000000 | -168    GB | fffffff5ffffffff |  128 GB | 直接映射所有物理内存
    fffffff700000000 |  -36    GB | fffffffeffffffff |   32 GB | kasan
   __________________|____________|__________________|_________|____________________________________________________________
                                                               |
Signature · 1 line
2.55.0
#1 lore raw

Hi, it's me again ;-)

Quoted 4 lines · Yukai Wu

Update Documentation/arch/riscv/vm-layout.rst translation.

Update the translation through commit 954260ff5a46 ("Revert "RISC-V: mm: Document mmap changes"")

Somehow I guess you didn't get the actual meaning behind this "Update xxx through commit...".

Correct me if I'm wrong. If you write this line in your commit message. Then it means if we apply this patch of yours. The Chinese documentation of this file should be already _completely_ synchronized.

However, the current translation of this file is missing this part:

RISC-V Linux Kernel SV57
------------------------

... which is not translated/synchronized in your patch.

Note that I'm not blaming on you for this. But I feel this is a point that a newcomer might find confusing, including me and Chen-Yu a couple of weeks ago, if did not read the script.

Our current how-to.rst only asks to write this line in the commit message but does not explain the results or the actual work behind it.

[...]
Update the translation through commit b080e52110ea ("docs: update self-protection __ro_after_init status") # 请执行 git log --oneline <您翻译的英文文档路径>,并替换上述内容

So when a newcomer comes and just does what this asks, without considering whether his/her/its translation is completely synchronized or not, our script would be kind of inaccurate. ?

Maybe we can add a description or a hint like:

If your current changes make the translation completely in line with the English version, then please add this line after your descriptions and before a blank line and your sign-off:

Update the translation through commit e83c5163316f (Initial revision of "git", the information manager from hell)

..then follows a template commit message

Any ideas?

(Should I cc the original authors of the script?)

Thanks.

author
#2 lore raw
Quoted 8 lines · China Standard Time Weijie Yuan

Hi, it's me again ;-)

Quoted 4 lines · Yukai Wu

Update Documentation/arch/riscv/vm-layout.rst translation.

Update the translation through commit 954260ff5a46 ("Revert "RISC-V: mm: Document mmap changes"")

Quoted 7 lines

Somehow I guess you didn't get the actual meaning behind this "Update xxx through commit...".

Correct me if I'm wrong. If you write this line in your commit message. Then it means if we apply this patch of yours. The Chinese documentation of this file should be already _completely_ synchronized.

I agree. My fault again.

Quoted 8 lines

However, the current translation of this file is missing this part:

RISC-V Linux Kernel SV57
------------------------

... which is not translated/synchronized in your patch.

Didn't see that because I just used the tools/docs/checktransupdate.py script, which cannot see the commits before ed843ae947f8 ("docs: move riscv under arch"). That commit just moved the Chinese translation but was treated as an update by the script. And I only looked at the commits reported by the script.

Quoted 18 lines

Note that I'm not blaming on you for this. But I feel this is a point that a newcomer might find confusing, including me and Chen-Yu a couple of weeks ago, if did not read the script.

Our current how-to.rst only asks to write this line in the commit message but does not explain the results or the actual work behind it.

[...]
Update the translation through commit b080e52110ea ("docs: update self-protection __ro_after_init status") # 请执行 git log --oneline <您翻译的英文文档路径>,并替换上述内容

So when a newcomer comes and just does what this asks, without considering whether his/her/its translation is completely synchronized or not, our script would be kind of inaccurate. ?

Maybe we can add a description or a hint like:

Quoted 8 lines

If your current changes make the translation completely in line with the English version, then please add this line after your descriptions and before a blank line and your sign-off:

Update the translation through commit e83c5163316f (Initial revision of "git", the information manager from hell)

..then follows a template commit message

Allowing partial updates to the translation?

Quoted 5 lines

Any ideas?

(Should I cc the original authors of the script?)

CC the authors of the checktransupdate.py script?

Quoted 2 lines

Thanks.

Best,
Yukai Wu

#3 lore raw
Quoted 13 lines · Yukai Wu
Quoted 11 lines · China Standard Time Weijie Yuan

Hi, it's me again ;-)

Quoted 4 lines · Yukai Wu

Update Documentation/arch/riscv/vm-layout.rst translation.

Update the translation through commit 954260ff5a46 ("Revert "RISC-V: mm: Document mmap changes"")

Somehow I guess you didn't get the actual meaning behind this "Update xxx through commit...".

Quoted 6 lines
Quoted 4 lines

Correct me if I'm wrong. If you write this line in your commit message. Then it means if we apply this patch of yours. The Chinese documentation of this file should be already _completely_ synchronized.

I agree. My fault again.

No worries at all.

Quoted 6 lines
Quoted 6 lines

However, the current translation of this file is missing this part:

RISC-V Linux Kernel SV57
------------------------

Quoted 8 lines
Quoted 3 lines

... which is not translated/synchronized in your patch.

Didn't see that because I just used the tools/docs/checktransupdate.py script, which cannot see the commits before ed843ae947f8 ("docs: move riscv under arch"). That commit just moved the Chinese translation but was treated as an update by the script. And I only looked at the commits reported by the script.

OK, I noticed that this file was moved/renamed.

$ tools/docs/checktransupdate.py Documentation/translations/zh_CN/arch/riscv/vm-layout.rst
[1788062042.378100] Documentation/translations/zh_CN/arch/riscv/vm-layout.rst
[1788062042.518400] commit 954260ff5a46 ("Revert "RISC-V: mm: Document mmap changes"")
[1788062042.560926] commit 5c8405d763dc ("riscv: Extend sv39 linear mapping max size to 128G")
[1788062042.601822] commit 371a3c2055db ("docs: riscv: Define behavior of mmap")
[1788062042.601947] 3 commits needs resolving in total

.. So our script missed a few commit before name-changing?

But whatever, this file is not long and complicated. And the script is just a reference to check the status.

Also, we do not need contributors to update the translation one commit by one commit.

So, the best solution now is simply manually synchronizing the translation, I think.

Quoted 22 lines
Quoted 22 lines

Note that I'm not blaming on you for this. But I feel this is a point that a newcomer might find confusing, including me and Chen-Yu a couple of weeks ago, if did not read the script.

Our current how-to.rst only asks to write this line in the commit message but does not explain the results or the actual work behind it.

[...]
Update the translation through commit b080e52110ea ("docs: update self-protection __ro_after_init status") # 请执行 git log --oneline <您翻译的英文文档路径>,并替换上述内容

So when a newcomer comes and just does what this asks, without considering whether his/her/its translation is completely synchronized or not, our script would be kind of inaccurate. ?

Maybe we can add a description or a hint like:

If your current changes make the translation completely in line with the English version, then please add this line after your descriptions and before a blank line and your sign-off:

Quoted 6 lines
Quoted 4 lines

Update the translation through commit e83c5163316f (Initial revision of "git", the information manager from hell)

..then follows a template commit message

Allowing partial updates to the translation?

I think it's fine to do partial updates. If you just do partial updates, therefore do not add that line "Update the translation through commit abc". That would make the script think you have done all the missing jobs.

Also, you can absolutely write the _specific_ commit hash if you do so, (only update partial) , not the lastest commit hash of the English original one.

That said, I did not read the script yet. :( So I'd better take a close look then.

Quoted 3 lines
Quoted 1 line

(Should I cc the original authors of the script?)

CC the authors of the checktransupdate.py script?

Yes, but since Dongliang is the original author, I guess it's enough.

Thanks.

#4 lore raw
In reply to Yukai Wu
Quoted 24 lines · Yukai Wu

Update Documentation/arch/riscv/vm-layout.rst translation.

Update the translation through commit 954260ff5a46 ("Revert "RISC-V: mm: Document mmap changes"")

---
 .../zh_CN/arch/riscv/vm-layout.rst             | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)
Documentation/translations/zh_CN/arch/riscv/vm-layout.rst +1 -1
index 4b9f4dcf6c19..0d0ec8ea5d05 100644
@@ -15,7 +15,7 @@ RISC-V Linux上的虚拟内存布局
 :作者: Alexandre Ghiti <[email protected]>
 :日期: 12 February 2021
 
-这份文件描述了RISC-V Linux内核使用的虚拟内存布局。
+这份文件描述了 RISC-V Linux 内核使用的虚拟内存布局。
 
 32位 RISC-V Linux 内核
 ======================

Documentation/translations/zh_CN/arch/riscv/vm-layout.rst TODO · line 33

Quoted 9 lines
Documentation/translations/zh_CN/arch/riscv/vm-layout.rst +3 -3
@@ -28,9 +28,9 @@ TODO
 64位 RISC-V Linux 内核
 ======================
 
-RISC-V特权架构文档指出,64位地址 "必须使第63-48位值都等于第47位,否则将发生缺页异常。":这将虚
-拟地址空间分成两半,中间有一个非常大的洞,下半部分是用户空间所在的地方,上半部分是RISC-V Linux
-内核所在的地方。
+RISC-V 特权架构文档指出,64 位地址“必须使第 63-48 位值都等于第 47 位,否则将发生缺页异常。”:
+这将虚拟地址空间分成两半,中间有一个非常大的洞,下半部分是用户空间所在的地方,上半部分是 RISC-V
+Linux 内核所在的地方。

I think changes above are purely style improvements? If so please mention it in the commit message, instead of specifying it's "updating" only. Separate the changes into another commit might help, but I'm not sure whether it's worth the effort.

Regards,
Yao Zi

#5 lore raw
Quoted 28 lines · Yao Zi
Quoted 27 lines · Yukai Wu

Update Documentation/arch/riscv/vm-layout.rst translation.

Update the translation through commit 954260ff5a46 ("Revert "RISC-V: mm: Document mmap changes"")

---
 .../zh_CN/arch/riscv/vm-layout.rst             | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)
Documentation/translations/zh_CN/arch/riscv/vm-layout.rst +1 -1
index 4b9f4dcf6c19..0d0ec8ea5d05 100644
@@ -15,7 +15,7 @@ RISC-V Linux上的虚拟内存布局
 :作者: Alexandre Ghiti <[email protected]>
 :日期: 12 February 2021
 
-这份文件描述了RISC-V Linux内核使用的虚拟内存布局。
+这份文件描述了 RISC-V Linux 内核使用的虚拟内存布局。
 
 32位 RISC-V Linux 内核
 ======================
@@ -28,9 +28,9 @@ TODO
 64位 RISC-V Linux 内核
 ======================
 
Quoted 10 lines

Documentation/translations/zh_CN/arch/riscv/vm-layout.rst TODO · line 33

Quoted 6 lines
Documentation/translations/zh_CN/arch/riscv/vm-layout.rst +3 -3
-RISC-V特权架构文档指出,64位地址 "必须使第63-48位值都等于第47位,否则将发生缺页异常。":这将虚
-拟地址空间分成两半,中间有一个非常大的洞,下半部分是用户空间所在的地方,上半部分是RISC-V Linux
-内核所在的地方。
+RISC-V 特权架构文档指出,64 位地址“必须使第 63-48 位值都等于第 47 位,否则将发生缺页异常。”:
+这将虚拟地址空间分成两半,中间有一个非常大的洞,下半部分是用户空间所在的地方,上半部分是 RISC-V
+Linux 内核所在的地方。

I think changes above are purely style improvements? If so please mention it in the commit message, instead of specifying it's "updating" only.

Agreed. To put it further, I think the commit message template we provided in how-to.rst [1] is somewhat like telling contributors: That's all you need to do.

Of course, in some cases, the patch is quite simple and there is nothing else to elaborate on. However, in some cases, such as when making extensive changes and updates, we should encourage contributors to write down some relevant information for future reference.

Similarly, just like this patch, the author did more than just update; he also carried out other actions, but failed to include the relevant details in the commit message. So I feel that perhaps our template might have somewhat restricted our writing? (to some extent)

Sure, the requirements for commit messages in the Chinese documentation are certainly not as strict as those for the more core subsystems. However, I do think it's fine to appropriately explicitly encourage contributors to include more meaningful relevant information in the commit messages.

Any ideas for this, or any objections? ;)

Thanks!

[1] https://docs.kernel.org/translations/zh_CN/how-to.html#id13

#6 lore raw
Quoted 40 lines · Weijie Yuan
Quoted 28 lines · Yao Zi
Quoted 27 lines · Yukai Wu

Update Documentation/arch/riscv/vm-layout.rst translation.

Update the translation through commit 954260ff5a46 ("Revert "RISC-V: mm: Document mmap changes"")

---
 .../zh_CN/arch/riscv/vm-layout.rst             | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)
Documentation/translations/zh_CN/arch/riscv/vm-layout.rst +1 -1
index 4b9f4dcf6c19..0d0ec8ea5d05 100644
@@ -15,7 +15,7 @@ RISC-V Linux上的虚拟内存布局
 :作者: Alexandre Ghiti <[email protected]>
 :日期: 12 February 2021
 
-这份文件描述了RISC-V Linux内核使用的虚拟内存布局。
+这份文件描述了 RISC-V Linux 内核使用的虚拟内存布局。
 
 32位 RISC-V Linux 内核
 ======================
@@ -28,9 +28,9 @@ TODO
 64位 RISC-V Linux 内核
 ======================
 
Quoted 10 lines

Documentation/translations/zh_CN/arch/riscv/vm-layout.rst TODO · line 33

Quoted 6 lines
Documentation/translations/zh_CN/arch/riscv/vm-layout.rst +3 -3
-RISC-V特权架构文档指出,64位地址 "必须使第63-48位值都等于第47位,否则将发生缺页异常。":这将虚
-拟地址空间分成两半,中间有一个非常大的洞,下半部分是用户空间所在的地方,上半部分是RISC-V Linux
-内核所在的地方。
+RISC-V 特权架构文档指出,64 位地址“必须使第 63-48 位值都等于第 47 位,否则将发生缺页异常。”:
+这将虚拟地址空间分成两半,中间有一个非常大的洞,下半部分是用户空间所在的地方,上半部分是 RISC-V
+Linux 内核所在的地方。

I think changes above are purely style improvements? If so please mention it in the commit message, instead of specifying it's "updating" only.

Quoted 3 lines

Agreed. To put it further, I think the commit message template we provided in how-to.rst [1] is somewhat like telling contributors: That's all you need to do.

Oops, I don't even realize it's part of our existing contributing guide...

Quoted 9 lines

Of course, in some cases, the patch is quite simple and there is nothing else to elaborate on. However, in some cases, such as when making extensive changes and updates, we should encourage contributors to write down some relevant information for future reference.

Similarly, just like this patch, the author did more than just update; he also carried out other actions, but failed to include the relevant details in the commit message. So I feel that perhaps our template might have somewhat restricted our writing? (to some extent)

Agree.

Quoted 7 lines

Sure, the requirements for commit messages in the Chinese documentation are certainly not as strict as those for the more core subsystems. However, I do think it's fine to appropriately explicitly encourage contributors to include more meaningful relevant information in the commit messages.

Any ideas for this, or any objections? ;)

I think it's worth pointing out that the template commit message is for reference only in how-to.rst, and guiding readers to submitting-patches.rst so at least newcomers have a brief understanding of the process and requirements.

Now how-to.rst refers process/index.rst, but this index seems to contain too much for anyone unfamiliar with the process to read through.

Quoted 3 lines

Thanks!

[1] https://docs.kernel.org/translations/zh_CN/how-to.html#id13

Regards,
Yao Zi

_______________________________________________
linux-riscv mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-riscv