* [PATCH 1/5] docs: move admin-guide/sysfs-rules.rst to userspace-api/
@ 2024-01-04 16:09 Vegard Nossum
2024-01-04 16:09 ` [PATCH 2/5] docs: move admin-guide/abi*.rst " Vegard Nossum
` (4 more replies)
0 siblings, 5 replies; 9+ messages in thread
From: Vegard Nossum @ 2024-01-04 16:09 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Randy Dunlap, Mauro Carvalho Chehab, Greg Kroah-Hartman,
Jani Nikula, linux-doc, linux-api, Vegard Nossum
This file documents how userspace ought to interact with sysfs. It is
clearly intended for applications that access sysfs programmatically,
rather than at users or admins.
Move it to the userspace API guide.
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
---
Documentation/ABI/stable/sysfs-devices | 2 +-
Documentation/admin-guide/index.rst | 9 ---------
Documentation/userspace-api/index.rst | 10 +++++++++-
.../{admin-guide => userspace-api}/sysfs-rules.rst | 0
tools/lib/api/fs/fs.c | 2 +-
5 files changed, 11 insertions(+), 12 deletions(-)
rename Documentation/{admin-guide => userspace-api}/sysfs-rules.rst (100%)
diff --git a/Documentation/ABI/stable/sysfs-devices b/Documentation/ABI/stable/sysfs-devices
index 98a8ef99ac5f..7829414cba62 100644
--- a/Documentation/ABI/stable/sysfs-devices
+++ b/Documentation/ABI/stable/sysfs-devices
@@ -1,6 +1,6 @@
Note:
This documents additional properties of any device beyond what
- is documented in Documentation/admin-guide/sysfs-rules.rst
+ is documented in Documentation/userspace-api/sysfs-rules.rst
What: /sys/devices/*/of_node
Date: February 2015
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 43ea35613dfc..c2b032314a24 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -47,15 +47,6 @@ problems and bugs in particular.
perf/index
pstore-blk
-This is the beginning of a section with information of interest to
-application developers. Documents covering various aspects of the kernel
-ABI will be found here.
-
-.. toctree::
- :maxdepth: 1
-
- sysfs-rules
-
This is the beginning of a section with information of interest to
application developers and system integrators doing analysis of the
Linux kernel for safety critical applications. Documents supporting
diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst
index 74bc0716432e..6ce2edf519f6 100644
--- a/Documentation/userspace-api/index.rst
+++ b/Documentation/userspace-api/index.rst
@@ -9,8 +9,16 @@ While much of the kernel's user-space API is documented elsewhere
also be found in the kernel tree itself. This manual is intended to be the
place where this information is gathered.
+General documentation:
+
+.. toctree::
+ :maxdepth: 1
+
+ sysfs-rules
+
+Subsystem-specific documentation:
+
.. toctree::
- :caption: Table of contents
:maxdepth: 2
no_new_privs
diff --git a/Documentation/admin-guide/sysfs-rules.rst b/Documentation/userspace-api/sysfs-rules.rst
similarity index 100%
rename from Documentation/admin-guide/sysfs-rules.rst
rename to Documentation/userspace-api/sysfs-rules.rst
diff --git a/tools/lib/api/fs/fs.c b/tools/lib/api/fs/fs.c
index 5cb0eeec2c8a..c35247b6ad81 100644
--- a/tools/lib/api/fs/fs.c
+++ b/tools/lib/api/fs/fs.c
@@ -214,7 +214,7 @@ static void mem_toupper(char *f, size_t len)
/*
* Check for "NAME_PATH" environment variable to override fs location (for
- * testing). This matches the recommendation in Documentation/admin-guide/sysfs-rules.rst
+ * testing). This matches the recommendation in Documentation/userspace-api/sysfs-rules.rst
* for SYSFS_PATH.
*/
static bool fs__env_override(struct fs *fs)
--
2.34.1
^ permalink raw reply related [flat|nested] 9+ messages in thread* [PATCH 2/5] docs: move admin-guide/abi*.rst to userspace-api/ 2024-01-04 16:09 [PATCH 1/5] docs: move admin-guide/sysfs-rules.rst to userspace-api/ Vegard Nossum @ 2024-01-04 16:09 ` Vegard Nossum 2024-01-04 16:09 ` [PATCH 3/5] docs: userspace-api: use single toctree level Vegard Nossum ` (3 subsequent siblings) 4 siblings, 0 replies; 9+ messages in thread From: Vegard Nossum @ 2024-01-04 16:09 UTC (permalink / raw) To: Jonathan Corbet Cc: Randy Dunlap, Mauro Carvalho Chehab, Greg Kroah-Hartman, Jani Nikula, linux-doc, linux-api, Vegard Nossum These files describe the kernel <-> userspace ABI and belongs with the userspace API guide. The new text was adapted from Documentation/ABI/README. Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> --- Documentation/admin-guide/index.rst | 1 - .../{admin-guide => userspace-api}/abi-obsolete.rst | 0 .../{admin-guide => userspace-api}/abi-removed.rst | 0 .../{admin-guide => userspace-api}/abi-stable.rst | 0 .../{admin-guide => userspace-api}/abi-testing.rst | 0 Documentation/{admin-guide => userspace-api}/abi.rst | 0 Documentation/userspace-api/index.rst | 8 ++++++++ 7 files changed, 8 insertions(+), 1 deletion(-) rename Documentation/{admin-guide => userspace-api}/abi-obsolete.rst (100%) rename Documentation/{admin-guide => userspace-api}/abi-removed.rst (100%) rename Documentation/{admin-guide => userspace-api}/abi-stable.rst (100%) rename Documentation/{admin-guide => userspace-api}/abi-testing.rst (100%) rename Documentation/{admin-guide => userspace-api}/abi.rst (100%) diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index c2b032314a24..fb055d926f6a 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -18,7 +18,6 @@ etc. devices sysctl/index - abi features This section describes CPU vulnerabilities and their mitigations. diff --git a/Documentation/admin-guide/abi-obsolete.rst b/Documentation/userspace-api/abi-obsolete.rst similarity index 100% rename from Documentation/admin-guide/abi-obsolete.rst rename to Documentation/userspace-api/abi-obsolete.rst diff --git a/Documentation/admin-guide/abi-removed.rst b/Documentation/userspace-api/abi-removed.rst similarity index 100% rename from Documentation/admin-guide/abi-removed.rst rename to Documentation/userspace-api/abi-removed.rst diff --git a/Documentation/admin-guide/abi-stable.rst b/Documentation/userspace-api/abi-stable.rst similarity index 100% rename from Documentation/admin-guide/abi-stable.rst rename to Documentation/userspace-api/abi-stable.rst diff --git a/Documentation/admin-guide/abi-testing.rst b/Documentation/userspace-api/abi-testing.rst similarity index 100% rename from Documentation/admin-guide/abi-testing.rst rename to Documentation/userspace-api/abi-testing.rst diff --git a/Documentation/admin-guide/abi.rst b/Documentation/userspace-api/abi.rst similarity index 100% rename from Documentation/admin-guide/abi.rst rename to Documentation/userspace-api/abi.rst diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst index 6ce2edf519f6..275f70f3bcbe 100644 --- a/Documentation/userspace-api/index.rst +++ b/Documentation/userspace-api/index.rst @@ -42,6 +42,14 @@ Subsystem-specific documentation: isapnp dcdbas +Kernel ABIs: These documents describe the the ABI between the Linux +kernel and userspace, and the relative stability of these interfaces. + +.. toctree:: + :maxdepth: 2 + + abi + .. only:: subproject and html Indices -- 2.34.1 ^ permalink raw reply related [flat|nested] 9+ messages in thread
* [PATCH 3/5] docs: userspace-api: use single toctree level 2024-01-04 16:09 [PATCH 1/5] docs: move admin-guide/sysfs-rules.rst to userspace-api/ Vegard Nossum 2024-01-04 16:09 ` [PATCH 2/5] docs: move admin-guide/abi*.rst " Vegard Nossum @ 2024-01-04 16:09 ` Vegard Nossum 2024-01-04 16:09 ` [PATCH 4/5] Documentation/ABI/README: convert to ReST Vegard Nossum ` (2 subsequent siblings) 4 siblings, 0 replies; 9+ messages in thread From: Vegard Nossum @ 2024-01-04 16:09 UTC (permalink / raw) To: Jonathan Corbet Cc: Randy Dunlap, Mauro Carvalho Chehab, Greg Kroah-Hartman, Jani Nikula, linux-doc, linux-api, Vegard Nossum Having a single toctree level makes this page more readable at a glance. This also makes it more like the other top-level books (process, admin-guide, etc.). We can also consider using proper headings like process/index does, but this is at least a step in the right direction. Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> --- Documentation/userspace-api/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst index 275f70f3bcbe..82f9dbd228f5 100644 --- a/Documentation/userspace-api/index.rst +++ b/Documentation/userspace-api/index.rst @@ -19,7 +19,7 @@ General documentation: Subsystem-specific documentation: .. toctree:: - :maxdepth: 2 + :maxdepth: 1 no_new_privs seccomp_filter -- 2.34.1 ^ permalink raw reply related [flat|nested] 9+ messages in thread
* [PATCH 4/5] Documentation/ABI/README: convert to ReST 2024-01-04 16:09 [PATCH 1/5] docs: move admin-guide/sysfs-rules.rst to userspace-api/ Vegard Nossum 2024-01-04 16:09 ` [PATCH 2/5] docs: move admin-guide/abi*.rst " Vegard Nossum 2024-01-04 16:09 ` [PATCH 3/5] docs: userspace-api: use single toctree level Vegard Nossum @ 2024-01-04 16:09 ` Vegard Nossum 2024-01-05 20:07 ` Mauro Carvalho Chehab 2024-01-04 16:09 ` [PATCH 5/5] docs: userspace-api/api: include ABI/README.rst Vegard Nossum 2024-01-05 20:25 ` [PATCH 1/5] docs: move admin-guide/sysfs-rules.rst to userspace-api/ Mauro Carvalho Chehab 4 siblings, 1 reply; 9+ messages in thread From: Vegard Nossum @ 2024-01-04 16:09 UTC (permalink / raw) To: Jonathan Corbet Cc: Randy Dunlap, Mauro Carvalho Chehab, Greg Kroah-Hartman, Jani Nikula, linux-doc, linux-api, Vegard Nossum 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@linuxfoundation.org> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> --- 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. + +.. 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. Patches that change userspace interfaces should be CCed to linux-api@vger.kernel.org. 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@vger.kernel.org. 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@vger.kernel.org. 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@vger.kernel.org。 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@vger.kernel.org。 19) 已通過至少注入slab和page分配失敗進行檢查。請參閱 ``Documentation/fault-injection/`` 。 -- 2.34.1 ^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [PATCH 4/5] Documentation/ABI/README: convert to ReST 2024-01-04 16:09 ` [PATCH 4/5] Documentation/ABI/README: convert to ReST Vegard Nossum @ 2024-01-05 20:07 ` Mauro Carvalho Chehab 2024-01-08 13:18 ` Vegard Nossum 0 siblings, 1 reply; 9+ messages in thread From: Mauro Carvalho Chehab @ 2024-01-05 20:07 UTC (permalink / raw) To: Vegard Nossum Cc: Jonathan Corbet, Randy Dunlap, Greg Kroah-Hartman, Jani Nikula, linux-doc, linux-api Em Thu, 4 Jan 2024 17:09:45 +0100 Vegard Nossum <vegard.nossum@oracle.com> 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@linuxfoundation.org> > Cc: Mauro Carvalho Chehab <mchehab@kernel.org> > Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> > --- > 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@vger.kernel.org. > > 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@vger.kernel.org. > > 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@vger.kernel.org. > > 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@vger.kernel.org。 > > 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@vger.kernel.org。 > > 19) 已通過至少注入slab和page分配失敗進行檢查。請參閱 ``Documentation/fault-injection/`` 。 Thanks, Mauro ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH 4/5] Documentation/ABI/README: convert to ReST 2024-01-05 20:07 ` Mauro Carvalho Chehab @ 2024-01-08 13:18 ` Vegard Nossum 2024-01-31 5:42 ` Mauro Carvalho Chehab 0 siblings, 1 reply; 9+ messages in thread From: Vegard Nossum @ 2024-01-08 13:18 UTC (permalink / raw) To: Mauro Carvalho Chehab, Jonathan Corbet Cc: Randy Dunlap, Greg Kroah-Hartman, Jani Nikula, linux-doc, linux-api [-- Attachment #1: Type: text/plain, Size: 2569 bytes --] On 05/01/2024 21:07, Mauro Carvalho Chehab wrote: > Em Thu, 4 Jan 2024 17:09:45 +0100 > Vegard Nossum <vegard.nossum@oracle.com> escreveu: >> +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. I would prefer to alter this as little as possible, since it describes the literal format of those ABI files, keeping it readable and understandable in plain text as well as HTML -- with a single leading space this whole block shows up as a code block in the HTML, which I think is appropriate when giving an example of a literal file. >> 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. Good point -- Jon, do you want me to resubmit this or can you fix it up? We could also just run a "treewide" fix for this as a separate patch: git grep -l '``Documentation/.*\.rst``' 'Documentation/**.rst' \ | xargs sed -i 's|``\(Documentation[^`*]*\.rst\)``|\1|g' I've attached the result (with 1 exclusion, see the changelog) as a patch. Thanks, Vegard [-- Attachment #2: 0001-docs-rely-on-automarkup-for-Documentation-.rst-links.patch --] [-- Type: text/x-patch, Size: 31853 bytes --] From 262186f2bc7ca72dbb8b68e282d3e418918fe6d8 Mon Sep 17 00:00:00 2001 From: Vegard Nossum <vegard.nossum@oracle.com> Date: Mon, 8 Jan 2024 14:11:02 +0100 Subject: [PATCH] docs: rely on automarkup for Documentation/**.rst links If we remove ``...`` around Documentation/ links to .rst files in .rst files, then automarkup.py can create cross-reference links and warn about non-existent files. git grep -l '``Documentation/.*\.rst``' 'Documentation/**.rst' \ | xargs sed -i 's|``\(Documentation[^`*]*\.rst\)``|\1|g' I've excluded one instance in Documentation/doc-guide/sphinx.rst to the top-level Documentation/index.rst file as I believe it makes more sense to keep that as a literal path. Link: https://lore.kernel.org/all/20240105210739.20ae5f05@coco.lan/ Suggested-by: Mauro Carvalho Chehab <mchehab@kernel.org> Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> --- Documentation/admin-guide/mm/numa_memory_policy.rst | 2 +- Documentation/admin-guide/serial-console.rst | 2 +- Documentation/driver-api/dmaengine/client.rst | 2 +- Documentation/driver-api/nvdimm/security.rst | 2 +- Documentation/filesystems/fscrypt.rst | 4 ++-- Documentation/kernel-hacking/hacking.rst | 6 +++--- Documentation/kernel-hacking/locking.rst | 2 +- Documentation/networking/dsa/b53.rst | 2 +- Documentation/networking/dsa/bcm_sf2.rst | 2 +- Documentation/networking/dsa/dsa.rst | 2 +- Documentation/networking/dsa/lan9303.rst | 2 +- Documentation/process/adding-syscalls.rst | 2 +- Documentation/process/submit-checklist.rst | 8 ++++---- Documentation/security/keys/trusted-encrypted.rst | 4 ++-- Documentation/sound/kernel-api/writing-an-alsa-driver.rst | 2 +- Documentation/translations/it_IT/doc-guide/sphinx.rst | 2 +- .../translations/it_IT/kernel-hacking/hacking.rst | 6 +++--- .../translations/it_IT/kernel-hacking/locking.rst | 2 +- .../translations/it_IT/process/adding-syscalls.rst | 2 +- .../translations/it_IT/process/submit-checklist.rst | 8 ++++---- .../translations/sp_SP/process/adding-syscalls.rst | 2 +- .../translations/sp_SP/process/submit-checklist.rst | 8 ++++---- Documentation/translations/zh_CN/doc-guide/sphinx.rst | 2 +- .../translations/zh_CN/process/submit-checklist.rst | 6 +++--- .../translations/zh_TW/process/submit-checklist.rst | 6 +++--- Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst | 2 +- Documentation/userspace-api/media/v4l/diff-v4l.rst | 2 +- Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst | 2 +- Documentation/virt/uml/user_mode_linux_howto_v2.rst | 2 +- 29 files changed, 48 insertions(+), 48 deletions(-) diff --git a/Documentation/admin-guide/mm/numa_memory_policy.rst b/Documentation/admin-guide/mm/numa_memory_policy.rst index eca38fa81e0f..7d43b8042a05 100644 --- a/Documentation/admin-guide/mm/numa_memory_policy.rst +++ b/Documentation/admin-guide/mm/numa_memory_policy.rst @@ -13,7 +13,7 @@ document attempts to describe the concepts and APIs of the 2.6 memory policy support. Memory policies should not be confused with cpusets -(``Documentation/admin-guide/cgroup-v1/cpusets.rst``) +(Documentation/admin-guide/cgroup-v1/cpusets.rst) which is an administrative mechanism for restricting the nodes from which memory may be allocated by a set of processes. Memory policies are a programming interface that a NUMA-aware application can take advantage of. When diff --git a/Documentation/admin-guide/serial-console.rst b/Documentation/admin-guide/serial-console.rst index a3dfc2c66e01..0befd17f66b6 100644 --- a/Documentation/admin-guide/serial-console.rst +++ b/Documentation/admin-guide/serial-console.rst @@ -84,7 +84,7 @@ You will need to create a new device to use ``/dev/console``. The official ``/dev/console`` is now character device 5,1. (You can also use a network device as a console. See -``Documentation/networking/netconsole.rst`` for information on that.) +Documentation/networking/netconsole.rst for information on that.) Here's an example that will use ``/dev/ttyS1`` (COM2) as the console. Replace the sample values as needed. diff --git a/Documentation/driver-api/dmaengine/client.rst b/Documentation/driver-api/dmaengine/client.rst index ecf139f73da4..bf1346792855 100644 --- a/Documentation/driver-api/dmaengine/client.rst +++ b/Documentation/driver-api/dmaengine/client.rst @@ -5,7 +5,7 @@ DMA Engine API Guide Vinod Koul <vinod dot koul at intel.com> .. note:: For DMA Engine usage in async_tx please see: - ``Documentation/crypto/async-tx-api.rst`` + Documentation/crypto/async-tx-api.rst Below is a guide to device driver writers on how to use the Slave-DMA API of the diff --git a/Documentation/driver-api/nvdimm/security.rst b/Documentation/driver-api/nvdimm/security.rst index eb3d35e6a95c..6deb677dea3b 100644 --- a/Documentation/driver-api/nvdimm/security.rst +++ b/Documentation/driver-api/nvdimm/security.rst @@ -51,7 +51,7 @@ all the keys are in the kernel user keyring for unlock. A nvdimm encrypted-key of format enc32 has the description format of: nvdimm:<bus-provider-specific-unique-id> -See file ``Documentation/security/keys/trusted-encrypted.rst`` for creating +See file Documentation/security/keys/trusted-encrypted.rst for creating encrypted-keys of enc32 format. TPM usage with a master trusted key is preferred for sealing the encrypted-keys. diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst index 1b84f818e574..d6a93e47e70c 100644 --- a/Documentation/filesystems/fscrypt.rst +++ b/Documentation/filesystems/fscrypt.rst @@ -874,7 +874,7 @@ as follows: hash of the key. To add this type of key, the calling process does not need any privileges. However, the number of keys that can be added is limited by the user's quota for the keyrings service (see - ``Documentation/security/keys/core.rst``). + Documentation/security/keys/core.rst). - ``raw_size`` must be the size of the ``raw`` key provided, in bytes. Alternatively, if ``key_id`` is nonzero, this field must be 0, since @@ -956,7 +956,7 @@ access encrypted files. Nevertheless, to add a key to one of the process-subscribed keyrings, the add_key() system call can be used (see: -``Documentation/security/keys/core.rst``). The key type must be +Documentation/security/keys/core.rst). The key type must be "logon"; keys of this type are kept in kernel memory and cannot be read back by userspace. The key description must be "fscrypt:" followed by the 16-character lower case hex representation of the diff --git a/Documentation/kernel-hacking/hacking.rst b/Documentation/kernel-hacking/hacking.rst index 1717348a4404..05338ef0912f 100644 --- a/Documentation/kernel-hacking/hacking.rst +++ b/Documentation/kernel-hacking/hacking.rst @@ -736,7 +736,7 @@ make a neat patch, there's administrative work to be done: - Usually you want a configuration option for your kernel hack. Edit ``Kconfig`` in the appropriate directory. The Config language is simple to use by cut and paste, and there's complete documentation in - ``Documentation/kbuild/kconfig-language.rst``. + Documentation/kbuild/kconfig-language.rst. In your description of the option, make sure you address both the expert user and the user who knows nothing about your feature. @@ -746,7 +746,7 @@ make a neat patch, there's administrative work to be done: - Edit the ``Makefile``: the CONFIG variables are exported here so you can usually just add a "obj-$(CONFIG_xxx) += xxx.o" line. The syntax - is documented in ``Documentation/kbuild/makefiles.rst``. + is documented in Documentation/kbuild/makefiles.rst. - Put yourself in ``CREDITS`` if you consider what you've done noteworthy, usually beyond a single file (your name should be at the @@ -755,7 +755,7 @@ make a neat patch, there's administrative work to be done: it implies a more-than-passing commitment to some part of the code. - Finally, don't forget to read - ``Documentation/process/submitting-patches.rst`` + Documentation/process/submitting-patches.rst Kernel Cantrips =============== diff --git a/Documentation/kernel-hacking/locking.rst b/Documentation/kernel-hacking/locking.rst index dff0646a717b..d479c2459895 100644 --- a/Documentation/kernel-hacking/locking.rst +++ b/Documentation/kernel-hacking/locking.rst @@ -1370,7 +1370,7 @@ Futex API reference Further reading =============== -- ``Documentation/locking/spinlocks.rst``: Linus Torvalds' spinlocking +- Documentation/locking/spinlocks.rst: Linus Torvalds' spinlocking tutorial in the kernel sources. - Unix Systems for Modern Architectures: Symmetric Multiprocessing and diff --git a/Documentation/networking/dsa/b53.rst b/Documentation/networking/dsa/b53.rst index 1cb3ff648f88..51fd39ca5201 100644 --- a/Documentation/networking/dsa/b53.rst +++ b/Documentation/networking/dsa/b53.rst @@ -14,7 +14,7 @@ Implementation details ====================== The driver is located in ``drivers/net/dsa/b53/`` and is implemented as a -DSA driver; see ``Documentation/networking/dsa/dsa.rst`` for details on the +DSA driver; see Documentation/networking/dsa/dsa.rst for details on the subsystem and what it provides. The switch is, if possible, configured to enable a Broadcom specific 4-bytes diff --git a/Documentation/networking/dsa/bcm_sf2.rst b/Documentation/networking/dsa/bcm_sf2.rst index d2571435696f..ba7371aad142 100644 --- a/Documentation/networking/dsa/bcm_sf2.rst +++ b/Documentation/networking/dsa/bcm_sf2.rst @@ -39,7 +39,7 @@ Implementation details ====================== The driver is located in ``drivers/net/dsa/bcm_sf2.c`` and is implemented as a DSA -driver; see ``Documentation/networking/dsa/dsa.rst`` for details on the subsystem +driver; see Documentation/networking/dsa/dsa.rst for details on the subsystem and what it provides. The SF2 switch is configured to enable a Broadcom specific 4-bytes switch tag diff --git a/Documentation/networking/dsa/dsa.rst b/Documentation/networking/dsa/dsa.rst index 7b2e69cd7ef0..6e185a08396b 100644 --- a/Documentation/networking/dsa/dsa.rst +++ b/Documentation/networking/dsa/dsa.rst @@ -1110,7 +1110,7 @@ interface with a physical switch port does not produce the expected result). A driver which is able of offloading certain functions of a DANP or DANH should declare the corresponding netdev features as indicated by the documentation at -``Documentation/networking/netdev-features.rst``. Additionally, the following +Documentation/networking/netdev-features.rst. Additionally, the following methods must be implemented: - ``port_hsr_join``: function invoked when a given switch port is added to a diff --git a/Documentation/networking/dsa/lan9303.rst b/Documentation/networking/dsa/lan9303.rst index ab81b4e0139e..97456316a8d9 100644 --- a/Documentation/networking/dsa/lan9303.rst +++ b/Documentation/networking/dsa/lan9303.rst @@ -10,7 +10,7 @@ host conduit network interface (e.g. fixed link). Driver details ============== -The driver is implemented as a DSA driver, see ``Documentation/networking/dsa/dsa.rst``. +The driver is implemented as a DSA driver, see Documentation/networking/dsa/dsa.rst. See ``Documentation/devicetree/bindings/net/dsa/lan9303.txt`` for device tree binding. diff --git a/Documentation/process/adding-syscalls.rst b/Documentation/process/adding-syscalls.rst index 906c47f1a9e5..5e6d26ef31eb 100644 --- a/Documentation/process/adding-syscalls.rst +++ b/Documentation/process/adding-syscalls.rst @@ -33,7 +33,7 @@ interface. to a somewhat opaque API. - If you're just exposing runtime system information, a new node in sysfs - (see ``Documentation/filesystems/sysfs.rst``) or the ``/proc`` filesystem may + (see Documentation/filesystems/sysfs.rst) or the ``/proc`` filesystem may be more appropriate. However, access to these mechanisms requires that the relevant filesystem is mounted, which might not always be the case (e.g. in a namespaced/sandboxed/chrooted environment). Avoid adding any API to diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst index 7e6198ab368d..4c25fa07d1d5 100644 --- a/Documentation/process/submit-checklist.rst +++ b/Documentation/process/submit-checklist.rst @@ -43,7 +43,7 @@ and elsewhere regarding submitting Linux kernel patches. 6) Any new or modified ``CONFIG`` options do not muck up the config menu and default to off unless they meet the exception criteria documented in - ``Documentation/kbuild/kconfig-language.rst`` Menu attributes: default value. + Documentation/kbuild/kconfig-language.rst Menu attributes: default value. 7) All new ``Kconfig`` options have help text. @@ -80,12 +80,12 @@ and elsewhere regarding submitting Linux kernel patches. 15) All new ``/proc`` entries are documented under ``Documentation/`` 16) All new kernel boot parameters are documented in - ``Documentation/admin-guide/kernel-parameters.rst``. + Documentation/admin-guide/kernel-parameters.rst. 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.rst`` for more information. + See Documentation/ABI/README.rst for more information. Patches that change userspace interfaces should be CCed to linux-api@vger.kernel.org. @@ -108,7 +108,7 @@ and elsewhere regarding submitting Linux kernel patches. and why. 23) If any ioctl's are added by the patch, then also update - ``Documentation/userspace-api/ioctl/ioctl-number.rst``. + Documentation/userspace-api/ioctl/ioctl-number.rst. 24) If your modified source code depends on or uses any of the kernel APIs or features that are related to the following ``Kconfig`` symbols, diff --git a/Documentation/security/keys/trusted-encrypted.rst b/Documentation/security/keys/trusted-encrypted.rst index e989b9802f92..7ea1dc3956da 100644 --- a/Documentation/security/keys/trusted-encrypted.rst +++ b/Documentation/security/keys/trusted-encrypted.rst @@ -88,7 +88,7 @@ safe. (2) TEE TEEs have well-documented, standardized client interface and APIs. For - more details refer to ``Documentation/driver-api/tee.rst``. + more details refer to Documentation/driver-api/tee.rst. (3) CAAM @@ -363,7 +363,7 @@ Other uses for trusted and encrypted keys, such as for disk and file encryption are anticipated. In particular the new format 'ecryptfs' has been defined in order to use encrypted keys to mount an eCryptfs filesystem. More details about the usage can be found in the file -``Documentation/security/keys/ecryptfs.rst``. +Documentation/security/keys/ecryptfs.rst. Another new format 'enc32' has been defined in order to support encrypted keys with payload size of 32 bytes. This will initially be used for nvdimm security diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst index cd421856409e..cf64e1c10ce8 100644 --- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst +++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst @@ -2466,7 +2466,7 @@ Mic boost Mic-boost switch is set as “Mic Boost” or “Mic Boost (6dB)”. More precise information can be found in -``Documentation/sound/designs/control-names.rst``. +Documentation/sound/designs/control-names.rst. Access Flags ------------ diff --git a/Documentation/translations/it_IT/doc-guide/sphinx.rst b/Documentation/translations/it_IT/doc-guide/sphinx.rst index 1f513bc33618..f5b2140921a8 100644 --- a/Documentation/translations/it_IT/doc-guide/sphinx.rst +++ b/Documentation/translations/it_IT/doc-guide/sphinx.rst @@ -184,7 +184,7 @@ Aggiungere nuova documentazione è semplice: 1. aggiungete un file ``.rst`` nella sottocartella ``Documentation`` 2. aggiungete un riferimento ad esso nell'indice (`TOC tree`_) in - ``Documentation/index.rst``. + Documentation/index.rst. .. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html diff --git a/Documentation/translations/it_IT/kernel-hacking/hacking.rst b/Documentation/translations/it_IT/kernel-hacking/hacking.rst index dd06bfc1a050..2b8ecc4b2098 100644 --- a/Documentation/translations/it_IT/kernel-hacking/hacking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/hacking.rst @@ -771,7 +771,7 @@ anche per avere patch pulite, c'è del lavoro amministrativo da fare: - Solitamente vorrete un'opzione di configurazione per la vostra modifica al kernel. Modificate ``Kconfig`` nella cartella giusta. Il linguaggio Config è facile con copia ed incolla, e c'è una completa documentazione - nel file ``Documentation/kbuild/kconfig-language.rst``. + nel file Documentation/kbuild/kconfig-language.rst. Nella descrizione della vostra opzione, assicuratevi di parlare sia agli utenti esperti sia agli utente che non sanno nulla del vostro lavoro. @@ -783,7 +783,7 @@ anche per avere patch pulite, c'è del lavoro amministrativo da fare: - Modificate il file ``Makefile``: le variabili CONFIG sono esportate qui, quindi potete solitamente aggiungere una riga come la seguete "obj-$(CONFIG_xxx) += xxx.o". La sintassi è documentata nel file - ``Documentation/kbuild/makefiles.rst``. + Documentation/kbuild/makefiles.rst. - Aggiungete voi stessi in ``CREDITS`` se credete di aver fatto qualcosa di notevole, solitamente qualcosa che supera il singolo file (comunque il vostro @@ -793,7 +793,7 @@ anche per avere patch pulite, c'è del lavoro amministrativo da fare: semplice impegno su una parte del codice. - Infine, non dimenticatevi di leggere - ``Documentation/process/submitting-patches.rst``. + Documentation/process/submitting-patches.rst. Trucchetti del kernel ===================== diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst index 4c21cf60f775..ab0fa1826f95 100644 --- a/Documentation/translations/it_IT/kernel-hacking/locking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst @@ -1409,7 +1409,7 @@ Riferimento per l'API dei Futex Approfondimenti =============== -- ``Documentation/locking/spinlocks.rst``: la guida di Linus Torvalds agli +- Documentation/locking/spinlocks.rst: la guida di Linus Torvalds agli spinlock del kernel. - Unix Systems for Modern Architectures: Symmetric Multiprocessing and diff --git a/Documentation/translations/it_IT/process/adding-syscalls.rst b/Documentation/translations/it_IT/process/adding-syscalls.rst index df8c652d004b..55e511050847 100644 --- a/Documentation/translations/it_IT/process/adding-syscalls.rst +++ b/Documentation/translations/it_IT/process/adding-syscalls.rst @@ -39,7 +39,7 @@ vostra interfaccia. un qualche modo opaca. - Se dovete esporre solo delle informazioni sul sistema, un nuovo nodo in - sysfs (vedere ``Documentation/filesystems/sysfs.rst``) o + sysfs (vedere Documentation/filesystems/sysfs.rst) o in procfs potrebbe essere sufficiente. Tuttavia, l'accesso a questi meccanismi richiede che il filesystem sia montato, il che potrebbe non essere sempre vero (per esempio, in ambienti come namespace/sandbox/chroot). diff --git a/Documentation/translations/it_IT/process/submit-checklist.rst b/Documentation/translations/it_IT/process/submit-checklist.rst index 828c8f27d492..770e5601adc2 100644 --- a/Documentation/translations/it_IT/process/submit-checklist.rst +++ b/Documentation/translations/it_IT/process/submit-checklist.rst @@ -47,7 +47,7 @@ sottomissione delle patch, in particolare 6) Le opzioni ``CONFIG``, nuove o modificate, non scombussolano il menu di configurazione e sono preimpostate come disabilitate a meno che non - soddisfino i criteri descritti in ``Documentation/kbuild/kconfig-language.rst`` + soddisfino i criteri descritti in Documentation/kbuild/kconfig-language.rst alla punto "Voci di menu: valori predefiniti". 7) Tutte le nuove opzioni ``Kconfig`` hanno un messaggio di aiuto. @@ -89,12 +89,12 @@ sottomissione delle patch, in particolare 16) Tutti i nuovi elementi in ``/proc`` sono documentati in ``Documentation/``. 17) Tutti i nuovi parametri d'avvio del kernel sono documentati in - ``Documentation/admin-guide/kernel-parameters.rst``. + Documentation/admin-guide/kernel-parameters.rst. 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.rst`` 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@vger.kernel.org. @@ -118,7 +118,7 @@ sottomissione delle patch, in particolare sorgenti che ne spieghi la logica: cosa fanno e perché. 24) Se la patch aggiunge nuove chiamate ioctl, allora aggiornate - ``Documentation/userspace-api/ioctl/ioctl-number.rst``. + Documentation/userspace-api/ioctl/ioctl-number.rst. 25) Se il codice che avete modificato dipende o usa una qualsiasi interfaccia o funzionalità del kernel che è associata a uno dei seguenti simboli diff --git a/Documentation/translations/sp_SP/process/adding-syscalls.rst b/Documentation/translations/sp_SP/process/adding-syscalls.rst index f21504c612b2..f143d4eea5eb 100644 --- a/Documentation/translations/sp_SP/process/adding-syscalls.rst +++ b/Documentation/translations/sp_SP/process/adding-syscalls.rst @@ -39,7 +39,7 @@ a su interfaz. API algo opaca. - Si sólo está exponiendo información del runtime, un nuevo nodo en sysfs - (mire ``Documentation/filesystems/sysfs.rst``) o el filesystem ``/proc`` + (mire Documentation/filesystems/sysfs.rst) o el filesystem ``/proc`` podría ser más adecuado. Sin embargo, acceder a estos mecanismos requiere que el filesystem relevante esté montado, lo que podría no ser siempre el caso (e.g. en un ambiente namespaced/sandboxed/chrooted). diff --git a/Documentation/translations/sp_SP/process/submit-checklist.rst b/Documentation/translations/sp_SP/process/submit-checklist.rst index b8072be18532..d79b0e7b478d 100644 --- a/Documentation/translations/sp_SP/process/submit-checklist.rst +++ b/Documentation/translations/sp_SP/process/submit-checklist.rst @@ -51,7 +51,7 @@ y en otros lugares con respecto al envío de parches del kernel de Linux. 6) Cualquier opción ``CONFIG`` nueva o modificada no altera el menú de configuración y se desactiva por defecto, a menos que cumpla con los criterios de excepción documentados en - ``Documentation/kbuild/kconfig-language.rst`` Atributos del menú: valor por defecto. + Documentation/kbuild/kconfig-language.rst Atributos del menú: valor por defecto. 7) Todas las nuevas opciones de ``Kconfig`` tienen texto de ayuda. @@ -91,13 +91,13 @@ y en otros lugares con respecto al envío de parches del kernel de Linux. ``Documentation/``. 16) Todos los nuevos parámetros de arranque del kernel están documentados - en ``Documentation/admin-guide/kernel-parameters.rst``. + en Documentation/admin-guide/kernel-parameters.rst. 17) Todos los nuevos parámetros del módulo están documentados con ``MODULE_PARM_DESC()``. 18) Todas las nuevas interfaces de espacio de usuario están documentadas - en ``Documentation/ABI/``. Consulte ``Documentation/ABI/README.rst`` 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@vger.kernel.org. @@ -120,7 +120,7 @@ y en otros lugares con respecto al envío de parches del kernel de Linux. la lógica de lo que están haciendo y por qué. 23) Si se añaden algún ioctl en el parche, actualice también - ``Documentation/userspace-api/ioctl/ioctl-number.rst``. + Documentation/userspace-api/ioctl/ioctl-number.rst. 24) Si su código fuente modificado depende o utiliza cualquiera de las API o características del kernel que están relacionadas con los diff --git a/Documentation/translations/zh_CN/doc-guide/sphinx.rst b/Documentation/translations/zh_CN/doc-guide/sphinx.rst index 23eac67fbc30..b24fbdde4e0d 100644 --- a/Documentation/translations/zh_CN/doc-guide/sphinx.rst +++ b/Documentation/translations/zh_CN/doc-guide/sphinx.rst @@ -134,7 +134,7 @@ Sphinx构建 添加新文档很容易，只需： 1. 在 ``Documentation`` 下某处添加一个新的 ``.rst`` 文件。 -2. 从 ``Documentation/index.rst`` 中的Sphinx `主目录树`_ 链接到它。 +2. 从 Documentation/index.rst 中的Sphinx `主目录树`_ 链接到它。 .. _主目录树: http://www.sphinx-doc.org/en/stable/markup/toctree.html diff --git a/Documentation/translations/zh_CN/process/submit-checklist.rst b/Documentation/translations/zh_CN/process/submit-checklist.rst index 0942021202a3..50c2f31906dd 100644 --- a/Documentation/translations/zh_CN/process/submit-checklist.rst +++ b/Documentation/translations/zh_CN/process/submit-checklist.rst @@ -42,7 +42,7 @@ Linux内核补丁提交检查单 违规行为。 6) 任何新的或修改过的 ``CONFIG`` 选项都不应搞乱配置菜单，并默认为关闭，除非 - 它们符合 ``Documentation/kbuild/kconfig-language.rst`` 菜单属性：默认值中 + 它们符合 Documentation/kbuild/kconfig-language.rst 菜单属性：默认值中 记录的例外条件。 7) 所有新的 ``kconfig`` 选项都有帮助文本。 @@ -83,7 +83,7 @@ Linux内核补丁提交检查单 17) 所有新的模块参数都记录在 ``MODULE_PARM_DESC()`` 18) 所有新的用户空间接口都记录在 ``Documentation/ABI/`` 中。有关详细信息， - 请参阅 ``Documentation/ABI/README.rst`` 。更改用户空间接口的补丁应该抄送 + 请参阅 Documentation/ABI/README.rst 。更改用户空间接口的补丁应该抄送 linux-api@vger.kernel.org。 19) 已通过至少注入slab和page分配失败进行检查。请参阅 ``Documentation/fault-injection/`` 。 @@ -100,7 +100,7 @@ Linux内核补丁提交检查单 释来解释它们正在执行的操作及其原因的逻辑。 23) 如果补丁添加了任何ioctl，那么也要更新 - ``Documentation/userspace-api/ioctl/ioctl-number.rst`` 。 + Documentation/userspace-api/ioctl/ioctl-number.rst 。 24) 如果修改后的源代码依赖或使用与以下 ``Kconfig`` 符号相关的任何内核API或 功能，则在禁用相关 ``Kconfig`` 符号和/或 ``=m`` （如果该选项可用）的情况 diff --git a/Documentation/translations/zh_TW/process/submit-checklist.rst b/Documentation/translations/zh_TW/process/submit-checklist.rst index efece58cb5b2..560bb30ac0f7 100644 --- a/Documentation/translations/zh_TW/process/submit-checklist.rst +++ b/Documentation/translations/zh_TW/process/submit-checklist.rst @@ -45,7 +45,7 @@ Linux內核補丁提交檢查單 違規行爲。 6) 任何新的或修改過的 ``CONFIG`` 選項都不應搞亂配置菜單，並默認爲關閉，除非 - 它們符合 ``Documentation/kbuild/kconfig-language.rst`` 菜單屬性：默認值中 + 它們符合 Documentation/kbuild/kconfig-language.rst 菜單屬性：默認值中 記錄的例外條件。 7) 所有新的 ``kconfig`` 選項都有幫助文本。 @@ -86,7 +86,7 @@ Linux內核補丁提交檢查單 17) 所有新的模塊參數都記錄在 ``MODULE_PARM_DESC()`` 18) 所有新的用戶空間接口都記錄在 ``Documentation/ABI/`` 中。有關詳細信息， - 請參閱 ``Documentation/ABI/README.rst`` 。更改用戶空間接口的補丁應該抄送 + 請參閱 Documentation/ABI/README.rst 。更改用戶空間接口的補丁應該抄送 linux-api@vger.kernel.org。 19) 已通過至少注入slab和page分配失敗進行檢查。請參閱 ``Documentation/fault-injection/`` 。 @@ -103,7 +103,7 @@ Linux內核補丁提交檢查單 釋來解釋它們正在執行的操作及其原因的邏輯。 23) 如果補丁添加了任何ioctl，那麼也要更新 - ``Documentation/userspace-api/ioctl/ioctl-number.rst`` 。 + Documentation/userspace-api/ioctl/ioctl-number.rst 。 24) 如果修改後的源代碼依賴或使用與以下 ``Kconfig`` 符號相關的任何內核API或 功能，則在禁用相關 ``Kconfig`` 符號和/或 ``=m`` （如果該選項可用）的情況 diff --git a/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst b/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst index 42cdb0a9f786..6e796775c740 100644 --- a/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst +++ b/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst @@ -430,7 +430,7 @@ MPEG stream. *Historical context*: This format specification originates from a custom, embedded, sliced VBI data format used by the ``ivtv`` driver. This format has already been informally specified in the kernel sources -in the file ``Documentation/userspace-api/media/drivers/cx2341x-uapi.rst`` . The +in the file Documentation/userspace-api/media/drivers/cx2341x-uapi.rst . The maximum size of the payload and other aspects of this format are driven by the CX23415 MPEG decoder's capabilities and limitations with respect to extracting, decoding, and displaying sliced VBI data embedded within diff --git a/Documentation/userspace-api/media/v4l/diff-v4l.rst b/Documentation/userspace-api/media/v4l/diff-v4l.rst index 33243ecb5033..b087835a147f 100644 --- a/Documentation/userspace-api/media/v4l/diff-v4l.rst +++ b/Documentation/userspace-api/media/v4l/diff-v4l.rst @@ -634,7 +634,7 @@ devices is documented in :ref:`extended-controls`. compatible with V4L or V4L2. .. [#f2] - According to ``Documentation/admin-guide/devices.rst`` a symbolic link to + According to Documentation/admin-guide/devices.rst a symbolic link to ``/dev/radio0``. .. [#f3] diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst index 2a165ae063fb..957c8a54fbfc 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst @@ -109,7 +109,7 @@ enum v4l2_mpeg_stream_vbi_fmt - * - ``V4L2_MPEG_STREAM_VBI_FMT_IVTV`` - VBI in private packets, IVTV format (documented in the kernel sources in the file - ``Documentation/userspace-api/media/drivers/cx2341x-uapi.rst``) + Documentation/userspace-api/media/drivers/cx2341x-uapi.rst) diff --git a/Documentation/virt/uml/user_mode_linux_howto_v2.rst b/Documentation/virt/uml/user_mode_linux_howto_v2.rst index d1cfe415e4c4..d7959b081458 100644 --- a/Documentation/virt/uml/user_mode_linux_howto_v2.rst +++ b/Documentation/virt/uml/user_mode_linux_howto_v2.rst @@ -1083,7 +1083,7 @@ new feature, please send it to ``linux-um@lists.infradead.org``. Please follow all standard Linux patch guidelines such as cc-ing relevant maintainers and run ``./scripts/checkpatch.pl`` on your patch. -For more details see ``Documentation/process/submitting-patches.rst`` +For more details see Documentation/process/submitting-patches.rst Note - the list does not accept HTML or attachments, all emails must be formatted as plain text. -- 2.34.1 ^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [PATCH 4/5] Documentation/ABI/README: convert to ReST 2024-01-08 13:18 ` Vegard Nossum @ 2024-01-31 5:42 ` Mauro Carvalho Chehab 0 siblings, 0 replies; 9+ messages in thread From: Mauro Carvalho Chehab @ 2024-01-31 5:42 UTC (permalink / raw) To: Vegard Nossum Cc: Jonathan Corbet, Randy Dunlap, Greg Kroah-Hartman, Jani Nikula, linux-doc, linux-api Em Mon, 8 Jan 2024 14:18:55 +0100 Vegard Nossum <vegard.nossum@oracle.com> escreveu: > On 05/01/2024 21:07, Mauro Carvalho Chehab wrote: > > Em Thu, 4 Jan 2024 17:09:45 +0100 > > Vegard Nossum <vegard.nossum@oracle.com> escreveu: > >> +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. > > I would prefer to alter this as little as possible, since it describes > the literal format of those ABI files, keeping it readable and > understandable in plain text as well as HTML -- with a single leading > space this whole block shows up as a code block in the HTML, which I > think is appropriate when giving an example of a literal file. Well, you're still not being strict by adding a single space after the field. That's OK for ReST, but if one uses it as a template, the extra space will cause problems. Btw, in the specific case of this code block, there is one alternative approach: keep it untouched and create a new ReST file on a similar approach to what it was done at Documentation/core-api/wrappers/, e. g.: .. SPDX-License-Identifier: GPL-2.0 This is a simple wrapper to bring ABI/README into the RST world. <snip> =============================== Linux userspace ABI description =============================== .. raw:: latex \footnotesize .. include:: ../../ABI/README :literal: .. raw:: latex \normalsize </snip> While I don't like very much this approach, in this very specific case, it is justified, at least for the field description. (Note: the latex part to change the font size may not be needed - it will depend on how this file will appear at the pdf version) > >> 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. > > Good point -- Jon, do you want me to resubmit this or can you fix it up? > > We could also just run a "treewide" fix for this as a separate patch: > > git grep -l '``Documentation/.*\.rst``' 'Documentation/**.rst' \ > | xargs sed -i 's|``\(Documentation[^`*]*\.rst\)``|\1|g' Doing it globally won't work, as there are a few cases where `` is needed: - when there are wildcards at the file name, like: Documentation/driver-api/usb/power-management.rst:covered to some extent (see ``Documentation/power/*.rst`` for more - when they don't point to the actual docs, like: Documentation/doc-guide/sphinx.rst:documentation is under ``Documentation/gpu``, split to several ``.rst`` files, - on some cases, it may require a different approach, or may not make sense, like here: Documentation/doc-guide/sphinx.rst:2. Refer to it from the Sphinx main `TOC tree`_ in ``Documentation/index.rst``. (the `Toc tree`_ is already an cross-reference link. So, it OK to keep ``Documentation/index.rst`` to help people reading at the sources) - when it points, for instance, to ./tools/*/Documentation, as those are currently outside the scope of the ReST docs. Not sure if we still have this at the docs Thanks, Mauro ^ permalink raw reply [flat|nested] 9+ messages in thread
* [PATCH 5/5] docs: userspace-api/api: include ABI/README.rst 2024-01-04 16:09 [PATCH 1/5] docs: move admin-guide/sysfs-rules.rst to userspace-api/ Vegard Nossum ` (2 preceding siblings ...) 2024-01-04 16:09 ` [PATCH 4/5] Documentation/ABI/README: convert to ReST Vegard Nossum @ 2024-01-04 16:09 ` Vegard Nossum 2024-01-05 20:25 ` [PATCH 1/5] docs: move admin-guide/sysfs-rules.rst to userspace-api/ Mauro Carvalho Chehab 4 siblings, 0 replies; 9+ messages in thread From: Vegard Nossum @ 2024-01-04 16:09 UTC (permalink / raw) To: Jonathan Corbet Cc: Randy Dunlap, Mauro Carvalho Chehab, Greg Kroah-Hartman, Jani Nikula, linux-doc, linux-api, Vegard Nossum The rendered ABI documents currently have no introduction or explanation, which is a bit jarring. Documentation/ABI/README is a pretty good introduction, even if it's aimed more at ABI-description producers (rather than consumers) -- we can always tweak the language to be clearer about this distinction later. Include it in userspace-api/api.rst. Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> --- Documentation/userspace-api/abi.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Documentation/userspace-api/abi.rst b/Documentation/userspace-api/abi.rst index bcab3ef2597c..ea615233a405 100644 --- a/Documentation/userspace-api/abi.rst +++ b/Documentation/userspace-api/abi.rst @@ -2,7 +2,10 @@ Linux ABI description ===================== +.. include:: ../ABI/README.rst + .. toctree:: + :caption: Directory :maxdepth: 2 abi-stable -- 2.34.1 ^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [PATCH 1/5] docs: move admin-guide/sysfs-rules.rst to userspace-api/ 2024-01-04 16:09 [PATCH 1/5] docs: move admin-guide/sysfs-rules.rst to userspace-api/ Vegard Nossum ` (3 preceding siblings ...) 2024-01-04 16:09 ` [PATCH 5/5] docs: userspace-api/api: include ABI/README.rst Vegard Nossum @ 2024-01-05 20:25 ` Mauro Carvalho Chehab 4 siblings, 0 replies; 9+ messages in thread From: Mauro Carvalho Chehab @ 2024-01-05 20:25 UTC (permalink / raw) To: Vegard Nossum Cc: Jonathan Corbet, Randy Dunlap, Greg Kroah-Hartman, Jani Nikula, linux-doc, linux-api Em Thu, 4 Jan 2024 17:09:42 +0100 Vegard Nossum <vegard.nossum@oracle.com> escreveu: > This file documents how userspace ought to interact with sysfs. It is > clearly intended for applications that access sysfs programmatically, > rather than at users or admins. > > Move it to the userspace API guide. Hmm... this is both uAPI and admin stuff, as sysfs nodes can be used directly on scripts written by sysadmin. Perhaps we should add a link from one book to the other one, specially if we move it to uAPI guide. Regards, Mauro > > Cc: Mauro Carvalho Chehab <mchehab@kernel.org> > Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> > --- > Documentation/ABI/stable/sysfs-devices | 2 +- > Documentation/admin-guide/index.rst | 9 --------- > Documentation/userspace-api/index.rst | 10 +++++++++- > .../{admin-guide => userspace-api}/sysfs-rules.rst | 0 > tools/lib/api/fs/fs.c | 2 +- > 5 files changed, 11 insertions(+), 12 deletions(-) > rename Documentation/{admin-guide => userspace-api}/sysfs-rules.rst (100%) > > diff --git a/Documentation/ABI/stable/sysfs-devices b/Documentation/ABI/stable/sysfs-devices > index 98a8ef99ac5f..7829414cba62 100644 > --- a/Documentation/ABI/stable/sysfs-devices > +++ b/Documentation/ABI/stable/sysfs-devices > @@ -1,6 +1,6 @@ > Note: > This documents additional properties of any device beyond what > - is documented in Documentation/admin-guide/sysfs-rules.rst > + is documented in Documentation/userspace-api/sysfs-rules.rst > > What: /sys/devices/*/of_node > Date: February 2015 > diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst > index 43ea35613dfc..c2b032314a24 100644 > --- a/Documentation/admin-guide/index.rst > +++ b/Documentation/admin-guide/index.rst > @@ -47,15 +47,6 @@ problems and bugs in particular. > perf/index > pstore-blk > > -This is the beginning of a section with information of interest to > -application developers. Documents covering various aspects of the kernel > -ABI will be found here. > - > -.. toctree:: > - :maxdepth: 1 > - > - sysfs-rules > - > This is the beginning of a section with information of interest to > application developers and system integrators doing analysis of the > Linux kernel for safety critical applications. Documents supporting > diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst > index 74bc0716432e..6ce2edf519f6 100644 > --- a/Documentation/userspace-api/index.rst > +++ b/Documentation/userspace-api/index.rst > @@ -9,8 +9,16 @@ While much of the kernel's user-space API is documented elsewhere > also be found in the kernel tree itself. This manual is intended to be the > place where this information is gathered. > > +General documentation: > + > +.. toctree:: > + :maxdepth: 1 > + > + sysfs-rules > + > +Subsystem-specific documentation: > + > .. toctree:: > - :caption: Table of contents > :maxdepth: 2 > > no_new_privs > diff --git a/Documentation/admin-guide/sysfs-rules.rst b/Documentation/userspace-api/sysfs-rules.rst > similarity index 100% > rename from Documentation/admin-guide/sysfs-rules.rst > rename to Documentation/userspace-api/sysfs-rules.rst > diff --git a/tools/lib/api/fs/fs.c b/tools/lib/api/fs/fs.c > index 5cb0eeec2c8a..c35247b6ad81 100644 > --- a/tools/lib/api/fs/fs.c > +++ b/tools/lib/api/fs/fs.c > @@ -214,7 +214,7 @@ static void mem_toupper(char *f, size_t len) > > /* > * Check for "NAME_PATH" environment variable to override fs location (for > - * testing). This matches the recommendation in Documentation/admin-guide/sysfs-rules.rst > + * testing). This matches the recommendation in Documentation/userspace-api/sysfs-rules.rst > * for SYSFS_PATH. > */ > static bool fs__env_override(struct fs *fs) Thanks, Mauro ^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2024-01-31 5:42 UTC | newest] Thread overview: 9+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2024-01-04 16:09 [PATCH 1/5] docs: move admin-guide/sysfs-rules.rst to userspace-api/ Vegard Nossum 2024-01-04 16:09 ` [PATCH 2/5] docs: move admin-guide/abi*.rst " Vegard Nossum 2024-01-04 16:09 ` [PATCH 3/5] docs: userspace-api: use single toctree level Vegard Nossum 2024-01-04 16:09 ` [PATCH 4/5] Documentation/ABI/README: convert to ReST Vegard Nossum 2024-01-05 20:07 ` Mauro Carvalho Chehab 2024-01-08 13:18 ` Vegard Nossum 2024-01-31 5:42 ` Mauro Carvalho Chehab 2024-01-04 16:09 ` [PATCH 5/5] docs: userspace-api/api: include ABI/README.rst Vegard Nossum 2024-01-05 20:25 ` [PATCH 1/5] docs: move admin-guide/sysfs-rules.rst to userspace-api/ Mauro Carvalho Chehab
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).