[PATCH v2 2/2] doc-guide: add help documentation checktransupdate.rst

[PATCH v2 2/2] doc-guide: add help documentation checktransupdate.rst

[Dongliang Mu]

This commit adds help documents - Documentation/doc-guide/checktransupdate.rst
and Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
for scripts/checktransupdate.py, including English and Chinese versions

Signed-off-by: Dongliang Mu <dzm91@hust.edu.cn>
---
v1->v2: fix some issues according to Randy
 Documentation/doc-guide/checktransupdate.rst  | 63 +++++++++++++++++++
 Documentation/doc-guide/index.rst             |  1 +
 .../zh_CN/doc-guide/checktransupdate.rst      | 62 ++++++++++++++++++
 .../translations/zh_CN/doc-guide/index.rst    |  1 +
 4 files changed, 127 insertions(+)
 create mode 100644 Documentation/doc-guide/checktransupdate.rst
 create mode 100644 Documentation/translations/zh_CN/doc-guide/checktransupdate.rst

diff --git a/Documentation/doc-guide/checktransupdate.rst b/Documentation/doc-guide/checktransupdate.rst
new file mode 100644
index 000000000000..4ece330882d6
--- /dev/null
+++ b/Documentation/doc-guide/checktransupdate.rst
@@ -0,0 +1,63 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Check translation update
+==========================
+
+This script helps track the translation status of the documentation in
+different locales, i.e., whether the documentation is up-to-date with
+the English counterpart.
+
+How it works
+------------
+
+It uses ``git log`` command to track the latest English commit from the
+translation commit (order by author date) and the latest English commits
+from HEAD. If any differences occur, the file is considered as out-of-date,
+then commits that need to be updated will be collected and reported.
+
+Features implemented
+--------------------
+
+-  check all files in a certain locale
+-  check a single file or a set of files
+-  provide options to change output format
+
+Usage
+-----
+
+::
+
+   checktransupdate.py [-h] [-l LOCALE] [--print-commits | --no-print-commits] [--print-updated-files | --no-print-updated-files] [--debug | --no-debug] [files ...]
+
+Options
+~~~~~~~
+
+-  ``-l``, ``--locale``: locale to check when file is not specified
+-  ``--[no-]print-commits``: whether to print commits between origin and
+   translation
+-  ``--[no-]print-updated-files``: whether to print files that do no
+   need to be updated
+-  ``files``: files to check, if this option is specified, the locale
+   option will be ignored.
+
+Samples
+~~~~~~~
+
+-  ``./scripts/checktransupdate.py -l zh_CN``
+   This will print all the files that need to be updated in the zh_CN locale.
+-  ``./scripts/checktransupdate.py Documentation/translations/zh_CN/process/coding-style.rst``
+   This will only print the status of the specified file.
+
+Then the output is something like:
+
+::
+
+    Documentation/translations/zh_CN/process/coding-style.rst       (2 commits)
+    commit 6813216bbdba ("Documentation: coding-style: ask function-like macros to evaluate parameters")
+    commit 185ea7676ef3 ("Documentation: coding-style: Update syntax highlighting for code-blocks")
+
+Features to be implemented
+----------------------------
+
+- track the translation status of files that have no translation
+- files can be a folder instead of only a file
diff --git a/Documentation/doc-guide/index.rst b/Documentation/doc-guide/index.rst
index 7c7d97784626..24d058faa75c 100644
--- a/Documentation/doc-guide/index.rst
+++ b/Documentation/doc-guide/index.rst
@@ -12,6 +12,7 @@ How to write kernel documentation
    parse-headers
    contributing
    maintainer-profile
+   checktransupdate
 
 .. only::  subproject and html
 
diff --git a/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst b/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
new file mode 100644
index 000000000000..37c0bb518ab8
--- /dev/null
+++ b/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
@@ -0,0 +1,62 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/doc-guide/checktransupdate.rst
+
+:译者: 慕冬亮 Dongliang Mu <dzm91@hust.edu.cn>
+
+检查翻译更新
+=============
+
+这个脚本帮助跟踪不同语言的文档翻译状态，即文档是否与对应的英文版本保持更新。
+
+工作原理
+------------
+
+它使用 ``git log`` 命令来跟踪翻译提交的最新英文提交（按作者日期排序）和英文文档的
+最新提交。如果有任何差异，则该文件被认为是过期的，然后需要更新的提交将被收集并报告。
+
+实现的功能
+--------------------
+
+- 检查特定语言中的所有文件
+- 检查单个文件或一组文件
+- 提供更改输出格式的选项
+
+用法
+-----
+
+::
+
+   checktransupdate.py [-h] [-l LOCALE] [--print-commits | --no-print-commits] [--print-updated-files | --no-print-updated-files] [--debug | --no-debug] [files ...]
+
+选项
+~~~~~~~
+
+-  ``-l``, ``--locale``: 检查指定的文件语言，如果未指定文件
+-  ``--[no-]print-commits``: 是否打印英文原始版本和翻译版本之间的提交
+-  ``--[no-]print-updated-files``: 是否打印无需更新的文件
+-  ``files``: 要检查的文件，如果指定了此选项，将忽略语言选项
+
+示例
+~~~~~~~
+
+-  ``./scripts/checktransupdate.py -l zh_CN``
+   这将打印 zh_CN 语言中需要更新的所有文件。
+-  ``./scripts/checktransupdate.py Documentation/translations/zh_CN/process/coding-style.rst``
+   这将只打印指定文件的状态。
+
+然后输出类似如下的内容：
+
+::
+
+    Documentation/translations/zh_CN/process/coding-style.rst       (2 commits)
+    commit 6813216bbdba ("Documentation: coding-style: ask function-like macros to evaluate parameters")
+    commit 185ea7676ef3 ("Documentation: coding-style: Update syntax highlighting for code-blocks")
+
+待实现的功能
+-------------
+
+- 跟踪没有翻译过的文件的翻译状态
+- 文件参数可以是文件夹而不仅仅是单个文件
diff --git a/Documentation/translations/zh_CN/doc-guide/index.rst b/Documentation/translations/zh_CN/doc-guide/index.rst
index 78c2e9a1697f..0ac1fc9315ea 100644
--- a/Documentation/translations/zh_CN/doc-guide/index.rst
+++ b/Documentation/translations/zh_CN/doc-guide/index.rst
@@ -18,6 +18,7 @@
    parse-headers
    contributing
    maintainer-profile
