[PATCH v2 1/1] docs: Update documentation to avoid mentioning of kernel.h

[PATCH v2 1/1] docs: Update documentation to avoid mentioning of kernel.h

[Andy Shevchenko]

For several years, and still ongoing, the kernel.h is being split
to smaller and narrow headers to avoid "including everything" approach
which is bad in many ways. Since that, documentation missed a few
required updates to align with that work. Do it here.

Note, language translations are left untouched and if anybody willing
to help, please provide path(es) based on the updated English variant.

Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
---

v2: collected tag (Randy), fixed util_macros k-doc (Randy, me), fixed spelling (Randy)

 Documentation/core-api/kobject.rst              |  2 +-
 Documentation/dev-tools/checkpatch.rst          |  2 +-
 Documentation/driver-api/basics.rst             | 17 ++++++++++++++++-
 .../driver-api/driver-model/design-patterns.rst |  2 +-
 Documentation/process/coding-style.rst          | 10 +++++++---
 Documentation/staging/rpmsg.rst                 |  7 +++++--
 include/linux/util_macros.h                     |  2 +-
 7 files changed, 32 insertions(+), 10 deletions(-)

diff --git a/Documentation/core-api/kobject.rst b/Documentation/core-api/kobject.rst
index 7310247310a0..5f6c61bc03bf 100644
--- a/Documentation/core-api/kobject.rst
+++ b/Documentation/core-api/kobject.rst
@@ -78,7 +78,7 @@ just a matter of using the kobj member.  Code that works with kobjects will
 often have the opposite problem, however: given a struct kobject pointer,
 what is the pointer to the containing structure?  You must avoid tricks
 (such as assuming that the kobject is at the beginning of the structure)
-and, instead, use the container_of() macro, found in ``<linux/kernel.h>``::
+and, instead, use the container_of() macro, found in ``<linux/container_of.h>``::
 
     container_of(ptr, type, member)
 
diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst
index fa2988dd4657..c1dff8e6bccb 100644
--- a/Documentation/dev-tools/checkpatch.rst
+++ b/Documentation/dev-tools/checkpatch.rst
@@ -753,7 +753,7 @@ Macros, Attributes and Symbols
     sizeof(foo)/sizeof(foo[0]) for finding number of elements in an
     array.
 
-    The macro is defined in include/linux/kernel.h::
+    The macro is defined in include/linux/array_size.h::
 
       #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
 
diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst
index 5e9f7aee71a7..8b6a5888cb11 100644
--- a/Documentation/driver-api/basics.rst
+++ b/Documentation/driver-api/basics.rst
@@ -114,10 +114,25 @@ Kernel objects manipulation
 Kernel utility functions
 ------------------------
 
-.. kernel-doc:: include/linux/kernel.h
+.. kernel-doc:: include/linux/array_size.h
+   :internal:
+
+.. kernel-doc:: include/linux/container_of.h
+   :internal:
+
+.. kernel-doc:: include/linux/kstrtox.h
    :internal:
    :no-identifiers: kstrtol kstrtoul
 
+.. kernel-doc:: include/linux/stddef.h
+   :internal:
+
+.. kernel-doc:: include/linux/util_macros.h
+   :internal:
+
+.. kernel-doc:: include/linux/wordpart.h
+   :internal:
+
 .. kernel-doc:: kernel/printk/printk.c
    :export:
    :no-identifiers: printk
diff --git a/Documentation/driver-api/driver-model/design-patterns.rst b/Documentation/driver-api/driver-model/design-patterns.rst
index 41eb8f41f7dd..965b2b93be6f 100644
--- a/Documentation/driver-api/driver-model/design-patterns.rst
+++ b/Documentation/driver-api/driver-model/design-patterns.rst
@@ -103,7 +103,7 @@ The design pattern is the same for an hrtimer or something similar that will
 return a single argument which is a pointer to a struct member in the
 callback.
 
-container_of() is a macro defined in <linux/kernel.h>
+container_of() is a macro defined in <linux/container_of.h>
 
 What container_of() does is to obtain a pointer to the containing struct from
 a pointer to a member by a simple subtraction using the offsetof() macro from
diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 2969ca378dbb..258158637f65 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -1070,7 +1070,7 @@ readability.
 18) Don't re-invent the kernel macros
 -------------------------------------
 
-The header file include/linux/kernel.h contains a number of macros that
+There are many header files in include/linux/ that contain a number of macros that
 you should use, rather than explicitly coding some variant of them yourself.
 For example, if you need to calculate the length of an array, take advantage
 of the macro
@@ -1079,14 +1079,18 @@ of the macro
 
 	#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
 
+which is defined in array_size.h.
+
 Similarly, if you need to calculate the size of some structure member, use
 
 .. code-block:: c
 
 	#define sizeof_field(t, f) (sizeof(((t*)0)->f))
 
