lists.openwall.net   lists  /  announce  owl-users  owl-dev  john-users  john-dev  passwdqc-users  yescrypt  popa3d-users  /  oss-security  kernel-hardening  musl  sabotage  tlsify  passwords  /  crypt-dev  xvendor  /  Bugtraq  Full-Disclosure  linux-kernel  linux-netdev  linux-ext4  linux-hardening  linux-cve-announce  PHC 
Open Source and information security mailing list archives
 
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [day] [month] [year] [list] 
Message-ID: <298d3a9c-41c1-4cbd-b4ab-d3009df9388c@gmail.com>
Date: Mon, 1 Dec 2025 12:11:18 +0900
From: Akira Yokosawa <akiyks@...il.com>
To: Akiyoshi Kurita <weibu@...admin.org>
Cc: shibata@...uxfoundation.org, linux-doc@...r.kernel.org,
 linux-kernel@...r.kernel.org, corbet@....net,
 Akira Yokosawa <akiyks@...il.com>
Subject: Re: [PATCH v2] docs: ja_JP: Move submitting-patches to process/ and
 add to build

Hi,

Sorry for being late.

On Tue, 25 Nov 2025 11:33:36 +0900, Akiyoshi Kurita wrote:
> As requested by Jonathan Corbet, move the Japanese translation of
> 'SubmittingPatches' to its proper location under 'process/' and
> convert it to reStructuredText.
> 

My interpretation of Jon's request is to make the translation up-to-date
as well as to convert it into reST.

Having mostly out-of-date docs as reST would be more confusing for
devs who happens to seek the guide in Japanese.

So I take this v2 as a RFC.

First of all, this patch introduces new warnings from Sphinx as follows:

  .../Documentation/translations/ja_JP/process/submitting-patches.rst:116: ERROR: Unexpected indentation. [docutils]
  .../Documentation/translations/ja_JP/process/submitting-patches.rst:275: ERROR: Unexpected indentation. [docutils]
  .../Documentation/translations/ja_JP/process/submitting-patches.rst:276: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
  .../linux/Documentation/translations/ja_JP/disclaimer-ja_JP.rst:7: WARNING: duplicate label translations_ja_jp_disclaimer, other instance in .../Documentation/translations/ja_JP/disclaimer-ja_JP.rst

Please make sure that your every patch doesn't produce new warnings
in "make htmldocs".  This is the minimal requirement.

Furthermore, looking at the resulting HTML page, I see quite a few other
issues due to lacks of proper uses of reST construct.

> This patch also wires the new file into the Japanese documentation's
> toctree, allowing it to be included in the Sphinx build.

My suggestion is to keep existing SubmittingPatchs intact for the
time being, and translate the English submmitting-patches.rst as of
v6.18 into ja_JP/process/ from scratch.

The translation can be done incrementally in a series consisting of dozen
of patches, each of which takes care of, say, 50 lines or so.

> 
> Signed-off-by: Akiyoshi Kurita <weibu@...admin.org>
> ---
> v2:
>  - Move the entry in index.rst below 'howto' (Akira Yokosawa)
>  - Update the document title to match the current English version (Akira Yokosawa)
>  - Remove legacy header and translation history (Akira Yokosawa)
>  - Add link to the disclaimer (Akira Yokosawa)
>  - Fix RST syntax errors (code blocks, underlines)
> 
>  Documentation/translations/ja_JP/index.rst    |  1 +
>  .../submitting-patches.rst}                   | 82 +++++++------------
>  2 files changed, 30 insertions(+), 53 deletions(-)
>  rename Documentation/translations/ja_JP/{SubmittingPatches => process/submitting-patches.rst} (94%)
> 
> diff --git a/Documentation/translations/ja_JP/index.rst b/Documentation/translations/ja_JP/index.rst
> index 4159b417bfdd..5d47d588e368 100644
> --- a/Documentation/translations/ja_JP/index.rst
> +++ b/Documentation/translations/ja_JP/index.rst
> @@ -13,6 +13,7 @@
>  
>     disclaimer-ja_JP
>     process/howto
> +   process/submitting-patches
>     process/submit-checklist
>  
>  .. raw:: latex
> diff --git a/Documentation/translations/ja_JP/SubmittingPatches b/Documentation/translations/ja_JP/process/submitting-patches.rst
> similarity index 94%
> rename from Documentation/translations/ja_JP/SubmittingPatches
> rename to Documentation/translations/ja_JP/process/submitting-patches.rst
> index 5334db471744..c6402fc52145 100644
> --- a/Documentation/translations/ja_JP/SubmittingPatches
> +++ b/Documentation/translations/ja_JP/process/submitting-patches.rst
> @@ -1,33 +1,10 @@
> -NOTE:
> -This is a version of Documentation/process/submitting-patches.rst into Japanese.
> -This document is maintained by Keiichi KII <k-keiichi@...jp.nec.com>
> -and the JF Project team <http://www.linux.or.jp/JF/>.
> -If you find any difference between this document and the original file
> -or a problem with the translation,
> -please contact the maintainer of this file or JF project.
> +.. include:: ../disclaimer-ja_JP.rst