+   checktransupdate
 
 .. only::  subproject and html
 
-- 
2.39.2

Re: [PATCH v2 2/2] doc-guide: add help documentation checktransupdate.rst

[si.yanteng]

2024年6月15日 11:53, "Dongliang Mu" <dzm91@hust.edu.cn> 写到:



> 
> This commit adds help documents - Documentation/doc-guide/checktransupdate.rst
> 
> and Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
> 
> for scripts/checktransupdate.py, including English and Chinese versions
> 
> Signed-off-by: Dongliang Mu <dzm91@hust.edu.cn>
> 
> ---
> 
> v1->v2: fix some issues according to Randy
> 
>  Documentation/doc-guide/checktransupdate.rst | 63 +++++++++++++++++++
> 
>  Documentation/doc-guide/index.rst | 1 +
> 
>  .../zh_CN/doc-guide/checktransupdate.rst | 62 ++++++++++++++++++
> 
>  .../translations/zh_CN/doc-guide/index.rst | 1 +
> 
>  4 files changed, 127 insertions(+)
> 
>  create mode 100644 Documentation/doc-guide/checktransupdate.rst
> 
>  create mode 100644 Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
> 
> diff --git a/Documentation/doc-guide/checktransupdate.rst b/Documentation/doc-guide/checktransupdate.rst
> 
> new file mode 100644
> 
> index 000000000000..4ece330882d6
> 
> --- /dev/null
> 
> +++ b/Documentation/doc-guide/checktransupdate.rst
> 
> @@ -0,0 +1,63 @@
> 
> +.. SPDX-License-Identifier: GPL-2.0
> 
> +
> 
> +Check translation update
> 
> +==========================
Let's get rid of unnecessary symbols.
> 
> +
> 
> +This script helps track the translation status of the documentation in
> 
> +different locales, i.e., whether the documentation is up-to-date with
> 
> +the English counterpart.
> 
> +
> 
> +How it works
> 
> +------------
> 
> +
> 
> +It uses ``git log`` command to track the latest English commit from the
> 
> +translation commit (order by author date) and the latest English commits
> 
> +from HEAD. If any differences occur, the file is considered as out-of-date,
> 
> +then commits that need to be updated will be collected and reported.
> 
> +
> 
> +Features implemented
> 
> +--------------------
> 
> +
> 
> +- check all files in a certain locale
> 
> +- check a single file or a set of files
> 
> +- provide options to change output format
> 
> +
> 
> +Usage
> 
> +-----
> 
> +
> 
> +::
> 
> +
> 
> + checktransupdate.py [-h] [-l LOCALE] [--print-commits | --no-print-commits] [--print-updated-files | --no-print-updated-files] [--debug | --no-debug] [files ...]
> 
> +
> 
> +Options
> 
> +~~~~~~~
> 
> +
> 
> +- ``-l``, ``--locale``: locale to check when file is not specified
> 
> +- ``--[no-]print-commits``: whether to print commits between origin and
> 
> + translation
> 
> +- ``--[no-]print-updated-files``: whether to print files that do no
> 
> + need to be updated
> 
> +- ``files``: files to check, if this option is specified, the locale
> 
> + option will be ignored.
> 
> +
> 
> +Samples
> 
> +~~~~~~~
> 
> +
> 
> +- ``./scripts/checktransupdate.py -l zh_CN``
> 
> + This will print all the files that need to be updated in the zh_CN locale.
> 
> +- ``./scripts/checktransupdate.py Documentation/translations/zh_CN/process/coding-style.rst``
> 
> + This will only print the status of the specified file.
> 
> +
> 
> +Then the output is something like:
> 
> +
> 
> +::
> 
> +
> 
> + Documentation/translations/zh_CN/process/coding-style.rst (2 commits)
> 
> + commit 6813216bbdba ("Documentation: coding-style: ask function-like macros to evaluate parameters")
> 
> + commit 185ea7676ef3 ("Documentation: coding-style: Update syntax highlighting for code-blocks")
> 
> +
> 
> +Features to be implemented
> 
> +----------------------------
ditto