-There are also min() and max() macros that do strict type checking if you
-need them.  Feel free to peruse that header file to see what else is already
+which is defined in stddef.h.
+
+There are also min() and max() macros defined in minmax.h that do strict type checking
+if you need them. Feel free to peruse the header files to see what else is already
 defined that you shouldn't reproduce in your code.
 
 
diff --git a/Documentation/staging/rpmsg.rst b/Documentation/staging/rpmsg.rst
index 40282cca86ca..42bac1149d9d 100644
--- a/Documentation/staging/rpmsg.rst
+++ b/Documentation/staging/rpmsg.rst
@@ -224,9 +224,12 @@ content to the console.
 
 ::
 
-  #include <linux/kernel.h>
+  #include <linux/dev_printk.h>
+  #include <linux/mod_devicetable.h>
   #include <linux/module.h>
+  #include <linux/printk.h>
   #include <linux/rpmsg.h>
+  #include <linux/types.h>
 
   static void rpmsg_sample_cb(struct rpmsg_channel *rpdev, void *data, int len,
 						void *priv, u32 src)
@@ -244,7 +247,7 @@ content to the console.
 	/* send a message on our channel */
 	err = rpmsg_send(rpdev->ept, "hello!", 6);
 	if (err) {
-		pr_err("rpmsg_send failed: %d\n", err);
+		dev_err(&rpdev->dev, "rpmsg_send failed: %d\n", err);
 		return err;
 	}
 
diff --git a/include/linux/util_macros.h b/include/linux/util_macros.h
index 2eb528058d0d..71564868b8f6 100644
--- a/include/linux/util_macros.h
+++ b/include/linux/util_macros.h
@@ -119,7 +119,7 @@
  * a fuss about it. This makes the programmer responsible for tagging
  * the functions that can be garbage-collected.
  *
- * With the macro it is possible to write the following:
+ * With the macro it is possible to write the following::
  *
  *     static int foo_suspend(struct device *dev)
  *     {
-- 
2.50.1

Re: [PATCH v2 1/1] docs: Update documentation to avoid mentioning of kernel.h

[Randy Dunlap]

On 11/26/25 1:46 PM, Andy Shevchenko wrote:
> For several years, and still ongoing, the kernel.h is being split
> to smaller and narrow headers to avoid "including everything" approach
> which is bad in many ways. Since that, documentation missed a few
> required updates to align with that work. Do it here.
> 
> Note, language translations are left untouched and if anybody willing
> to help, please provide path(es) based on the updated English variant.
> 
> Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>

Tested-by: Randy Dunlap <rdunlap@infradead.org>

> ---
> 
> v2: collected tag (Randy), fixed util_macros k-doc (Randy, me), fixed spelling (Randy)
> 
>  Documentation/core-api/kobject.rst              |  2 +-
>  Documentation/dev-tools/checkpatch.rst          |  2 +-
>  Documentation/driver-api/basics.rst             | 17 ++++++++++++++++-
>  .../driver-api/driver-model/design-patterns.rst |  2 +-
>  Documentation/process/coding-style.rst          | 10 +++++++---
>  Documentation/staging/rpmsg.rst                 |  7 +++++--
>  include/linux/util_macros.h                     |  2 +-
>  7 files changed, 32 insertions(+), 10 deletions(-)
> 

-- 
~Randy

Re: [PATCH v2 1/1] docs: Update documentation to avoid mentioning of kernel.h

[Joe Perches]

On Wed, 2025-11-26 at 22:46 +0100, Andy Shevchenko wrote:
> For several years, and still ongoing, the kernel.h is being split
> to smaller and narrow headers to avoid "including everything" approach
> which is bad in many ways.

And I still think precompiled headers can be beneficial to
standardize using kernel.h to reduce overall compilation time.

Re: [PATCH v2 1/1] docs: Update documentation to avoid mentioning of kernel.h

[Andy Shevchenko]

On Thu, Nov 27, 2025 at 09:34:51AM -0800, Joe Perches wrote:
> On Wed, 2025-11-26 at 22:46 +0100, Andy Shevchenko wrote:
> > For several years, and still ongoing, the kernel.h is being split
> > to smaller and narrow headers to avoid "including everything" approach
> > which is bad in many ways.
> 
> And I still think precompiled headers can be beneficial to
> standardize using kernel.h to reduce overall compilation time.

Same Q, why don't we have just a single header? Why do we have a concept of
(modular) headers to begin with? And Ingo's approach shows that the problem
can be solved properly by dividing headers to be more logical smaller pieces.
So, I have a strong disagreement for using kernel.h. At least not in this form,
It needs to be cleaned up and some sanity given to that train wreck. When it's
done, we can think of precompiled headers.

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v2 1/1] docs: Update documentation to avoid mentioning of kernel.h

[Andy Shevchenko]