This direct include is the cause of above mentioned warning:

  .../linux/Documentation/translations/ja_JP/disclaimer-ja_JP.rst:7: WARNING: duplicate label translations_ja_jp_disclaimer, other instance in .../Documentation/translations/ja_JP/disclaimer-ja_JP.rst

>  
> -Please also note that the purpose of this file is to be easier to read
> -for non English (read: Japanese) speakers and is not intended as a
> -fork. So if you have any comments or updates of this file, please try
> -to update the original English file first.
> +:Original: :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`

As I requested earlier [1], please follow the way done in
ja_JP/process/submit-checklist.rst, where the reference to original docs
is placed in ".. note:: 【訳註】" under the documentation title along with
the references to disclaimer.

[1]: https://lore.kernel.org/67d1cfd2-a3e3-4a3f-89f5-38e822321578@gmail.com/

This way, it is more clear in the PDF output that the note belongs to
each of translation docs.  You see, there is no concept of individual
web page in PDF.

Also as mentioned earlier, a fat warning saying that the reST doc is
"under construction" would help preventing confusions.  Something like so:

  .. attention:: UNDER CONSTRUCTION!!
     この文書は翻訳更新の作業中です。最新の内容は原文を参照してください。

>  
> -Last Updated: 2011/06/09
> -
> -==================================
> -これは、
> -linux-2.6.39/Documentation/process/submitting-patches.rst の和訳
> -です。
> -翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
> -翻訳日： 2011/06/09
> -翻訳者： Keiichi Kii <k-keiichi at bx dot jp dot nec dot com>
> -校正者： Masanari Kobayashi さん <zap03216 at nifty dot ne dot jp>
> -         Matsukura さん <nbh--mats at nifty dot com>
> -         Takeshi Hamasaki さん <hmatrjp at users dot sourceforge dot jp>
> -==================================
> -
> -        Linux カーネルに変更を加えるための Howto
> -        又は
> -        かの Linus Torvalds の取り扱い説明書
> +======================================================
> +パッチの投稿: カーネルにコードを入れるための必須ガイド
> +======================================================
>  
>  Linux カーネルに変更を加えたいと思っている個人又は会社にとって、パッ
>  チの投稿に関連した仕組みに慣れていなければ、その過程は時々みなさんを
> @@ -37,12 +14,11 @@ Linux カーネルに変更を加えたいと思っている個人又は会社
>  コードを投稿する前に、Documentation/process/submit-checklist.rst の項目リストに目
>  を通してチェックしてください。
>  
> ---------------------------------------------
>  セクション1 パッチの作り方と送り方
> ---------------------------------------------
> +==================================
>  
>  1) 「 diff -up 」
> -------------
> +-----------------

This section as a whole is of no use today.  You don't see any mention of
"diff" as a CLI command in the original.  I think you can redact those
unhelpful sections and put notes saying:

  .. note:: 【訳註】
     翻訳作業中

, and add new translation in a follow-up patch in the next step.

>  
>  パッチの作成には「 diff -up 」又は「 diff -uprN 」を使ってください。
>  
> @@ -55,7 +31,7 @@ Linux カーネルに対する全ての変更は diff(1) コマンドによる
>  ディレクトリを基準にしないといけません。
>  
>  1個のファイルについてのパッチを作成するためには、ほとんどの場合、
> -以下の作業を行えば十分です。
> +以下の作業を行えば十分です。::
>  
>  	SRCTREE=linux-2.6
>  	MYFILE=drivers/net/mydriver.c
> @@ -68,7 +44,7 @@ Linux カーネルに対する全ての変更は diff(1) コマンドによる
>  
>  複数のファイルについてのパッチを作成するためには、素の( vanilla )、す
>  なわち変更を加えてない Linux カーネルを展開し、自分の Linux カーネル
> -ソースとの差分を生成しないといけません。例えば、
> +ソースとの差分を生成しないといけません。例えば、::
>  
>  	MYSRC=/devel/linux-2.6
>  
> @@ -125,7 +101,7 @@ http://savannah.nongnu.org/projects/quilt
>  特定のコミットを参照したい場合は、その SHA-1 ID だけでなく、一行サマリ
>  も含めてください。それにより、それが何に関するコミットなのかがレビューする
>  人にわかりやすくなります。
> -例 (英文のママ):
> +例 (英文のママ)::
>  
>         Commit e21d2170f36602ae2708 ("video: remove unnecessary
>         platform_set_drvdata()") removed the unnecessary
> @@ -601,9 +577,8 @@ diffstat の結果を生成するために「 git diff -M --stat --summary 」
>  異なってきます。git は大規模な変更(追加と削除のペア)をファイル名の変更と
>  判断するためです。
>  
> -------------------------------------
>  セクション2 - ヒントとTIPSと小技
> -------------------------------------
> +================================
>  
>  このセクションは Linux カーネルに変更を適用することに関係のある一般的な
>  「お約束」の多くを載せています。物事には例外というものがあります。しか
> @@ -645,7 +620,7 @@ ifdef が散乱したコードは、読むのもメンテナンスするのも
>  てください。後はコンパイラが、何もしない箇所を最適化して取り去ってくれるで
>  しょう。
>  
> -まずいコードの簡単な例
> +まずいコードの簡単な例::
>  
>  	dev = alloc_etherdev (sizeof(struct funky_private));
>  	if (!dev)
> @@ -656,12 +631,14 @@ ifdef が散乱したコードは、読むのもメンテナンスするのも
>  
>  クリーンアップしたコードの例
>  
> -(in header)
> +(in header)::
> +
>  	#ifndef CONFIG_NET_FUNKINESS
>  	static inline void init_funky_net (struct net_device *d) {}
>  	#endif
>  
> -(in the code itself)
> +(in the code itself)::
> +
>  	dev = alloc_etherdev (sizeof(struct funky_private));
>  	if (!dev)
>  		return -ENODEV;
> @@ -686,35 +663,34 @@ gcc においては、マクロと同じくらい軽いです。
>  をしないでください。「できる限り簡単に、そして、それ以上簡単になら
>  ないような設計をしてください。」
>  
> -----------------------
>  セクション3 参考文献
> -----------------------
> +====================
>  
>  Andrew Morton, "The perfect patch" (tpp).
> -  <http://www.ozlabs.org/~akpm/stuff/tpp.txt>
> +<http://www.ozlabs.org/~akpm/stuff/tpp.txt>

This part comes from the original.
If you need to change this, it means you also need to change the original.
Is this the case?

>  
>  Jeff Garzik, "Linux kernel patch submission format".
> -  <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>
> +<https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>

Ditto.

>  
>  Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
> -  <http://www.kroah.com/log/linux/maintainer.html>
> -  <http://www.kroah.com/log/linux/maintainer-02.html>
> -  <http://www.kroah.com/log/linux/maintainer-03.html>
> -  <http://www.kroah.com/log/linux/maintainer-04.html>
> -  <http://www.kroah.com/log/linux/maintainer-05.html>
> +<http://www.kroah.com/log/linux/maintainer.html>
> +<http://www.kroah.com/log/linux/maintainer-02.html>
> +<http://www.kroah.com/log/linux/maintainer-03.html>
> +<http://www.kroah.com/log/linux/maintainer-04.html>
> +<http://www.kroah.com/log/linux/maintainer-05.html>
>  
>  NO!!!! No more huge patch bombs to linux-kernel@...r.kernel.org people!
> -  <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net>
> +<https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net>
>  
>  Kernel Documentation/process/coding-style.rst:
> -  <http://users.sosdg.org/~qiyong/lxr/source/Documentation/process/coding-style.rst>
> +<http://users.sosdg.org/~qiyong/lxr/source/Documentation/process/coding-style.rst>
>  
>  Linus Torvalds's mail on the canonical patch format:
> -  <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org>
> +<https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org>
>  
>  Andi Kleen, "On submitting kernel patches"
> -  Some strategies to get difficult or controversial changes in.
> -  http://halobates.de/on-submitting-patches.pdf
> +Some strategies to get difficult or controversial changes in.
> +http://halobates.de/on-submitting-patches.pdf
>  
>  --
>  

There is no use of stray "--" in the end.

Again, please pay attention to the resulting HTML (and hopefully, PDF)
rendering.

Thanks, Akira

Powered by blists - more mailing lists

Powered by Openwall GNU/*/Linux Powered by OpenVZ