> 
> +
> 
> +- track the translation status of files that have no translation
> 
> +- files can be a folder instead of only a file
> 
> diff --git a/Documentation/doc-guide/index.rst b/Documentation/doc-guide/index.rst
> 
> index 7c7d97784626..24d058faa75c 100644
> 
> --- a/Documentation/doc-guide/index.rst
> 
> +++ b/Documentation/doc-guide/index.rst
> 
> @@ -12,6 +12,7 @@ How to write kernel documentation
> 
>  parse-headers
> 
>  contributing
> 
>  maintainer-profile
> 
> + checktransupdate
> 
>  
> 
>  .. only:: subproject and html
> 
>  
> 
> diff --git a/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst b/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
> 
> new file mode 100644
> 
> index 000000000000..37c0bb518ab8
> 
> --- /dev/null
> 
> +++ b/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
> 
> @@ -0,0 +1,62 @@
> 
> +.. SPDX-License-Identifier: GPL-2.0
> 
> +
> 
> +.. include:: ../disclaimer-zh_CN.rst
> 
> +
> 
> +:Original: Documentation/doc-guide/checktransupdate.rst
> 
> +
> 
> +:译者: 慕冬亮 Dongliang Mu <dzm91@hust.edu.cn>
> 
> +
> 
> +检查翻译更新
> 
> +=============
ditto
> 
> +
> 
> +这个脚本帮助跟踪不同语言的文档翻译状态，即文档是否与对应的英文版本保持更新。
> 
> +
> 
> +工作原理
> 
> +------------
> 
> +
> 
> +它使用 ``git log`` 命令来跟踪翻译提交的最新英文提交（按作者日期排序）和英文文档的
> 
> +最新提交。如果有任何差异，则该文件被认为是过期的，然后需要更新的提交将被收集并报告。
> 
> +
> 
> +实现的功能
> 
> +--------------------
ditto

...

> 
> +
> 
> +- 检查特定语言中的所有文件
> 
> +- 检查单个文件或一组文件
> 
> +- 提供更改输出格式的选项
> 
> +
> 
> +用法
> 
> +-----
> 
> +
> 
> +::
> 
> +
> 
> + checktransupdate.py [-h] [-l LOCALE] [--print-commits | --no-print-commits] [--print-updated-files | --no-print-updated-files] [--debug | --no-debug] [files ...]
> 
> +
> 
> +选项
> 
> +~~~~~~~
> 
> +
> 
> +- ``-l``, ``--locale``: 检查指定的文件语言，如果未指定文件
> 
> +- ``--[no-]print-commits``: 是否打印英文原始版本和翻译版本之间的提交
> 
> +- ``--[no-]print-updated-files``: 是否打印无需更新的文件
> 
> +- ``files``: 要检查的文件，如果指定了此选项，将忽略语言选项
> 
> +
> 
> +示例
> 
> +~~~~~~~

ditto


Thanks,
Yanteng
> 
> +
> 
> +- ``./scripts/checktransupdate.py -l zh_CN``
> 
> + 这将打印 zh_CN 语言中需要更新的所有文件。
> 
> +- ``./scripts/checktransupdate.py Documentation/translations/zh_CN/process/coding-style.rst``
> 
> + 这将只打印指定文件的状态。
> 
> +
> 
> +然后输出类似如下的内容：
> 
> +
> 
> +::
> 
> +
> 
> + Documentation/translations/zh_CN/process/coding-style.rst (2 commits)
> 
> + commit 6813216bbdba ("Documentation: coding-style: ask function-like macros to evaluate parameters")
> 
> + commit 185ea7676ef3 ("Documentation: coding-style: Update syntax highlighting for code-blocks")
> 
> +
> 
> +待实现的功能
> 
> +-------------
> 
> +
> 
> +- 跟踪没有翻译过的文件的翻译状态
> 
> +- 文件参数可以是文件夹而不仅仅是单个文件
> 
> diff --git a/Documentation/translations/zh_CN/doc-guide/index.rst b/Documentation/translations/zh_CN/doc-guide/index.rst
> 
> index 78c2e9a1697f..0ac1fc9315ea 100644
> 
> --- a/Documentation/translations/zh_CN/doc-guide/index.rst
> 
> +++ b/Documentation/translations/zh_CN/doc-guide/index.rst
> 
> @@ -18,6 +18,7 @@
> 
>  parse-headers
> 
>  contributing
> 
>  maintainer-profile
> 
> + checktransupdate
> 
>  
> 
>  .. only:: subproject and html
> 
>  
> 
> -- 
> 
> 2.39.2
>

Re: [PATCH v2 2/2] doc-guide: add help documentation checktransupdate.rst

[Dongliang Mu]