On Wed, Nov 26, 2025 at 04:26:04PM -0800, Randy Dunlap wrote:
> On 11/26/25 1:46 PM, Andy Shevchenko wrote:
> > For several years, and still ongoing, the kernel.h is being split
> > to smaller and narrow headers to avoid "including everything" approach
> > which is bad in many ways. Since that, documentation missed a few
> > required updates to align with that work. Do it here.
> > 
> > Note, language translations are left untouched and if anybody willing
> > to help, please provide path(es) based on the updated English variant.
> > 
> > Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
> > Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
> 
> Tested-by: Randy Dunlap <rdunlap@infradead.org>

Thanks, Randy!

Jonathan, please apply this change. Independently on the opinions about
kernel.h the documentation has to be updated as it's currently misleading.

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v2 1/1] docs: Update documentation to avoid mentioning of kernel.h

[Jonathan Corbet]

Andy Shevchenko <andriy.shevchenko@linux.intel.com> writes:

> On Wed, Nov 26, 2025 at 04:26:04PM -0800, Randy Dunlap wrote:
>> On 11/26/25 1:46 PM, Andy Shevchenko wrote:
>> > For several years, and still ongoing, the kernel.h is being split
>> > to smaller and narrow headers to avoid "including everything" approach
>> > which is bad in many ways. Since that, documentation missed a few
>> > required updates to align with that work. Do it here.
>> > 
>> > Note, language translations are left untouched and if anybody willing
>> > to help, please provide path(es) based on the updated English variant.
>> > 
>> > Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
>> > Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
>> 
>> Tested-by: Randy Dunlap <rdunlap@infradead.org>
>
> Thanks, Randy!
>
> Jonathan, please apply this change. Independently on the opinions about
> kernel.h the documentation has to be updated as it's currently misleading.

I will but not right away...I'm really trying to stabilize things,
already too late, for the merge window.

jon

Re: [PATCH v2 1/1] docs: Update documentation to avoid mentioning of kernel.h

[Andy Shevchenko]

On Sat, Nov 29, 2025 at 08:54:48AM -0700, Jonathan Corbet wrote:
> Andy Shevchenko <andriy.shevchenko@linux.intel.com> writes:
> > On Wed, Nov 26, 2025 at 04:26:04PM -0800, Randy Dunlap wrote:
> >> On 11/26/25 1:46 PM, Andy Shevchenko wrote:
> >> > For several years, and still ongoing, the kernel.h is being split
> >> > to smaller and narrow headers to avoid "including everything" approach
> >> > which is bad in many ways. Since that, documentation missed a few
> >> > required updates to align with that work. Do it here.
> >> > 
> >> > Note, language translations are left untouched and if anybody willing
> >> > to help, please provide path(es) based on the updated English variant.
> >> > 
> >> > Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
> >> > Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
> >> 
> >> Tested-by: Randy Dunlap <rdunlap@infradead.org>
> >
> > Thanks, Randy!
> >
> > Jonathan, please apply this change. Independently on the opinions about
> > kernel.h the documentation has to be updated as it's currently misleading.
> 
> I will but not right away...I'm really trying to stabilize things,
> already too late, for the merge window.

Noted, thanks for explanation!

-- 
With Best Regards,
Andy Shevchenko

[PATCH] Doc:it_IT: Do not reference kernel.h anymore

[Andi Shyti]

coding-style.rst still references the kernel.h header, which is
being phased out. Remove that reference and point to the proper
headers for the examples instead: array_size.h, stddef.h and
minmax.h.

Signed-off-by: Andi Shyti <andi.shyti@kernel.org>
Cc: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Cc: Federico Vaga <federico.vaga@vaga.pv.it>
---
Hi,

Following Andy's suggestion, and as a native Italian speaker,
I am updating the Italian translation of coding-style.rst based
on his original change.

I also took the chance to improve the phrasing in a few places.

Andi

 .../it_IT/process/coding-style.rst            | 19 +++++++++++--------
 1 file changed, 11 insertions(+), 8 deletions(-)

diff --git a/Documentation/translations/it_IT/process/coding-style.rst b/Documentation/translations/it_IT/process/coding-style.rst
index c0dc786b8474..b2fd74528de5 100644
--- a/Documentation/translations/it_IT/process/coding-style.rst
+++ b/Documentation/translations/it_IT/process/coding-style.rst
@@ -1068,15 +1068,17 @@ può migliorare la leggibilità.
 18) Non reinventate le macro del kernel
 ---------------------------------------
 
-Il file di intestazione include/linux/kernel.h contiene un certo numero
-di macro che dovreste usare piuttosto che implementarne una qualche variante.
-Per esempio, se dovete calcolare la lunghezza di un vettore, sfruttate la
-macro:
+I file header presenti in include/linux mettono a disposizione numerose macro
+che è preferibile utilizzare, evitando di sviluppare implementazioni
+alternative. Per esempio, se dovete calcolare la lunghezza di un vettore,
+sfruttate la macro:
 
 .. code-block:: c
 
 	#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
 
+definita in array_size.h.
+
 Analogamente, se dovete calcolare la dimensione di un qualche campo di una
 struttura, usate
 
