Em Thu, 4 Jan 2024 17:09:45 +0100
Vegard Nossum <vegard.nossum@xxxxxxxxxx> escreveu:
> This file is basically ReST syntax already -- with just a few tweaks we
> can include this in the rendered HTML documentation which currently has
> no introduction or explanation.
>
> References to this document were found and fixed with some variant of:
>
> git grep -Pl 'ABI/README(?!\.rst)' | xargs sed -i 's|\(Documentation/ABI/README\)|\1\.rst|g'
>
> plus manual inspection and reflows where necessary.
>
> Cc: Greg Kroah-Hartman <gregkh@xxxxxxxxxxxxxxxxxxx>
> Cc: Mauro Carvalho Chehab <mchehab@xxxxxxxxxx>
> Signed-off-by: Vegard Nossum <vegard.nossum@xxxxxxxxxx>
> ---
> Documentation/ABI/{README => README.rst} | 36 +++++++++----------
> Documentation/Kconfig | 8 ++---
> Documentation/filesystems/sysfs.rst | 4 +--
> Documentation/process/4.Coding.rst | 4 +--
> Documentation/process/submit-checklist.rst | 2 +-
> .../translations/it_IT/process/4.Coding.rst | 4 +--
> .../it_IT/process/submit-checklist.rst | 2 +-
> .../translations/ja_JP/SubmitChecklist | 2 +-
> .../sp_SP/process/submit-checklist.rst | 2 +-
> .../translations/zh_CN/filesystems/sysfs.txt | 2 +-
> .../translations/zh_CN/process/4.Coding.rst | 2 +-
> .../zh_CN/process/submit-checklist.rst | 2 +-
> .../translations/zh_TW/filesystems/sysfs.txt | 2 +-
> .../translations/zh_TW/process/4.Coding.rst | 2 +-
> .../zh_TW/process/submit-checklist.rst | 2 +-
> 15 files changed, 38 insertions(+), 38 deletions(-)
> rename Documentation/ABI/{README => README.rst} (82%)
>
> diff --git a/Documentation/ABI/README b/Documentation/ABI/README.rst
> similarity index 82%
> rename from Documentation/ABI/README
> rename to Documentation/ABI/README.rst
> index 8bac9cb09a6d..04f5d05d6caa 100644
> --- a/Documentation/ABI/README
> +++ b/Documentation/ABI/README.rst
> @@ -41,24 +41,24 @@ The different levels of stability are:
> This directory contains a list of the old interfaces that have
> been removed from the kernel.
>
> -Every file in these directories will contain the following information:
> -
> -What: Short description of the interface
> -Date: Date created
> -KernelVersion: Kernel version this feature first showed up in.
> -Contact: Primary contact for this interface (may be a mailing list)
> -Description: Long description of the interface and how to use it.
> -Users: All users of this interface who wish to be notified when
> - it changes. This is very important for interfaces in
> - the "testing" stage, so that kernel developers can work
> - with userspace developers to ensure that things do not
> - break in ways that are unacceptable. It is also
> - important to get feedback for these interfaces to make
> - sure they are working in a proper way and do not need to
> - be changed further.
> -
> -
> -Note:
> +Every file in these directories will contain the following information::
> +
> + What: Short description of the interface
> + Date: Date created
> + KernelVersion: Kernel version this feature first showed up in.
> + Contact: Primary contact for this interface (may be a mailing list)
> + Description: Long description of the interface and how to use it.
> + Users: All users of this interface who wish to be notified when
> + it changes. This is very important for interfaces in
> + the "testing" stage, so that kernel developers can work
> + with userspace developers to ensure that things do not
> + break in ways that are unacceptable. It is also
> + important to get feedback for these interfaces to make
> + sure they are working in a proper way and do not need to
> + be changed further.
My personal preference would be to use:
:What:
as this produces a better markup.
> +
> +.. note::
> +
> The fields should be use a simple notation, compatible with ReST markup.
> Also, the file **should not** have a top-level index, like::
>
> diff --git a/Documentation/Kconfig b/Documentation/Kconfig
> index 3a0e7ac0c4e3..8e690a4f1a64 100644
> --- a/Documentation/Kconfig
> +++ b/Documentation/Kconfig
> @@ -16,10 +16,10 @@ config WARN_ABI_ERRORS
> bool "Warn if there are errors at ABI files"
> help
> The files under Documentation/ABI should follow what's
> - described at Documentation/ABI/README. Yet, as they're manually
> - written, it would be possible that some of those files would
> - have errors that would break them for being parsed by
> - scripts/get_abi.pl. Add a check to verify them.
> + described at Documentation/ABI/README.rst. Yet, as they're
> + manually written, it would be possible that some of those
> + files would have errors that would break them for being parsed
> + by scripts/get_abi.pl. Add a check to verify them.
>
> If unsure, select 'N'.
>
> diff --git a/Documentation/filesystems/sysfs.rst b/Documentation/filesystems/sysfs.rst
> index c32993bc83c7..e30694706b15 100644
> --- a/Documentation/filesystems/sysfs.rst
> +++ b/Documentation/filesystems/sysfs.rst
> @@ -418,5 +418,5 @@ Documentation
> The sysfs directory structure and the attributes in each directory define an
> ABI between the kernel and user space. As for any ABI, it is important that
> this ABI is stable and properly documented. All new sysfs attributes must be
> -documented in Documentation/ABI. See also Documentation/ABI/README for more
> -information.
> +documented in Documentation/ABI. See also Documentation/ABI/README.rst for
> +more information.
> diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst
> index 1f0d81f44e14..120d126ee288 100644
> --- a/Documentation/process/4.Coding.rst
> +++ b/Documentation/process/4.Coding.rst
> @@ -347,8 +347,8 @@ information.
> Any code which adds a new user-space interface - including new sysfs or
> /proc files - should include documentation of that interface which enables
> user-space developers to know what they are working with. See
> -Documentation/ABI/README for a description of how this documentation should
> -be formatted and what information needs to be provided.
> +Documentation/ABI/README.rst for a description of how this documentation
> +should be formatted and what information needs to be provided.
>
> The file :ref:`Documentation/admin-guide/kernel-parameters.rst
> <kernelparameters>` describes all of the kernel's boot-time parameters.
> diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst
> index b1bc2d37bd0a..7e6198ab368d 100644
> --- a/Documentation/process/submit-checklist.rst
> +++ b/Documentation/process/submit-checklist.rst
> @@ -85,7 +85,7 @@ and elsewhere regarding submitting Linux kernel patches.
> 17) All new module parameters are documented with ``MODULE_PARM_DESC()``
>
> 18) All new userspace interfaces are documented in ``Documentation/ABI/``.
> - See ``Documentation/ABI/README`` for more information.
> + See ``Documentation/ABI/README.rst`` for more information.
If you're willing to convert to ReST, please remove ``, as this will
let automarkup.py to create cross-reference links. Same note for the
translations too.
> Patches that change userspace interfaces should be CCed to
> linux-api@xxxxxxxxxxxxxxx.
>
> diff --git a/Documentation/translations/it_IT/process/4.Coding.rst b/Documentation/translations/it_IT/process/4.Coding.rst
> index 54fd255b77d0..631d56ae56dc 100644
> --- a/Documentation/translations/it_IT/process/4.Coding.rst
> +++ b/Documentation/translations/it_IT/process/4.Coding.rst
> @@ -365,8 +365,8 @@ informazione.
> Qualsiasi codice che aggiunge una nuova interfaccia in spazio utente - inclusi
> nuovi file in sysfs o /proc - dovrebbe includere la documentazione di tale
> interfaccia così da permette agli sviluppatori dello spazio utente di sapere
> -con cosa stanno lavorando. Consultate: Documentation/ABI/README per avere una
> -descrizione di come questi documenti devono essere impostati e quali
> +con cosa stanno lavorando. Consultate: Documentation/ABI/README.rst per avere
> +una descrizione di come questi documenti devono essere impostati e quali
> informazioni devono essere fornite.
>
> Il file :ref:`Documentation/translations/it_IT/admin-guide/kernel-parameters.rst <kernelparameters>`
> diff --git a/Documentation/translations/it_IT/process/submit-checklist.rst b/Documentation/translations/it_IT/process/submit-checklist.rst
> index 2fc09cc1f0be..828c8f27d492 100644
> --- a/Documentation/translations/it_IT/process/submit-checklist.rst
> +++ b/Documentation/translations/it_IT/process/submit-checklist.rst
> @@ -94,7 +94,7 @@ sottomissione delle patch, in particolare
> 18) Tutti i nuovi parametri dei moduli sono documentati con ``MODULE_PARM_DESC()``.
>
> 19) Tutte le nuove interfacce verso lo spazio utente sono documentate in
> - ``Documentation/ABI/``. Leggete ``Documentation/ABI/README`` per maggiori
> + ``Documentation/ABI/``. Leggete ``Documentation/ABI/README.rst`` per maggiori
> informazioni. Le patch che modificano le interfacce utente dovrebbero
> essere inviate in copia anche a linux-api@xxxxxxxxxxxxxxx.
>
> diff --git a/Documentation/translations/ja_JP/SubmitChecklist b/Documentation/translations/ja_JP/SubmitChecklist
> index 4429447b0965..87867c47bffd 100644
> --- a/Documentation/translations/ja_JP/SubmitChecklist
> +++ b/Documentation/translations/ja_JP/SubmitChecklist
> @@ -86,7 +86,7 @@ Linux カーネルパッチ投稿者向けチェックリスト
> 利用して必ずその説明を記述してください。
>
> 18: 新しいuserspaceインタフェースを作成した場合には、Documentation/ABI/ に
> - Documentation/ABI/README を参考にして必ずドキュメントを追加してください。
> + Documentation/ABI/README.rst を参考にして必ずドキュメントを追加してください。
>
> 19: 少なくともslabアロケーションとpageアロケーションに失敗した場合の
> 挙動について、fault-injectionを利用して確認してください。
> diff --git a/Documentation/translations/sp_SP/process/submit-checklist.rst b/Documentation/translations/sp_SP/process/submit-checklist.rst
> index 0d6651f9d871..b8072be18532 100644
> --- a/Documentation/translations/sp_SP/process/submit-checklist.rst
> +++ b/Documentation/translations/sp_SP/process/submit-checklist.rst
> @@ -97,7 +97,7 @@ y en otros lugares con respecto al envío de parches del kernel de Linux.
> ``MODULE_PARM_DESC()``.
>
> 18) Todas las nuevas interfaces de espacio de usuario están documentadas
> - en ``Documentation/ABI/``. Consulte ``Documentation/ABI/README`` para
> + en ``Documentation/ABI/``. Consulte ``Documentation/ABI/README.rst`` para
> obtener más información. Los parches que cambian las interfaces del
> espacio de usuario deben ser CCed a linux-api@xxxxxxxxxxxxxxx.
>
> diff --git a/Documentation/translations/zh_CN/filesystems/sysfs.txt b/Documentation/translations/zh_CN/filesystems/sysfs.txt
> index 547062759e60..871fc60aeeca 100644
> --- a/Documentation/translations/zh_CN/filesystems/sysfs.txt
> +++ b/Documentation/translations/zh_CN/filesystems/sysfs.txt
> @@ -370,4 +370,4 @@ void driver_remove_file(struct device_driver *, const struct driver_attribute *)
>
> sysfs 目录结构以及其中包含的属性定义了一个内核与用户空间之间的 ABI。
> 对于任何 ABI，其自身的稳定和适当的文档是非常重要的。所有新的 sysfs
> -属性必须在 Documentation/ABI 中有文档。详见 Documentation/ABI/README。
> +属性必须在 Documentation/ABI 中有文档。详见 Documentation/ABI/README.rst。
> diff --git a/Documentation/translations/zh_CN/process/4.Coding.rst b/Documentation/translations/zh_CN/process/4.Coding.rst
> index 7cac9424f5d5..1b752b3bdc8c 100644
> --- a/Documentation/translations/zh_CN/process/4.Coding.rst
> +++ b/Documentation/translations/zh_CN/process/4.Coding.rst
> @@ -244,7 +244,7 @@ scripts/coccinelle目录下已经打包了相当多的内核“语义补丁”
>
> 任何添加新用户空间接口的代码——包括新的sysfs或/proc文件——都应该包含该接口
> 的文档，该文档使用户空间开发人员能够知道他们在使用什么。请参阅
> -Documentation/ABI/README，了解如何此文档格式以及需要提供哪些信息。
> +Documentation/ABI/README.rst，了解如何此文档格式以及需要提供哪些信息。
>
> 文档 :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>`
> 描述了内核的所有引导时间参数。任何添加新参数的补丁都应该向该文档添加适当的
> diff --git a/Documentation/translations/zh_CN/process/submit-checklist.rst b/Documentation/translations/zh_CN/process/submit-checklist.rst
> index 3d6ee21c74ae..0942021202a3 100644
> --- a/Documentation/translations/zh_CN/process/submit-checklist.rst
> +++ b/Documentation/translations/zh_CN/process/submit-checklist.rst
> @@ -83,7 +83,7 @@ Linux内核补丁提交检查单
> 17) 所有新的模块参数都记录在 ``MODULE_PARM_DESC()``
>
> 18) 所有新的用户空间接口都记录在 ``Documentation/ABI/`` 中。有关详细信息，
> - 请参阅 ``Documentation/ABI/README`` 。更改用户空间接口的补丁应该抄送
> + 请参阅 ``Documentation/ABI/README.rst`` 。更改用户空间接口的补丁应该抄送
> linux-api@xxxxxxxxxxxxxxx。
>
> 19) 已通过至少注入slab和page分配失败进行检查。请参阅 ``Documentation/fault-injection/`` 。
> diff --git a/Documentation/translations/zh_TW/filesystems/sysfs.txt b/Documentation/translations/zh_TW/filesystems/sysfs.txt
> index 978462d5fe14..a94e83dcb814 100644
> --- a/Documentation/translations/zh_TW/filesystems/sysfs.txt
> +++ b/Documentation/translations/zh_TW/filesystems/sysfs.txt
> @@ -373,5 +373,5 @@ void driver_remove_file(struct device_driver *, const struct driver_attribute *)
>
> sysfs 目錄結構以及其中包含的屬性定義了一個內核與用戶空間之間的 ABI。
> 對於任何 ABI，其自身的穩定和適當的文檔是非常重要的。所有新的 sysfs
> -屬性必須在 Documentation/ABI 中有文檔。詳見 Documentation/ABI/README。
> +屬性必須在 Documentation/ABI 中有文檔。詳見 Documentation/ABI/README.rst。
>
> diff --git a/Documentation/translations/zh_TW/process/4.Coding.rst b/Documentation/translations/zh_TW/process/4.Coding.rst
> index bdd2abe4daf4..541e09ae1440 100644
> --- a/Documentation/translations/zh_TW/process/4.Coding.rst
> +++ b/Documentation/translations/zh_TW/process/4.Coding.rst
> @@ -247,7 +247,7 @@ scripts/coccinelle目錄下已經打包了相當多的內核“語義補丁”
>
> 任何添加新用戶空間接口的代碼——包括新的sysfs或/proc文件——都應該包含該接口
> 的文檔，該文檔使用戶空間開發人員能夠知道他們在使用什麼。請參閱
> -Documentation/ABI/README，瞭解如何此文檔格式以及需要提供哪些信息。
> +Documentation/ABI/README.rst，瞭解如何此文檔格式以及需要提供哪些信息。
>
> 文檔 :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>`
> 描述了內核的所有引導時間參數。任何添加新參數的補丁都應該向該文檔添加適當的
> diff --git a/Documentation/translations/zh_TW/process/submit-checklist.rst b/Documentation/translations/zh_TW/process/submit-checklist.rst
> index e57ef0f99e0c..efece58cb5b2 100644
> --- a/Documentation/translations/zh_TW/process/submit-checklist.rst
> +++ b/Documentation/translations/zh_TW/process/submit-checklist.rst
> @@ -86,7 +86,7 @@ Linux內核補丁提交檢查單
> 17) 所有新的模塊參數都記錄在 ``MODULE_PARM_DESC()``
>
> 18) 所有新的用戶空間接口都記錄在 ``Documentation/ABI/`` 中。有關詳細信息，
> - 請參閱 ``Documentation/ABI/README`` 。更改用戶空間接口的補丁應該抄送
> + 請參閱 ``Documentation/ABI/README.rst`` 。更改用戶空間接口的補丁應該抄送
> linux-api@xxxxxxxxxxxxxxx。
>
> 19) 已通過至少注入slab和page分配失敗進行檢查。請參閱 ``Documentation/fault-injection/`` 。
Thanks,
Mauro