On 2024/6/15 15:57, si.yanteng@linux.dev wrote:
> 2024年6月15日 11:53, "Dongliang Mu" <dzm91@hust.edu.cn> 写到:
>
>
>
>> This commit adds help documents - Documentation/doc-guide/checktransupdate.rst
>>
>> and Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
>>
>> for scripts/checktransupdate.py, including English and Chinese versions
>>
>> Signed-off-by: Dongliang Mu <dzm91@hust.edu.cn>
>>
>> ---
>>
>> v1->v2: fix some issues according to Randy
>>
>>   Documentation/doc-guide/checktransupdate.rst | 63 +++++++++++++++++++
>>
>>   Documentation/doc-guide/index.rst | 1 +
>>
>>   .../zh_CN/doc-guide/checktransupdate.rst | 62 ++++++++++++++++++
>>
>>   .../translations/zh_CN/doc-guide/index.rst | 1 +
>>
>>   4 files changed, 127 insertions(+)
>>
>>   create mode 100644 Documentation/doc-guide/checktransupdate.rst
>>
>>   create mode 100644 Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
>>
>> diff --git a/Documentation/doc-guide/checktransupdate.rst b/Documentation/doc-guide/checktransupdate.rst
>>
>> new file mode 100644
>>
>> index 000000000000..4ece330882d6
>>
>> --- /dev/null
>>
>> +++ b/Documentation/doc-guide/checktransupdate.rst
>>
>> @@ -0,0 +1,63 @@
>>
>> +.. SPDX-License-Identifier: GPL-2.0
>>
>> +
>>
>> +Check translation update
>>
>> +==========================
> Let's get rid of unnecessary symbols.
>> +
>>
>> +This script helps track the translation status of the documentation in
>>
>> +different locales, i.e., whether the documentation is up-to-date with
>>
>> +the English counterpart.
>>
>> +
>>
>> +How it works
>>
>> +------------
>>
>> +
>>
>> +It uses ``git log`` command to track the latest English commit from the
>>
>> +translation commit (order by author date) and the latest English commits
>>
>> +from HEAD. If any differences occur, the file is considered as out-of-date,
>>
>> +then commits that need to be updated will be collected and reported.
>>
>> +
>>
>> +Features implemented
>>
>> +--------------------
>>
>> +
>>
>> +- check all files in a certain locale
>>
>> +- check a single file or a set of files
>>
>> +- provide options to change output format
>>
>> +
>>
>> +Usage
>>
>> +-----
>>
>> +
>>
>> +::
>>
>> +
>>
>> + checktransupdate.py [-h] [-l LOCALE] [--print-commits | --no-print-commits] [--print-updated-files | --no-print-updated-files] [--debug | --no-debug] [files ...]
>>
>> +
>>
>> +Options
>>
>> +~~~~~~~
>>
>> +
>>
>> +- ``-l``, ``--locale``: locale to check when file is not specified
>>
>> +- ``--[no-]print-commits``: whether to print commits between origin and
>>
>> + translation
>>
>> +- ``--[no-]print-updated-files``: whether to print files that do no
>>
>> + need to be updated
>>
>> +- ``files``: files to check, if this option is specified, the locale
>>
>> + option will be ignored.
>>
>> +
>>
>> +Samples
>>
>> +~~~~~~~
>>
>> +
>>
>> +- ``./scripts/checktransupdate.py -l zh_CN``
>>
>> + This will print all the files that need to be updated in the zh_CN locale.
>>
>> +- ``./scripts/checktransupdate.py Documentation/translations/zh_CN/process/coding-style.rst``
>>
>> + This will only print the status of the specified file.
>>
>> +
>>
>> +Then the output is something like:
>>
>> +
>>
>> +::
>>
>> +
>>
>> + Documentation/translations/zh_CN/process/coding-style.rst (2 commits)
>>
>> + commit 6813216bbdba ("Documentation: coding-style: ask function-like macros to evaluate parameters")
>>
>> + commit 185ea7676ef3 ("Documentation: coding-style: Update syntax highlighting for code-blocks")
>>
>> +
>>
>> +Features to be implemented
>>
>> +----------------------------
> ditto
>
>> +
>>
>> +- track the translation status of files that have no translation
>>
>> +- files can be a folder instead of only a file
>>
>> diff --git a/Documentation/doc-guide/index.rst b/Documentation/doc-guide/index.rst
>>
>> index 7c7d97784626..24d058faa75c 100644
>>
>> --- a/Documentation/doc-guide/index.rst
>>
>> +++ b/Documentation/doc-guide/index.rst
>>
>> @@ -12,6 +12,7 @@ How to write kernel documentation
>>
>>   parse-headers
>>
>>   contributing
>>
>>   maintainer-profile
>>
>> + checktransupdate
>>
>>   
>>
>>   .. only:: subproject and html
>>
>>   
>>
>> diff --git a/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst b/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
>>
>> new file mode 100644
>>
>> index 000000000000..37c0bb518ab8
>>
>> --- /dev/null
>>
>> +++ b/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
>>
>> @@ -0,0 +1,62 @@
>>
>> +.. SPDX-License-Identifier: GPL-2.0
>>
>> +
>>
>> +.. include:: ../disclaimer-zh_CN.rst
>>
>> +
>>
>> +:Original: Documentation/doc-guide/checktransupdate.rst
>>
>> +
>>
>> +:译者: 慕冬亮 Dongliang Mu <dzm91@hust.edu.cn>
>>
>> +
>>
>> +检查翻译更新
>>
>> +=============
> ditto
>> +
>>
>> +这个脚本帮助跟踪不同语言的文档翻译状态，即文档是否与对应的英文版本保持更新。
>>
>> +
>>
>> +工作原理
>>
>> +------------
>>
>> +
>>
>> +它使用 ``git log`` 命令来跟踪翻译提交的最新英文提交（按作者日期排序）和英文文档的
>>
>> +最新提交。如果有任何差异，则该文件被认为是过期的，然后需要更新的提交将被收集并报告。
>>
>> +
>>
>> +实现的功能
>>
>> +--------------------
> ditto
>
> ...
>
>> +
>>
>> +- 检查特定语言中的所有文件
>>
>> +- 检查单个文件或一组文件
>>
>> +- 提供更改输出格式的选项
>>
>> +
>>
>> +用法
>>
>> +-----
>>
>> +
>>
>> +::
>>
>> +
>>
>> + checktransupdate.py [-h] [-l LOCALE] [--print-commits | --no-print-commits] [--print-updated-files | --no-print-updated-files] [--debug | --no-debug] [files ...]
>>
>> +
>>
>> +选项
>>
>> +~~~~~~~
>>
>> +
>>
>> +- ``-l``, ``--locale``: 检查指定的文件语言，如果未指定文件
>>
>> +- ``--[no-]print-commits``: 是否打印英文原始版本和翻译版本之间的提交
>>
>> +- ``--[no-]print-updated-files``: 是否打印无需更新的文件
>>
>> +- ``files``: 要检查的文件，如果指定了此选项，将忽略语言选项
>>
>> +
>>
>> +示例
>>
>> +~~~~~~~
> ditto