@@ -1084,10 +1086,11 @@ struttura, usate
 
 	#define sizeof_field(t, f) (sizeof(((t*)0)->f))
 
-Ci sono anche le macro min() e max() che, se vi serve, effettuano un controllo
-rigido sui tipi.  Sentitevi liberi di leggere attentamente questo file
-d'intestazione per scoprire cos'altro è stato definito che non dovreste
-reinventare nel vostro codice.
+definita in stddef.h.
+
+Ci sono anche le macro min() e max() definite in minmax.h che effettuano un
+controllo rigoroso sui tipi. È consigliato consultare i vari file header per
+vedere altre macro già disponibili.
 
 19) Linee di configurazione degli editor e altre schifezze
 -----------------------------------------------------------
-- 
2.51.0

Re: [PATCH v2 1/1] docs: Update documentation to avoid mentioning of kernel.h

[Mathieu Poirier]

On Wed, 26 Nov 2025 at 14:47, Andy Shevchenko
<andriy.shevchenko@linux.intel.com> wrote:
>
> For several years, and still ongoing, the kernel.h is being split
> to smaller and narrow headers to avoid "including everything" approach
> which is bad in many ways. Since that, documentation missed a few
> required updates to align with that work. Do it here.
>
> Note, language translations are left untouched and if anybody willing
> to help, please provide path(es) based on the updated English variant.
>
> Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
> ---
>
> v2: collected tag (Randy), fixed util_macros k-doc (Randy, me), fixed spelling (Randy)
>
>  Documentation/core-api/kobject.rst              |  2 +-
>  Documentation/dev-tools/checkpatch.rst          |  2 +-
>  Documentation/driver-api/basics.rst             | 17 ++++++++++++++++-
>  .../driver-api/driver-model/design-patterns.rst |  2 +-
>  Documentation/process/coding-style.rst          | 10 +++++++---
>  Documentation/staging/rpmsg.rst                 |  7 +++++--
>  include/linux/util_macros.h                     |  2 +-
>  7 files changed, 32 insertions(+), 10 deletions(-)
>
> diff --git a/Documentation/core-api/kobject.rst b/Documentation/core-api/kobject.rst
> index 7310247310a0..5f6c61bc03bf 100644
> --- a/Documentation/core-api/kobject.rst
> +++ b/Documentation/core-api/kobject.rst
> @@ -78,7 +78,7 @@ just a matter of using the kobj member.  Code that works with kobjects will
>  often have the opposite problem, however: given a struct kobject pointer,
>  what is the pointer to the containing structure?  You must avoid tricks
>  (such as assuming that the kobject is at the beginning of the structure)
> -and, instead, use the container_of() macro, found in ``<linux/kernel.h>``::
> +and, instead, use the container_of() macro, found in ``<linux/container_of.h>``::
>
>      container_of(ptr, type, member)
>
> diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst
> index fa2988dd4657..c1dff8e6bccb 100644
> --- a/Documentation/dev-tools/checkpatch.rst
> +++ b/Documentation/dev-tools/checkpatch.rst
> @@ -753,7 +753,7 @@ Macros, Attributes and Symbols
>      sizeof(foo)/sizeof(foo[0]) for finding number of elements in an
>      array.
>
> -    The macro is defined in include/linux/kernel.h::
> +    The macro is defined in include/linux/array_size.h::
>
>        #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
>
> diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst
> index 5e9f7aee71a7..8b6a5888cb11 100644
> --- a/Documentation/driver-api/basics.rst
> +++ b/Documentation/driver-api/basics.rst
> @@ -114,10 +114,25 @@ Kernel objects manipulation
>  Kernel utility functions
>  ------------------------
>
> -.. kernel-doc:: include/linux/kernel.h
> +.. kernel-doc:: include/linux/array_size.h
> +   :internal:
> +
> +.. kernel-doc:: include/linux/container_of.h
> +   :internal:
> +
> +.. kernel-doc:: include/linux/kstrtox.h
>     :internal:
>     :no-identifiers: kstrtol kstrtoul
>
> +.. kernel-doc:: include/linux/stddef.h
> +   :internal:
> +
> +.. kernel-doc:: include/linux/util_macros.h
> +   :internal:
> +
> +.. kernel-doc:: include/linux/wordpart.h
> +   :internal:
> +
>  .. kernel-doc:: kernel/printk/printk.c
>     :export:
>     :no-identifiers: printk
> diff --git a/Documentation/driver-api/driver-model/design-patterns.rst b/Documentation/driver-api/driver-model/design-patterns.rst
> index 41eb8f41f7dd..965b2b93be6f 100644
> --- a/Documentation/driver-api/driver-model/design-patterns.rst
> +++ b/Documentation/driver-api/driver-model/design-patterns.rst
> @@ -103,7 +103,7 @@ The design pattern is the same for an hrtimer or something similar that will
>  return a single argument which is a pointer to a struct member in the
>  callback.
>
> -container_of() is a macro defined in <linux/kernel.h>
> +container_of() is a macro defined in <linux/container_of.h>
>
>  What container_of() does is to obtain a pointer to the containing struct from
>  a pointer to a member by a simple subtraction using the offsetof() macro from
> diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> index 2969ca378dbb..258158637f65 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -1070,7 +1070,7 @@ readability.
>  18) Don't re-invent the kernel macros
>  -------------------------------------
>
> -The header file include/linux/kernel.h contains a number of macros that
> +There are many header files in include/linux/ that contain a number of macros that
>  you should use, rather than explicitly coding some variant of them yourself.
>  For example, if you need to calculate the length of an array, take advantage
>  of the macro
> @@ -1079,14 +1079,18 @@ of the macro
>
>         #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
>
> +which is defined in array_size.h.
> +
>  Similarly, if you need to calculate the size of some structure member, use
>
>  .. code-block:: c
>
>         #define sizeof_field(t, f) (sizeof(((t*)0)->f))
>
> -There are also min() and max() macros that do strict type checking if you
> -need them.  Feel free to peruse that header file to see what else is already
> +which is defined in stddef.h.
> +
> +There are also min() and max() macros defined in minmax.h that do strict type checking
> +if you need them. Feel free to peruse the header files to see what else is already
>  defined that you shouldn't reproduce in your code.
>
>
> diff --git a/Documentation/staging/rpmsg.rst b/Documentation/staging/rpmsg.rst
> index 40282cca86ca..42bac1149d9d 100644
> --- a/Documentation/staging/rpmsg.rst
> +++ b/Documentation/staging/rpmsg.rst
> @@ -224,9 +224,12 @@ content to the console.
>
>  ::
>
> -  #include <linux/kernel.h>
> +  #include <linux/dev_printk.h>
> +  #include <linux/mod_devicetable.h>
>    #include <linux/module.h>
> +  #include <linux/printk.h>
>    #include <linux/rpmsg.h>
> +  #include <linux/types.h>
>
>    static void rpmsg_sample_cb(struct rpmsg_channel *rpdev, void *data, int len,
>                                                 void *priv, u32 src)
> @@ -244,7 +247,7 @@ content to the console.
>         /* send a message on our channel */
>         err = rpmsg_send(rpdev->ept, "hello!", 6);
>         if (err) {
> -               pr_err("rpmsg_send failed: %d\n", err);
> +               dev_err(&rpdev->dev, "rpmsg_send failed: %d\n", err);
>                 return err;
>         }

