Date: Sat, 15 Jun 2024 16:24:27 +0800
From: Dongliang Mu <dzm91@...t.edu.cn>
To: si.yanteng@...ux.dev, Jonathan Corbet <corbet@....net>,
 Alex Shi <alexs@...nel.org>, Yanteng Si <siyanteng@...ngson.cn>
Cc: linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH v2 2/2] doc-guide: add help documentation
 checktransupdate.rst


On 2024/6/15 15:57, si.yanteng@...ux.dev wrote:
> 2024年6月15日 11:53, "Dongliang Mu" <dzm91@...t.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@...t.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@...t.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
>>

Powered by blists - more mailing lists