Yanteng,

the requested changes does not match between English and Chinse translation.

Dongliang Mu


>
>
> Thanks,
> Yanteng
>> +
>>
>> +- ``./scripts/checktransupdate.py -l zh_CN``
>>
>> + 这将打印 zh_CN 语言中需要更新的所有文件。
>>
>> +- ``./scripts/checktransupdate.py Documentation/translations/zh_CN/process/coding-style.rst``
>>
>> + 这将只打印指定文件的状态。
>>
>> +
>>
>> +然后输出类似如下的内容：
>>
>> +
>>
>> +::
>>
>> +
>>
>> + Documentation/translations/zh_CN/process/coding-style.rst (2 commits)
>>
>> + commit 6813216bbdba ("Documentation: coding-style: ask function-like macros to evaluate parameters")
>>
>> + commit 185ea7676ef3 ("Documentation: coding-style: Update syntax highlighting for code-blocks")
>>
>> +
>>
>> +待实现的功能
>>
>> +-------------
>>
>> +
>>
>> +- 跟踪没有翻译过的文件的翻译状态
>>
>> +- 文件参数可以是文件夹而不仅仅是单个文件
>>
>> diff --git a/Documentation/translations/zh_CN/doc-guide/index.rst b/Documentation/translations/zh_CN/doc-guide/index.rst
>>
>> index 78c2e9a1697f..0ac1fc9315ea 100644
>>
>> --- a/Documentation/translations/zh_CN/doc-guide/index.rst
>>
>> +++ b/Documentation/translations/zh_CN/doc-guide/index.rst
>>
>> @@ -18,6 +18,7 @@
>>
>>   parse-headers
>>
>>   contributing
>>
>>   maintainer-profile
>>
>> + checktransupdate
>>
>>   
>>
>>   .. only:: subproject and html
>>
>>   
>>
>> -- 
>>
>> 2.39.2
>>

Re: [PATCH v2 1/2] scripts: fix most issues reported by pylint

[Yanteng Si]

Hi,Dongliang

在 2024/6/17 09:05, Dongliang Mu 写道:
>
> On 2024/6/16 03:42, Jonathan Corbet wrote:
>> Dongliang Mu <dzm91@hust.edu.cn> writes:
>>
>>> Pylint reports many coding style issues of scripts/checktransupdate.py
>>>
>>> This patch fixes most issues with the following contents:
>>> - add or revise comments for all functions
>>> - use format string suggested by python
>>>
>>> Signed-off-by: Dongliang Mu <dzm91@hust.edu.cn>
>>> ---
>>>   scripts/checktransupdate.py | 55 
>>> ++++++++++++++++---------------------
>>>   1 file changed, 24 insertions(+), 31 deletions(-)
>> How does this differ from v1?  Please always give that information so
>> reviewers know what's going on.
>
> Hi Jon,
>
> Patch 1/2 in v2 patch has no difference with Patch 1/2 in v1. Randy 
> put up some change requests about
>
> the help documentation, and it is written in the Patch 2/2 in v2.
>
> I am not sure how to show this information in Patch 1/2. How about 
> "v1->v2: no changes"?
>
>
Let's make a cover letter, just like:

<https://lore.kernel.org/netdev/cover.1716973237.git.siyanteng@loongson.cn/>


you can run:


$: git format-patch xxxxx   --cover-letter


BTW,

It seem that you forget to cc  linux-doc@vger.kernel.org.


Thanks,

Yanteng

Re: [PATCH v2 1/2] scripts: fix most issues reported by pylint

[Dongliang Mu]