Reviewed-by: Mathieu Poirier <mathieu.poirier@linaro.org>

>
> diff --git a/include/linux/util_macros.h b/include/linux/util_macros.h
> index 2eb528058d0d..71564868b8f6 100644
> --- a/include/linux/util_macros.h
> +++ b/include/linux/util_macros.h
> @@ -119,7 +119,7 @@
>   * a fuss about it. This makes the programmer responsible for tagging
>   * the functions that can be garbage-collected.
>   *
> - * With the macro it is possible to write the following:
> + * With the macro it is possible to write the following::
>   *
>   *     static int foo_suspend(struct device *dev)
>   *     {
> --
> 2.50.1
>

Re: [PATCH] Doc:it_IT: Do not reference kernel.h anymore

[Federico Vaga]

Hi Andi,

thank you for contributing to the Italian translation.

On Fri, Dec 05, 2025 at 12:15:58PM +0100, Andi Shyti wrote:
>I also took the chance to improve the phrasing in a few places.

As a technical translation, we should not try to make reinterpretation of the
original text. See comments below.

>Andi
>
> .../it_IT/process/coding-style.rst            | 19 +++++++++++--------
> 1 file changed, 11 insertions(+), 8 deletions(-)
>
>diff --git a/Documentation/translations/it_IT/process/coding-style.rst b/Documentation/translations/it_IT/process/coding-style.rst
>index c0dc786b8474..b2fd74528de5 100644
>--- a/Documentation/translations/it_IT/process/coding-style.rst
>+++ b/Documentation/translations/it_IT/process/coding-style.rst
>@@ -1068,15 +1068,17 @@ può migliorare la leggibilità.
> 18) Non reinventate le macro del kernel
> ---------------------------------------
>
>-Il file di intestazione include/linux/kernel.h contiene un certo numero
>-di macro che dovreste usare piuttosto che implementarne una qualche variante.
>-Per esempio, se dovete calcolare la lunghezza di un vettore, sfruttate la
>-macro:
>+I file header

In Italian, the correct name for "header file" is "file di intestazione".
Please, don't replace correct Italian with *Itanglese* :)

>presenti in include/linux mettono a disposizione numerose macro
>+che è preferibile utilizzare, evitando di sviluppare implementazioni
>+alternative.

I think it is less accurate. In English, it tells users what they "should do"
and "should not do". It does not speak about what is preferable and what to
avoid. I agree that, at the end of the day, one should come at the same
conclusions. However, the translation should be as accurate as possible and
make adaptations wherever necessary to improve the understanding.

A would be perfectly fine if also the English statement changes in the same
direction.

Including your suggestions I would write:

"""
I file di intestazione presenti in include/linux mettono a disposizione numerose
macro che dovreste utilizzare piuttosto che implementarne delle varianti.
"""

>@@ -1084,10 +1086,11 @@ struttura, usate
>
> 	#define sizeof_field(t, f) (sizeof(((t*)0)->f))
>
>-Ci sono anche le macro min() e max() che, se vi serve, effettuano un controllo
>-rigido sui tipi.  Sentitevi liberi di leggere attentamente questo file
>-d'intestazione per scoprire cos'altro è stato definito che non dovreste
>-reinventare nel vostro codice.
>+definita in stddef.h.
>+
>+Ci sono anche le macro min() e max() definite in minmax.h che effettuano un
>+controllo rigoroso sui tipi.

Here it is loosing the "if you need them". If removed here, it should be removed
also in the English version. Of course, one use functions if they are needed, it
comes without saying.

>È consigliato consultare i vari file header per
>+vedere altre macro già disponibili.

"file header" -> "file di intestazione"

Here, the English text is more colloquial and speaks to users with some irony.
In your adaptation these things are lost. Which is fine if also the English version
looses it with a more cold/professional "It is recommanded reading ...".

-- 
Federico Vaga

Re: [PATCH] Doc:it_IT: Do not reference kernel.h anymore

[Andi Shyti]

Hi Federico,

> >-Il file di intestazione include/linux/kernel.h contiene un certo numero
> >-di macro che dovreste usare piuttosto che implementarne una qualche variante.
> >-Per esempio, se dovete calcolare la lunghezza di un vettore, sfruttate la
> >-macro:
> >+I file header
> 
> In Italian, the correct name for "header file" is "file di intestazione".
> Please, don't replace correct Italian with *Itanglese* :)

I absolutely disagree.

If you open any C book, they are called 'header files', except
for a few Italian technical books with excessively literal
translations, where even non-translatable terms are translated.

Italian technical translations usually preserve the original
English terms as much as possible, which is quite different from
what often happens in French or German.

'File di intestazione' is a literal word-by-word translation.
If you want the proper technical term, it is 'header file'.

> >presenti in include/linux mettono a disposizione numerose macro
> >+che è preferibile utilizzare, evitando di sviluppare implementazioni
> >+alternative.
> 
> I think it is less accurate. In English, it tells users what they "should do"
> and "should not do". It does not speak about what is preferable and what to
> avoid. I agree that, at the end of the day, one should come at the same
> conclusions. However, the translation should be as accurate as possible and
> make adaptations wherever necessary to improve the understanding.
> 
> A would be perfectly fine if also the English statement changes in the same
> direction.

I think a literal translation is not beneficial to the final
text, and we have some room to rephrase it while keeping the
original meaning intact.

Andi

Re: [PATCH] Doc:it_IT: Do not reference kernel.h anymore

[Federico Vaga]

Hi Andi,

On Mon, Dec 15, 2025 at 05:14:02PM +0100, Andi Shyti wrote:
>Hi Federico,
>
>> >-Il file di intestazione include/linux/kernel.h contiene un certo numero
>> >-di macro che dovreste usare piuttosto che implementarne una qualche variante.
>> >-Per esempio, se dovete calcolare la lunghezza di un vettore, sfruttate la
>> >-macro:
>> >+I file header
>>
>> In Italian, the correct name for "header file" is "file di intestazione".
>> Please, don't replace correct Italian with *Itanglese* :)
>
>I absolutely disagree.
>
>If you open any C book, they are called 'header files', except
>for a few Italian technical books with excessively literal
>translations, where even non-translatable terms are translated.
>
>Italian technical translations usually preserve the original
>English terms as much as possible, which is quite different from
>what often happens in French or German.
>
>'File di intestazione' is a literal word-by-word translation.
>If you want the proper technical term, it is 'header file'.

Both English and Italian terms are borrowed from typography, "that thing you see
on top of your document": the header file. In Italian, we never had a neologism
for "file", but we have a typography glossary. So it becomes "file di
intestazione". A wider audience can quickly understand where to look to find the
mentioned "file" because "intestazione" means at the top ("in testa"), like in
English.