On 2024/6/17 10:29, Yanteng Si wrote:
> Hi,Dongliang
>
> 在 2024/6/17 09:05, Dongliang Mu 写道:
>>
>> On 2024/6/16 03:42, Jonathan Corbet wrote:
>>> Dongliang Mu <dzm91@hust.edu.cn> writes:
>>>
>>>> Pylint reports many coding style issues of scripts/checktransupdate.py
>>>>
>>>> This patch fixes most issues with the following contents:
>>>> - add or revise comments for all functions
>>>> - use format string suggested by python
>>>>
>>>> Signed-off-by: Dongliang Mu <dzm91@hust.edu.cn>
>>>> ---
>>>>   scripts/checktransupdate.py | 55 
>>>> ++++++++++++++++---------------------
>>>>   1 file changed, 24 insertions(+), 31 deletions(-)
>>> How does this differ from v1?  Please always give that information so
>>> reviewers know what's going on.
>>
>> Hi Jon,
>>
>> Patch 1/2 in v2 patch has no difference with Patch 1/2 in v1. Randy 
>> put up some change requests about
>>
>> the help documentation, and it is written in the Patch 2/2 in v2.
>>
>> I am not sure how to show this information in Patch 1/2. How about 
>> "v1->v2: no changes"?
>>
>>
> Let's make a cover letter, just like:
>
> <https://lore.kernel.org/netdev/cover.1716973237.git.siyanteng@loongson.cn/> 
>
>
>
> you can run:
>
>
> $: git format-patch xxxxx   --cover-letter
>
I see. I will follow this rule when sending a patchset in the future.

Thanks for your helpful message.

>
> BTW,
>
> It seem that you forget to cc  linux-doc@vger.kernel.org.
>
>
> Thanks,
>
> Yanteng

Re: [PATCH v2 2/2] doc-guide: add help documentation checktransupdate.rst

[Jani Nikula]

On Sat, 15 Jun 2024, Dongliang Mu <dzm91@hust.edu.cn> wrote:
> This commit adds help documents - Documentation/doc-guide/checktransupdate.rst
> and Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
> for scripts/checktransupdate.py, including English and Chinese versions
>
> Signed-off-by: Dongliang Mu <dzm91@hust.edu.cn>
> ---
> v1->v2: fix some issues according to Randy
>  Documentation/doc-guide/checktransupdate.rst  | 63 +++++++++++++++++++
>  Documentation/doc-guide/index.rst             |  1 +
>  .../zh_CN/doc-guide/checktransupdate.rst      | 62 ++++++++++++++++++
>  .../translations/zh_CN/doc-guide/index.rst    |  1 +
>  4 files changed, 127 insertions(+)
>  create mode 100644 Documentation/doc-guide/checktransupdate.rst
>  create mode 100644 Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
>
> diff --git a/Documentation/doc-guide/checktransupdate.rst b/Documentation/doc-guide/checktransupdate.rst
> new file mode 100644
> index 000000000000..4ece330882d6
> --- /dev/null
> +++ b/Documentation/doc-guide/checktransupdate.rst
> @@ -0,0 +1,63 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +Check translation update
> +==========================
> +
> +This script helps track the translation status of the documentation in
> +different locales, i.e., whether the documentation is up-to-date with
> +the English counterpart.
> +
> +How it works
> +------------
> +
> +It uses ``git log`` command to track the latest English commit from the
> +translation commit (order by author date) and the latest English commits
> +from HEAD. If any differences occur, the file is considered as out-of-date,
> +then commits that need to be updated will be collected and reported.
> +
> +Features implemented
> +--------------------
> +
> +-  check all files in a certain locale
> +-  check a single file or a set of files
> +-  provide options to change output format
> +
> +Usage
> +-----

Why not document the argument parser and tell people ot run
'checktransupdate.py --help' here? Duplicating the usage here is just a
maintenance burden.

BR,
Jani.