As you rightly mentioned, other languages are more alive than Italian and their
speakers naturally make and use neologisms for the new things popping up in
their lives without scandal. For Italian speakers, these days, it is harder
(already this email shows that I need to justify the use of Italian words in an
Italian document. There are some publications about this problem if you would
like to know more). However, I don't think this should be a justification to
forget that terms exist and should be used. I'm well aware of all possible
variants that you can find in Italian original texts (they exist) or
translations ("I file di intestazione", "L'header", "I file header", "L'header
file"). You wrote that the good one is "header file", but four variants exist
and your rephrase used "file header" (swapped). When I started this work long
ago I had to chose an editorial line, and I chose to use Italian terms: (a) when
they exist, (b) they have sufficient diffusion, and (c) if it adds value for a
wider audience.

For the case at hand, any web search will give you various results using "file
di intestazione". You can also use Google Books. You might still say that is not
your taste because you prefer English words, but it can't be denied that the
term exists and it is used.

On this particular subject, I think we are a bit off-topic. But if you want to
discuss more we can continue aside.

>> >presenti in include/linux mettono a disposizione numerose macro
>> >+che è preferibile utilizzare, evitando di sviluppare implementazioni
>> >+alternative.
>>
>> I think it is less accurate. In English, it tells users what they "should do"
>> and "should not do". It does not speak about what is preferable and what to
>> avoid. I agree that, at the end of the day, one should come at the same
>> conclusions. However, the translation should be as accurate as possible and
>> make adaptations wherever necessary to improve the understanding.
>>
>> A would be perfectly fine if also the English statement changes in the same
>> direction.
>
>I think a literal translation is not beneficial to the final
>text,

It is not a literal translation. It is a translation. For example, if there is a
joke inside the documentation, that joke gets translated no matter my opinion on
that joke or jokes in technical documents in general. If there are implicit,
rather than explicit, references they get translated as such. If the
documentation needs improvement, it must be first done in its original language,
and the translation must follow.

>and we have some room to rephrase it while keeping the original meaning intact.

Why not using that room in English as well? For example:

""" From the patch
Feel free to peruse the header files to see what else is already
defined that you shouldn't reproduce in your code.
"""

""" Your suggestion
È consigliato consultare i vari file header per vedere altre macro già
disponibili.
"""

This reprhase is not anymore -->friendly<-- inviting users to read the header
files and discover new macros, and it is not reminding them that they should do
it to avoid duplicating code, probably incorrect code (the entire intention of
point 18 of the coding style document).

A reprhase for better readability would be greatly appriciated, I'm definively
not Dante. In doing so, remember to not delete things or change the tone of the
original text. If that is your intention, then do the same in English.

P.S. I'm interested in the non-translatable terms you found in Italian books. In
the past I was doing some researches on the topic and I'm genuinly curious to
see what you found there and see their etymology :)

>Andi
>

-- 
Federico Vaga

Re: [PATCH v2 1/1] docs: Update documentation to avoid mentioning of kernel.h

[Jonathan Corbet]

Andy Shevchenko <andriy.shevchenko@linux.intel.com> writes:

> For several years, and still ongoing, the kernel.h is being split
> to smaller and narrow headers to avoid "including everything" approach
> which is bad in many ways. Since that, documentation missed a few
> required updates to align with that work. Do it here.
>
> Note, language translations are left untouched and if anybody willing
> to help, please provide path(es) based on the updated English variant.
>
> Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
> ---
>
> v2: collected tag (Randy), fixed util_macros k-doc (Randy, me), fixed spelling (Randy)
>
>  Documentation/core-api/kobject.rst              |  2 +-
>  Documentation/dev-tools/checkpatch.rst          |  2 +-
>  Documentation/driver-api/basics.rst             | 17 ++++++++++++++++-
>  .../driver-api/driver-model/design-patterns.rst |  2 +-
>  Documentation/process/coding-style.rst          | 10 +++++++---
>  Documentation/staging/rpmsg.rst                 |  7 +++++--
>  include/linux/util_macros.h                     |  2 +-
>  7 files changed, 32 insertions(+), 10 deletions(-)

Applied (finally) thanks.

jon

Re: [PATCH] Doc:it_IT: Do not reference kernel.h anymore

[Jonathan Corbet]

Andi Shyti <andi.shyti@kernel.org> writes:

> Hi Federico,
>
>> >-Il file di intestazione include/linux/kernel.h contiene un certo numero
>> >-di macro che dovreste usare piuttosto che implementarne una qualche variante.
>> >-Per esempio, se dovete calcolare la lunghezza di un vettore, sfruttate la
>> >-macro:
>> >+I file header
>> 
>> In Italian, the correct name for "header file" is "file di intestazione".
>> Please, don't replace correct Italian with *Itanglese* :)
>
> I absolutely disagree.
>
> If you open any C book, they are called 'header files', except
> for a few Italian technical books with excessively literal
> translations, where even non-translatable terms are translated.

I'm unconvinced about "file di intestazione" based on my own
understanding of the language... but, in a case like this, I will defer
to the creator and maintainer of the translation.

Thanks,

jon

Re: [PATCH] Doc:it_IT: Do not reference kernel.h anymore

[Federico Vaga]

Hi Jon,

Thank you for your message