> +
> +::
> +
> +   checktransupdate.py [-h] [-l LOCALE] [--print-commits | --no-print-commits] [--print-updated-files | --no-print-updated-files] [--debug | --no-debug] [files ...]
> +
> +Options
> +~~~~~~~
> +
> +-  ``-l``, ``--locale``: locale to check when file is not specified
> +-  ``--[no-]print-commits``: whether to print commits between origin and
> +   translation
> +-  ``--[no-]print-updated-files``: whether to print files that do no
> +   need to be updated
> +-  ``files``: files to check, if this option is specified, the locale
> +   option will be ignored.
> +
> +Samples
> +~~~~~~~
> +
> +-  ``./scripts/checktransupdate.py -l zh_CN``
> +   This will print all the files that need to be updated in the zh_CN locale.
> +-  ``./scripts/checktransupdate.py Documentation/translations/zh_CN/process/coding-style.rst``
> +   This will only print the status of the specified file.
> +
> +Then the output is something like:
> +
> +::
> +
> +    Documentation/translations/zh_CN/process/coding-style.rst       (2 commits)
> +    commit 6813216bbdba ("Documentation: coding-style: ask function-like macros to evaluate parameters")
> +    commit 185ea7676ef3 ("Documentation: coding-style: Update syntax highlighting for code-blocks")
> +
> +Features to be implemented
> +----------------------------
> +
> +- track the translation status of files that have no translation
> +- files can be a folder instead of only a file
> diff --git a/Documentation/doc-guide/index.rst b/Documentation/doc-guide/index.rst
> index 7c7d97784626..24d058faa75c 100644
> --- a/Documentation/doc-guide/index.rst
> +++ b/Documentation/doc-guide/index.rst
> @@ -12,6 +12,7 @@ How to write kernel documentation
>     parse-headers
>     contributing
>     maintainer-profile
> +   checktransupdate
>  
>  .. only::  subproject and html
>  
> diff --git a/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst b/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
> new file mode 100644
> index 000000000000..37c0bb518ab8
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
> @@ -0,0 +1,62 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: Documentation/doc-guide/checktransupdate.rst
> +
> +:译者: 慕冬亮 Dongliang Mu <dzm91@hust.edu.cn>
> +
> +检查翻译更新
> +=============
> +
> +这个脚本帮助跟踪不同语言的文档翻译状态，即文档是否与对应的英文版本保持更新。
> +
> +工作原理
> +------------
> +
> +它使用 ``git log`` 命令来跟踪翻译提交的最新英文提交（按作者日期排序）和英文文档的
> +最新提交。如果有任何差异，则该文件被认为是过期的，然后需要更新的提交将被收集并报告。
> +
> +实现的功能
> +--------------------
> +
> +- 检查特定语言中的所有文件
> +- 检查单个文件或一组文件
> +- 提供更改输出格式的选项
> +
> +用法
> +-----
> +
> +::
> +
> +   checktransupdate.py [-h] [-l LOCALE] [--print-commits | --no-print-commits] [--print-updated-files | --no-print-updated-files] [--debug | --no-debug] [files ...]
> +
> +选项
> +~~~~~~~
> +
> +-  ``-l``, ``--locale``: 检查指定的文件语言，如果未指定文件
> +-  ``--[no-]print-commits``: 是否打印英文原始版本和翻译版本之间的提交
> +-  ``--[no-]print-updated-files``: 是否打印无需更新的文件
> +-  ``files``: 要检查的文件，如果指定了此选项，将忽略语言选项
> +
> +示例
> +~~~~~~~
> +
> +-  ``./scripts/checktransupdate.py -l zh_CN``
> +   这将打印 zh_CN 语言中需要更新的所有文件。
> +-  ``./scripts/checktransupdate.py Documentation/translations/zh_CN/process/coding-style.rst``
> +   这将只打印指定文件的状态。
> +
> +然后输出类似如下的内容：
> +
> +::
> +
> +    Documentation/translations/zh_CN/process/coding-style.rst       (2 commits)
> +    commit 6813216bbdba ("Documentation: coding-style: ask function-like macros to evaluate parameters")
> +    commit 185ea7676ef3 ("Documentation: coding-style: Update syntax highlighting for code-blocks")
> +
> +待实现的功能
> +-------------
> +
> +- 跟踪没有翻译过的文件的翻译状态
> +- 文件参数可以是文件夹而不仅仅是单个文件
> diff --git a/Documentation/translations/zh_CN/doc-guide/index.rst b/Documentation/translations/zh_CN/doc-guide/index.rst
> index 78c2e9a1697f..0ac1fc9315ea 100644
> --- a/Documentation/translations/zh_CN/doc-guide/index.rst
> +++ b/Documentation/translations/zh_CN/doc-guide/index.rst
> @@ -18,6 +18,7 @@
>     parse-headers
>     contributing
>     maintainer-profile
> +   checktransupdate
>  
>  .. only::  subproject and html

-- 
Jani Nikula, Intel

Re: [PATCH v2 2/2] doc-guide: add help documentation checktransupdate.rst

[Dongliang Mu]

On Mon, Jun 17, 2024 at 4:32 PM Jani Nikula <jani.nikula@linux.intel.com> wrote:
>
> On Sat, 15 Jun 2024, Dongliang Mu <dzm91@hust.edu.cn> wrote:
> > This commit adds help documents - Documentation/doc-guide/checktransupdate.rst
> > and Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
> > for scripts/checktransupdate.py, including English and Chinese versions
> >
> > Signed-off-by: Dongliang Mu <dzm91@hust.edu.cn>
> > ---
> > v1->v2: fix some issues according to Randy
> >  Documentation/doc-guide/checktransupdate.rst  | 63 +++++++++++++++++++
> >  Documentation/doc-guide/index.rst             |  1 +
> >  .../zh_CN/doc-guide/checktransupdate.rst      | 62 ++++++++++++++++++
> >  .../translations/zh_CN/doc-guide/index.rst    |  1 +
> >  4 files changed, 127 insertions(+)
> >  create mode 100644 Documentation/doc-guide/checktransupdate.rst
> >  create mode 100644 Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
> >
> > diff --git a/Documentation/doc-guide/checktransupdate.rst b/Documentation/doc-guide/checktransupdate.rst
> > new file mode 100644
> > index 000000000000..4ece330882d6
> > --- /dev/null
> > +++ b/Documentation/doc-guide/checktransupdate.rst
> > @@ -0,0 +1,63 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +Check translation update
> > +==========================
> > +
> > +This script helps track the translation status of the documentation in
> > +different locales, i.e., whether the documentation is up-to-date with
> > +the English counterpart.
> > +
> > +How it works
> > +------------
> > +
> > +It uses ``git log`` command to track the latest English commit from the
> > +translation commit (order by author date) and the latest English commits
> > +from HEAD. If any differences occur, the file is considered as out-of-date,
> > +then commits that need to be updated will be collected and reported.
> > +
> > +Features implemented
> > +--------------------
> > +
> > +-  check all files in a certain locale
> > +-  check a single file or a set of files
> > +-  provide options to change output format
> > +
> > +Usage
> > +-----
>
> Why not document the argument parser and tell people ot run
> 'checktransupdate.py --help' here? Duplicating the usage here is just a
> maintenance burden.
>

Thanks, this is a good suggestion. I will modify it in the v3 patch.