On Mon, Dec 22, 2025 at 03:01:57PM -0700, Jonathan Corbet wrote:
>Andi Shyti <andi.shyti@kernel.org> writes:
>
>> Hi Federico,
>>
>>> >-Il file di intestazione include/linux/kernel.h contiene un certo numero
>>> >-di macro che dovreste usare piuttosto che implementarne una qualche variante.
>>> >-Per esempio, se dovete calcolare la lunghezza di un vettore, sfruttate la
>>> >-macro:
>>> >+I file header
>>>
>>> In Italian, the correct name for "header file" is "file di intestazione".
>>> Please, don't replace correct Italian with *Itanglese* :)
>>
>> I absolutely disagree.
>>
>> If you open any C book, they are called 'header files', except
>> for a few Italian technical books with excessively literal
>> translations, where even non-translatable terms are translated.
>
>I'm unconvinced about "file di intestazione" based on my own
>understanding of the language... but, in a case like this, I will defer
>to the creator and maintainer of the translation.

Due to my explanation in the previous message, and after your answer, I have the
feeling it may sounds like I'm making up words needing persuasion. Probably I'm
misunderstanding. Just in case, please allow me a clarification.

"File di intestazione" is the equivalent in Italian, same semantic. It can be
found at the university, in books, in youtube videos, and in tutorials about C
and C++ languages. One might have different opinions on the term. But it is a
fact that the term exits, it is Italian, and it is used.

> [...]
> I chose to use Italian terms: (a) when they exist, (b) they have sufficient
> diffusion, and (c) if it adds value for a wider audience.
> [...]

A short list of references.

Universities:

Napoli: https://www.docenti.unina.it/webdocenti-be/allegati/materiale-didattico/94515
Bologna: http://lia.deis.unibo.it/Courses/FondA0607-ELE/materiale/Lucidi/ProgettiSuPiuFile.pdf
Milano: https://aguzzoli.di.unimi.it/didattica/algo12/lucidi1.pdf
Torino: https://staff.polito.it/claudio.fornaro/CorsoC/09-Stringhe.pdf

Wikis:

https://it.wikibooks.org/wiki/Dal_C_al_C++/Utilizzo_basilare_di_librerie/I_file_di_intestazione
https://it.wikibooks.org/wiki/C/Compilatore_e_precompilatore/Header
https://it.wikipedia.org/wiki/Direttiva_di_inclusione

   From Italian-aware automatic translations:

https://www.ibm.com/docs/it/aix/7.3.0?topic=reference-header-files
https://learn.microsoft.com/it-it/cpp/cpp/header-files-cpp

Books:

Original Italian:
https://www.google.ch/books/edition/Dalla_A_alla_Z_passando_per_C/OXoFAgAAQBAJ?hl=it&gbpv=0

Translated from English:
https://www.google.ch/books/edition/C++_Fondamenti_di_programmazione/fPaLAwAAQBAJ?hl=it&gbpv=0

Another source from the GNU/Linux world:

PLUTO (Appunti di informatica libera):
http://a2.pluto.it/a292.htm#almltitle3828

-- 
Federico Vaga

Re: [PATCH] Doc:it_IT: Do not reference kernel.h anymore

[Jonathan Corbet]

Federico Vaga <federico.vaga@vaga.pv.it> writes:

>>I'm unconvinced about "file di intestazione" based on my own
>>understanding of the language... but, in a case like this, I will defer
>>to the creator and maintainer of the translation.
>
> Due to my explanation in the previous message, and after your answer,
> I have the feeling it may sounds like I'm making up words needing
> persuasion. Probably I'm misunderstanding. Just in case, please allow
> me a clarification.

No, that was not my intent at all.  It's a term I haven't encountered
before, but that doesn't mean you made it up :)

Thanks,

jon

Re: [PATCH v2 1/1] docs: Update documentation to avoid mentioning of kernel.h

[Andy Shevchenko]

On Mon, Dec 22, 2025 at 03:00:24PM -0700, Jonathan Corbet wrote:
> Andy Shevchenko <andriy.shevchenko@linux.intel.com> writes:
> 
> > For several years, and still ongoing, the kernel.h is being split
> > to smaller and narrow headers to avoid "including everything" approach
> > which is bad in many ways. Since that, documentation missed a few
> > required updates to align with that work. Do it here.
> >
> > Note, language translations are left untouched and if anybody willing
> > to help, please provide path(es) based on the updated English variant.
> >
> > Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
> > Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
> > ---
> >
> > v2: collected tag (Randy), fixed util_macros k-doc (Randy, me), fixed spelling (Randy)
> >
> >  Documentation/core-api/kobject.rst              |  2 +-
> >  Documentation/dev-tools/checkpatch.rst          |  2 +-
> >  Documentation/driver-api/basics.rst             | 17 ++++++++++++++++-
> >  .../driver-api/driver-model/design-patterns.rst |  2 +-
> >  Documentation/process/coding-style.rst          | 10 +++++++---
> >  Documentation/staging/rpmsg.rst                 |  7 +++++--
> >  include/linux/util_macros.h                     |  2 +-
> >  7 files changed, 32 insertions(+), 10 deletions(-)
> 
> Applied (finally) thanks.

Thank you! I leave the translations to the respective maintainers and native
speakers to decide.

-- 
With Best Regards,
Andy Shevchenko