> BR,
> Jani.
>
>
>
>
> > +
> > +::
> > +
> > +   checktransupdate.py [-h] [-l LOCALE] [--print-commits | --no-print-commits] [--print-updated-files | --no-print-updated-files] [--debug | --no-debug] [files ...]
> > +
> > +Options
> > +~~~~~~~
> > +
> > +-  ``-l``, ``--locale``: locale to check when file is not specified
> > +-  ``--[no-]print-commits``: whether to print commits between origin and
> > +   translation
> > +-  ``--[no-]print-updated-files``: whether to print files that do no
> > +   need to be updated
> > +-  ``files``: files to check, if this option is specified, the locale
> > +   option will be ignored.
> > +
> > +Samples
> > +~~~~~~~
> > +
> > +-  ``./scripts/checktransupdate.py -l zh_CN``
> > +   This will print all the files that need to be updated in the zh_CN locale.
> > +-  ``./scripts/checktransupdate.py Documentation/translations/zh_CN/process/coding-style.rst``
> > +   This will only print the status of the specified file.
> > +
> > +Then the output is something like:
> > +
> > +::
> > +
> > +    Documentation/translations/zh_CN/process/coding-style.rst       (2 commits)
> > +    commit 6813216bbdba ("Documentation: coding-style: ask function-like macros to evaluate parameters")
> > +    commit 185ea7676ef3 ("Documentation: coding-style: Update syntax highlighting for code-blocks")
> > +
> > +Features to be implemented
> > +----------------------------
> > +
> > +- track the translation status of files that have no translation
> > +- files can be a folder instead of only a file
> > diff --git a/Documentation/doc-guide/index.rst b/Documentation/doc-guide/index.rst
> > index 7c7d97784626..24d058faa75c 100644
> > --- a/Documentation/doc-guide/index.rst
> > +++ b/Documentation/doc-guide/index.rst
> > @@ -12,6 +12,7 @@ How to write kernel documentation
> >     parse-headers
> >     contributing
> >     maintainer-profile
> > +   checktransupdate
> >
> >  .. only::  subproject and html
> >
> > diff --git a/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst b/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
> > new file mode 100644
> > index 000000000000..37c0bb518ab8
> > --- /dev/null
> > +++ b/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
> > @@ -0,0 +1,62 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +.. include:: ../disclaimer-zh_CN.rst
> > +
> > +:Original: Documentation/doc-guide/checktransupdate.rst
> > +
> > +:译者: 慕冬亮 Dongliang Mu <dzm91@hust.edu.cn>
> > +
> > +检查翻译更新
> > +=============
> > +
> > +这个脚本帮助跟踪不同语言的文档翻译状态，即文档是否与对应的英文版本保持更新。
> > +
> > +工作原理
> > +------------
> > +
> > +它使用 ``git log`` 命令来跟踪翻译提交的最新英文提交（按作者日期排序）和英文文档的
> > +最新提交。如果有任何差异，则该文件被认为是过期的，然后需要更新的提交将被收集并报告。
> > +
> > +实现的功能
> > +--------------------
> > +
> > +- 检查特定语言中的所有文件
> > +- 检查单个文件或一组文件
> > +- 提供更改输出格式的选项
> > +
> > +用法
> > +-----
> > +
> > +::
> > +
> > +   checktransupdate.py [-h] [-l LOCALE] [--print-commits | --no-print-commits] [--print-updated-files | --no-print-updated-files] [--debug | --no-debug] [files ...]
> > +
> > +选项
> > +~~~~~~~
> > +
> > +-  ``-l``, ``--locale``: 检查指定的文件语言，如果未指定文件
> > +-  ``--[no-]print-commits``: 是否打印英文原始版本和翻译版本之间的提交
> > +-  ``--[no-]print-updated-files``: 是否打印无需更新的文件
> > +-  ``files``: 要检查的文件，如果指定了此选项，将忽略语言选项
> > +
> > +示例
> > +~~~~~~~
> > +
> > +-  ``./scripts/checktransupdate.py -l zh_CN``
> > +   这将打印 zh_CN 语言中需要更新的所有文件。
> > +-  ``./scripts/checktransupdate.py Documentation/translations/zh_CN/process/coding-style.rst``
> > +   这将只打印指定文件的状态。
> > +
> > +然后输出类似如下的内容：
> > +
> > +::
> > +
> > +    Documentation/translations/zh_CN/process/coding-style.rst       (2 commits)
> > +    commit 6813216bbdba ("Documentation: coding-style: ask function-like macros to evaluate parameters")
> > +    commit 185ea7676ef3 ("Documentation: coding-style: Update syntax highlighting for code-blocks")
> > +
> > +待实现的功能
> > +-------------
> > +
> > +- 跟踪没有翻译过的文件的翻译状态
> > +- 文件参数可以是文件夹而不仅仅是单个文件
> > diff --git a/Documentation/translations/zh_CN/doc-guide/index.rst b/Documentation/translations/zh_CN/doc-guide/index.rst
> > index 78c2e9a1697f..0ac1fc9315ea 100644
> > --- a/Documentation/translations/zh_CN/doc-guide/index.rst
> > +++ b/Documentation/translations/zh_CN/doc-guide/index.rst
> > @@ -18,6 +18,7 @@
> >     parse-headers
> >     contributing
> >     maintainer-profile
> > +   checktransupdate
> >
> >  .. only::  subproject and html
>
> --
> Jani Nikula, Intel
>