[PATCH] doc:it_IT: align doc-guide translation

[PATCH] doc:it_IT: align doc-guide translation

[Federico Vaga]

Update the Italian translation of Documentation/doc-guide to catch up
with the following upstream commits:

doc-guide/index.rst:
  commit a592a36e4937 ("Documentation: use a source-read extension for the index link boilerplate")
  commit d40981350844 ("doc-guide: add help documentation checktransupdate.rst")

doc-guide/sphinx.rst:
  commit f1c2db1f145b ("docs: move test_doc_build.py to tools/docs")
  commit abd61d1ff8f0 ("scripts: sphinx-pre-install: move it to tools/docs")
  commit 9322af5e6557 ("docs: sphinx: add a file with the requirements for lowest version")
  commit d6d886005d32 ("Docs: doc-guide: update sphinx.rst Sphinx version number")
  commit 5ccab49c104c ("docs: doc-guide: clarify latest theme usage")
  commit b31274d58d21 ("docs: drop the version constraints for sphinx and dependencies")
  commit 40be2369dc0e ("Documentation: multiple .rst files: Fix grammar and more consistent formatting")
  commit 3e893e16af55 ("docs: Raise the minimum Sphinx requirement to 2.4.4")
  commit 86b17aaf2e88 ("docs: automarkup: linkify git revs")
  commit 35d4a3c67eb5 ("docs/doc-guide: Clarify how to write tables")
  commit 26d797ffc1c0 ("docs: update sphinx.rst to reflect the default theme change")
  commit 679b4bc25fc7 ("docs/doc-guide: Add documentation on SPHINX_IMGMATH")
  commit 4d627ef12b40 ("docs/doc-guide: Mention make variable SPHINXDIRS")
  commit 7c43214dddfd ("docs/doc-guide: Add footnote on Inkscape for better images in PDF documents")

doc-guide/kernel-doc.rst:
  commit 827b9458c933 ("docs: kernel-doc.rst: document private: scope propagation")
  commit eba6ffd126cd ("docs: kdoc: move kernel-doc to tools/docs")
  commit 90f1d896d59f ("doc-guide: kernel-doc: specify that W=n does not check header files")
  commit b580fa304c85 ("docs: kernel-doc.rst: document the new "var" kernel-doc markup")
  commit 8deb5d725b48 ("docs: kernel-doc.rst: don't let automarkup mangle with consts")
  commit dd3e817e879c ("doc-guide: kernel-doc: add %CONST examples")
  commit 7e8a8143ecc3 ("docs: add support to build manpages from kerneldoc output")
  commit 9e6c5870bb44 ("Documentation: kernel-doc: enumerate identifier *type*s")
  commit 23a0bc285159 ("doc-guide: kernel-doc: document Returns: spelling")

doc-guide/parse-headers.rst:
  commit 6ae0f2072768 ("docs: parse-headers.rst: Fix a typo")
  commit 68f3d40ea0ce ("docs: parse-headers.rst: remove uneeded parenthesis")
  commit d69a03a97a2d ("docs: doc-guide: parse-headers.rst update its documentation")

Also add the translations for the following pages, which had none:

doc-guide/contributing.rst:
  commit d96574b0b49d ("Add a document on how to contri

doc-guide/maintainer-profile.rst:
  commit 53b7f3aa411b ("Add a maintainer entry profile for documentation")

doc-guide/checktransupdate.rst:
  commit d40981350844 ("doc-guide: add help documentation checktransupdate.rst")

Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
---
 .../it_IT/doc-guide/checktransupdate.rst      |  59 ++++
 .../it_IT/doc-guide/contributing.rst          | 319 ++++++++++++++++++
 .../translations/it_IT/doc-guide/index.rst    |  13 +-
 .../it_IT/doc-guide/kernel-doc.rst            |  88 +++--
 .../it_IT/doc-guide/maintainer-profile.rst    |  60 ++++
 .../it_IT/doc-guide/parse-headers.rst         | 220 ++++++------
 .../translations/it_IT/doc-guide/sphinx.rst   | 178 +++++++---
 7 files changed, 757 insertions(+), 180 deletions(-)
 create mode 100644 Documentation/translations/it_IT/doc-guide/checktransupdate.rst
 create mode 100644 Documentation/translations/it_IT/doc-guide/contributing.rst
 create mode 100644 Documentation/translations/it_IT/doc-guide/maintainer-profile.rst

diff --git a/Documentation/translations/it_IT/doc-guide/checktransupdate.rst b/Documentation/translations/it_IT/doc-guide/checktransupdate.rst
new file mode 100644
index 000000000000..5171c24e8b52
--- /dev/null
+++ b/Documentation/translations/it_IT/doc-guide/checktransupdate.rst
@@ -0,0 +1,59 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-ita.rst
+
+Verificare la necessità di aggiornare le traduzioni
+===================================================
+
+Questo script aiuta a tracciare lo stato delle traduzioni della
+documentazione nelle diverse lingue, ovvero se la documentazione è
+allineata con la controparte inglese.
+
+Come funziona
+-------------
+
+Lo script usa il comando ``git log`` per individuare l'ultimo commit in inglese
+a partire dal commit della traduzione (in ordine di data dell'autore) e gli
+ultimi commit in inglese a partire da HEAD. Se emergono delle differenze, il
+file viene considerato non aggiornato, e vengono quindi raccolti e segnalati i
+commit che necessitano di un aggiornamento.
+
+Funzionalità implementate
+
+-  verifica di tutti i file in una determinata lingua
+-  verifica di un singolo file o di un insieme di file
+-  opzioni per modificare il formato dell'output
+-  tracciamento dello stato di traduzione dei file che non hanno alcuna
+   traduzione
+
+Utilizzo
+--------
+
+::
+
+   tools/docs/checktransupdate.py --help
+
+Fate riferimento all'output del messaggio d'aiuto per i dettagli sull'utilizzo.
+
+Esempi
+
+-  ``tools/docs/checktransupdate.py -l zh_CN``
+   Questo stamperà tutti i file che necessitano di un aggiornamento nella
+   lingua zh_CN.
+-  ``tools/docs/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst``
+   Questo stamperà solamente lo stato del file specificato.
+
+L'output sarà quindi qualcosa del genere:
+
+::
+
+    Documentation/dev-tools/kfence.rst
+    No translation in the locale of zh_CN
+
+    Documentation/translations/zh_CN/dev-tools/testing-overview.rst
+    commit 42fb9cfd5b18 ("Documentation: dev-tools: Add link to RV docs")
+    1 commits needs resolving in total
+
+Funzionalità ancora da implementare
+
+- specificare cartelle in aggiunta ai singoli file
diff --git a/Documentation/translations/it_IT/doc-guide/contributing.rst b/Documentation/translations/it_IT/doc-guide/contributing.rst
new file mode 100644
index 000000000000..b6bb3fae22d7
--- /dev/null
+++ b/Documentation/translations/it_IT/doc-guide/contributing.rst
@@ -0,0 +1,319 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-ita.rst
+
+Come contribuire al miglioramento della documentazione del kernel
+=================================================================
+
+La documentazione è una parte importante di ogni progetto di sviluppo
+software. Una buona documentazione aiuta ad attirare nuovi sviluppatori e
+permette a quelli già presenti di lavorare in modo più efficace. Senza una
+documentazione di qualità, si spreca molto tempo nel decifrare il codice a
+ritroso e si commettono errori altrimenti evitabili.
+
+Sfortunatamente, al momento la documentazione del kernel è ben lontana da
+quello che dovrebbe essere per sostenere un progetto di queste dimensioni e
+importanza.
+
+Questa guida è per chi vuole contribuire a migliorare questa situazione. I
+miglioramenti alla documentazione del kernel possono essere fatti da
+sviluppatori con diversi livelli di esperienza; sono un modo relativamente
+semplice per imparare il processo di sviluppo del kernel in generale e
+trovare il proprio posto nella comunità. Quello che segue è, per la maggior
+parte, l'elenco dei compiti che il manutentore della documentazione ritiene
+più urgenti.
+
+Le cose da fare nella documentazione
+------------------------------------
+
+C'è un elenco infinito di compiti da svolgere per portare la nostra
+documentazione al livello in cui dovrebbe essere. Questo elenco contiene
+alcuni punti importanti, ma è lungi dall'essere esaustivo; se trovate un
+modo diverso per migliorare la documentazione, non esitate!
+
+Correzione degli avvisi
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Al momento, la generazione della documentazione produce un numero
+incredibile di avvisi. Quando ce ne sono così tanti, è come se non ce ne
+fosse nessuno: le persone li ignorano e non si accorgeranno mai quando il
+loro lavoro ne aggiunge di nuovi. Per questo motivo, eliminare gli avvisi è
+uno dei compiti a più alta priorità nell'elenco delle cose da fare per la
+documentazione. Il compito in sé è ragionevolmente semplice, ma va
+affrontato nel modo giusto per avere successo.
+
+Gli avvisi emessi da un compilatore per il codice C possono spesso essere
+scartati come falsi positivi, portando a patch il cui unico scopo è zittire
+il compilatore. Gli avvisi generati dalla documentazione, invece, indicano
+quasi sempre un problema reale; farli sparire richiede di comprendere il
+problema e correggerlo alla radice. Per questo motivo, le patch che
+correggono avvisi nella documentazione non dovrebbero limitarsi a dire "fix
+a warning" nel titolo del changelog; dovrebbero invece indicare il problema
+reale che è stato corretto.
+
+Un altro punto importante è che gli avvisi nella documentazione sono spesso
+generati da problemi nei commenti kerneldoc all'interno del codice C. Anche se
+il manutentore della documentazione apprezza l'essere messo in copia sulle
+correzioni di questo tipo, in realtà spesso rivolgersi al sottosistema di
+documentazione non è il modo migliore di apportare queste modifiche; queste
+dovrebbero invece essere inviate al manutentore del sottosistema in questione.
+
+Per esempio, in una generazione della documentazione ho preso, quasi a
+caso, un paio di avvisi::
+
+  ./drivers/devfreq/devfreq.c:1818: warning: bad line:
+  	- Resource-managed devfreq_register_notifier()
+  ./drivers/devfreq/devfreq.c:1854: warning: bad line:
+	- Resource-managed devfreq_unregister_notifier()
+
+(Le righe sono state divise per essere più leggibili).
+
+Una rapida occhiata al file sorgente indicato sopra ha rivelato un paio di
+commenti kerneldoc con questo aspetto::
+
+  /**
+   * devm_devfreq_register_notifier()
+	  - Resource-managed devfreq_register_notifier()
+   * @dev:	The devfreq user device. (parent of devfreq)
+   * @devfreq:	The devfreq object.
+   * @nb:		The notifier block to be unregistered.
+   * @list:	DEVFREQ_TRANSITION_NOTIFIER.
+   */
+
+Il problema è l'asterisco mancante, che confonde l'idea semplicistica che il
+sistema di generazione abbia idea di come debba essere fatto un blocco di
+commento C. Questo problema era presente fin da quando quel commento venne
+aggiunto nel 2016, quindi da diversi anni. Correggerlo è stata solo questione di
+aggiungere gli asterischi mancanti. Una rapida occhiata alla cronologia di quel
+file ha mostrato quale fosse il formato usuale per la riga dell'oggetto, e
+``scripts/get_maintainer.pl`` mi ha detto chi dovesse riceverla (basta passare
+il percorso delle vostre patch come argomento a scripts/get_maintainer.pl). La
+patch risultante era questa::
+
+  [PATCH] PM / devfreq: Fix two malformed kerneldoc comments
+
+  Two kerneldoc comments in devfreq.c fail to adhere to the required format,
+  resulting in these doc-build warnings:
+
+    ./drivers/devfreq/devfreq.c:1818: warning: bad line:
+  	  - Resource-managed devfreq_register_notifier()
+    ./drivers/devfreq/devfreq.c:1854: warning: bad line:
+	  - Resource-managed devfreq_unregister_notifier()
+
+  Add a couple of missing asterisks and make kerneldoc a little happier.
+
+  Signed-off-by: Jonathan Corbet <corbet@lwn.net>
+  ---
+   drivers/devfreq/devfreq.c | 4 ++--
+   1 file changed, 2 insertions(+), 2 deletions(-)
+
+  diff --git a/drivers/devfreq/devfreq.c b/drivers/devfreq/devfreq.c
+  index 57f6944d65a6..00c9b80b3d33 100644
+  --- a/drivers/devfreq/devfreq.c
+  +++ b/drivers/devfreq/devfreq.c
+  @@ -1814,7 +1814,7 @@ static void devm_devfreq_notifier_release(struct device *dev, void *res)
+
+   /**
+    * devm_devfreq_register_notifier()
+  -	- Resource-managed devfreq_register_notifier()
+  + *	- Resource-managed devfreq_register_notifier()
+    * @dev:	The devfreq user device. (parent of devfreq)
+    * @devfreq:	The devfreq object.
+    * @nb:		The notifier block to be unregistered.
+  @@ -1850,7 +1850,7 @@ EXPORT_SYMBOL(devm_devfreq_register_notifier);
+
+   /**
+    * devm_devfreq_unregister_notifier()
+  -	- Resource-managed devfreq_unregister_notifier()
+  + *	- Resource-managed devfreq_unregister_notifier()
+    * @dev:	The devfreq user device. (parent of devfreq)
+    * @devfreq:	The devfreq object.
+    * @nb:		The notifier block to be unregistered.
+  --
+  2.24.1
+
+L'intero procedimento ha richiesto solo pochi minuti. Naturalmente, ho poi
+scoperto che qualcun altro l'aveva già corretto in un altro albero,
+mettendo in luce un'altra lezione: controllate sempre linux-next per
+vedere se un problema è già stato risolto prima di mettervici sopra.
+
+Altre correzioni richiederanno più tempo, specialmente quelle relative ai
+campi di una struttura o ai parametri di una funzione privi di
+documentazione. In questi casi, è necessario capire quale sia il ruolo di
+questi campi o parametri e descriverli correttamente. Nel complesso, questo
+compito diventa un po' tedioso a volte, ma è molto importante. Se riusciamo
+davvero ad eliminare gli avvisi dalla generazione della documentazione,
+allora potremo iniziare a pretendere che gli sviluppatori evitino di
+aggiungerne di nuovi.
+
+Oltre ai normali avvisi durante la generazione della documentazione, potete
+ottenerne di più eseguendo ``make refcheckdocs`` per trovare riferimenti a file
+di documentazione inesistenti.
+
+Commenti kerneldoc dimenticati
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Gli sviluppatori sono incoraggiati a scrivere commenti kerneldoc per il
+loro codice, ma molti di questi commenti non vengono mai inclusi nella
+generazione della documentazione. Questo rende tale informazione più
+difficile da trovare e, per esempio, impedisce a Sphinx di generare
+collegamenti verso quella documentazione. Aggiungere le direttive
+``kernel-doc`` alla documentazione per includere quei commenti può aiutare
+la comunità a ottenere il pieno valore del lavoro speso per crearli.
+
+Lo strumento ``tools/docs/find-unused-docs.sh`` può essere usato per
+trovare questi commenti dimenticati.
+
+Da notare che il valore maggiore deriva dall'includere la documentazione
+per le funzioni e le strutture dati esportate. Molti sottosistemi hanno
+anche commenti kerneldoc per uso interno; questi non dovrebbero essere
+inclusi nella generazione della documentazione a meno che non vengano
+posti in un documento specificamente rivolto agli sviluppatori che
+lavorano all'interno del sottosistema in questione.
+
+
+Correzione dei refusi
+~~~~~~~~~~~~~~~~~~~~~
+
+Correggere errori di battitura o di formattazione nella documentazione è
+un modo rapido per imparare come creare e inviare patch, ed è un servizio
+utile. Sono sempre disposto ad accettare questo tipo di patch. Detto
+questo, una volta che ne avete corretti alcuni, considerate di passare a
+compiti più avanzati, lasciando qualche refuso per il prossimo principiante
+che vorrà occuparsene.
+
+Da notare che alcune cose *non* sono refusi e non dovrebbero essere
+"corrette":
+
+ - Sia la grafia americana che quella britannica dell'inglese sono
+   ammesse nella documentazione del kernel. Non c'è bisogno di sostituire
+   l'una con l'altra.
+
+ - La questione se un punto debba essere seguito da uno o due spazi non
+   va dibattuta nel contesto della documentazione del kernel. Anche
+   altri argomenti di legittimo disaccordo, come la "virgola di Oxford",
+   non sono pertinenti qui.
+
+Come per qualsiasi patch a qualsiasi progetto, considerate se la vostra
+modifica sta davvero migliorando le cose.
+
+Documentazione datata
+~~~~~~~~~~~~~~~~~~~~~
+
+Parte della documentazione del kernel è attuale, mantenuta e utile.
+Un'altra parte... non lo è. Documentazione impolverata, vecchia e
+imprecisa può fuorviare i lettori e gettare discredito sulla nostra
+documentazione nel suo complesso. Qualsiasi cosa si possa fare per
+affrontare questi problemi è più che benvenuta.
+
+Ogni volta che lavorate su un documento, considerate se è attuale, se ha
+bisogno di essere aggiornato, o se forse dovrebbe essere rimosso del
+tutto. Ci sono alcuni segnali d'allarme a cui potete prestare attenzione:
+
+ - Riferimenti a kernel della serie 2.x
+ - Rimandi a repositori su SourceForge
+ - Nella cronologia, negli ultimi anni, solo correzioni di refusi
+ - Discussioni su modi di lavorare precedenti a Git
+
+La cosa migliore da fare, ovviamente, sarebbe portare la documentazione a
+essere attuale, aggiungendo qualsiasi informazione necessaria. Un lavoro
+simile spesso richiede la collaborazione di sviluppatori che conoscono bene
+il sottosistema in questione. Gli sviluppatori, quando viene chiesto loro
+gentilmente, e quando le loro risposte vengono ascoltate e messe in
+pratica, sono spesso più che disposti a collaborare con chi lavora per
+migliorare la documentazione.
+
+Alcuni documenti sono senza speranza; a volte troviamo documenti che fanno
+riferimento a codice rimosso dal kernel molto tempo fa, per esempio. C'è
+una sorprendente resistenza a rimuovere la documentazione obsoleta, ma
+dovremmo farlo comunque. Il materiale superfluo nella nostra documentazione
+non è d'aiuto a nessuno.
+
+Nei casi in cui, forse, ci sono informazioni utili in un documento
+gravemente datato, e non siete in grado di aggiornarlo, la cosa migliore
+da fare potrebbe essere aggiungere un avviso all'inizio. Si raccomanda il
+seguente testo::
+
+  .. warning ::
+  	This document is outdated and in need of attention.  Please use
+	this information with caution, and please consider sending patches
+	to update it.
+
+In questo modo, almeno i nostri pazientissimi lettori sono stati avvisati
+che il documento potrebbe portarli fuori strada.
+
+Coerenza della documentazione
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+I veterani di qui ricorderanno i libri su Linux che comparvero sugli
+scaffali negli anni '90. Erano semplicemente raccolte di file di
+documentazione racimolati da varie fonti in rete. I libri sono (per lo
+più) migliorati da allora, ma la documentazione del kernel è ancora per lo
+più costruita su quel modello. Sono migliaia di file, quasi ognuno dei
+quali è stato scritto in isolamento da tutti gli altri. Non abbiamo un
+corpo coerente di documentazione del kernel; abbiamo migliaia di documenti
+individuali.
+
+Abbiamo cercato di migliorare la situazione creando un insieme di "libri"
+che raggruppano la documentazione per specifici lettori. Questi
+includono:
+
+ - Documentation/admin-guide/index.rst
+ - Documentation/core-api/index.rst
+ - Documentation/driver-api/index.rst
+ - Documentation/userspace-api/index.rst
+
+Così come questo libro sulla documentazione stessa.
+
+Spostare i documenti nei libri appropriati è un compito importante e deve
+continuare. Ci sono, tuttavia, un paio di sfide associate a questo lavoro.
+Spostare i file della documentazione, nel breve termine, infastidisce chi vi
+lavora; comprensibilmente, non sono entusiasti di questi cambiamenti. Di solito
+li si può convincere a spostarli una volta; tuttavia, non vogliamo continuare a
+spostarli in giro.
+
+Anche quando tutti i documenti sono al posto giusto, però, siamo solo
+riusciti a trasformare un grande cumulo in un gruppo di cumuli più
+piccoli. Il lavoro di cercare di tessere insieme tutti quei documenti in
+un unico insieme non è ancora iniziato. Se avete idee brillanti su come
+potremmo procedere su questo fronte, saremmo più che felici di sentirle.
+
+Miglioramenti al foglio di stile
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Con l'adozione di Sphinx abbiamo un output HTML dall'aspetto molto più gradevole
+di quanto avessimo un tempo. Ma è ancora migliorabile; Donald Knuth e Edward
+Tufte non ne sarebbero impressionati. Questo richiede di modificare i nostri
+fogli di stile per creare un output tipograficamente più solido, accessibile e
+leggibile.
+
+Attenzione: se vi assumete questo compito, vi state addentrando nel
+classico territorio del "bikeshed". Aspettatevi molte opinioni e
+discussioni anche per cambiamenti relativamente ovvi. Questa è, ahimè, la
+natura del mondo in cui viviamo.
+
+Generazione di PDF senza LaTeX
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Questo è un compito decisamente non banale per qualcuno con molto tempo a
+disposizione e competenze in Python. La catena di strumenti di Sphinx è
+relativamente piccola e ben contenuta; è facile da aggiungere a un sistema
+di sviluppo. Ma generare output in PDF o EPUB richiede l'installazione di
+LaTeX, che non è affatto piccolo o ben contenuto. Sarebbe una bella cosa
+da eliminare.
+
+La speranza originale era di usare lo strumento rst2pdf (https://rst2pdf.org/)
+per la generazione dei PDF, ma si è scoperto che non era all'altezza del
+compito. Il lavoro di sviluppo su rst2pdf sembra però essere ripreso di recente,
+il che è un segno di speranza. Se uno sviluppatore adeguatamente motivato lo
+migliorasse per far funzionare rst2pdf con la documentazione del kernel, il
+mondo gli sarebbe eternamente grato.
+
+Scrivere più documentazione
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Naturalmente, ci sono vaste parti del kernel che sono gravemente prive di
+documentazione. Se avete la conoscenza per documentare uno specifico
+sottosistema del kernel e il desiderio di farlo, non esitate a scrivere e
+inviare il lavoro al kernel. Un numero incalcolabile di
+sviluppatori e utenti del kernel vi ringrazierà.
diff --git a/Documentation/translations/it_IT/doc-guide/index.rst b/Documentation/translations/it_IT/doc-guide/index.rst
index 9fffff626711..04df7e550f6b 100644
--- a/Documentation/translations/it_IT/doc-guide/index.rst
+++ b/Documentation/translations/it_IT/doc-guide/index.rst
@@ -1,8 +1,5 @@
 .. include:: ../disclaimer-ita.rst
 
-.. note:: Per leggere la documentazione originale in inglese:
-	  :ref:`Documentation/doc-guide/index.rst <doc_guide>`
-
 .. _it_doc_guide:
 
 ==========================================
@@ -15,10 +12,6 @@ Come scrivere la documentazione del kernel
    sphinx
    kernel-doc
    parse-headers
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
+   contributing
+   maintainer-profile
+   checktransupdate
diff --git a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
index bac959b8b7b9..7e8981d5f464 100644
--- a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
+++ b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
@@ -1,12 +1,7 @@
 .. include:: ../disclaimer-ita.rst
 
-.. note:: Per leggere la documentazione originale in inglese:
-	  :ref:`Documentation/doc-guide/index.rst <doc_guide>`
-
 .. title:: Commenti in kernel-doc
 
-.. _it_kernel_doc:
-
 =================================
 Scrivere i commenti in kernel-doc
 =================================
@@ -82,11 +77,15 @@ che questo produca alcuna documentazione. Per esempio::
 
 	tools/docs/kernel-doc -v -none drivers/foo/bar.c
 
-Il formato della documentazione è verificato della procedura di generazione
-del kernel quando viene richiesto di effettuare dei controlli extra con GCC::
+Il formato della documentazione dei file ``.c`` è verificato anche dalla
+procedura di generazione del kernel quando viene richiesto di effettuare dei
+controlli extra con GCC::
 
 	make W=n
 
+Tuttavia, il comando precedente non verifica i file d'intestazione. Questi
+devono essere controllati separatamente utilizzando ``kernel-doc``.
+
 Documentare le funzioni
 ------------------------
 
@@ -172,7 +171,7 @@ Valore di ritorno
 ~~~~~~~~~~~~~~~~~
 
 Il valore di ritorno, se c'è, viene descritto in una sezione dedicata di nome
-``Return``.
+``Return`` (o ``Returns``).
 
 .. note::
 
@@ -202,7 +201,8 @@ Il valore di ritorno, se c'è, viene descritto in una sezione dedicata di nome
 Documentare strutture, unioni ed enumerazioni
 ---------------------------------------------
 
-Generalmente il formato di un commento kernel-doc per struct, union ed enum è::
+Generalmente il formato di un commento kernel-doc per ``struct``, ``union``
+ed ``enum`` è::
 
   /**
    * struct struct_name - Brief description.
@@ -237,6 +237,10 @@ Le etichette ``private:`` e ``public:`` devono essere messe subito dopo
 il marcatore di un commento ``/*``. Opzionalmente, possono includere commenti
 fra ``:`` e il marcatore di fine commento ``*/``.
 
+Quando ``private:`` viene usata su strutture annidate, si propaga solo alle
+strutture/unioni interne.
+
+
 Esempio::
 
   /**
@@ -280,13 +284,15 @@ Strutture ed unioni annidate
         union {
           struct {
             int memb1;
+            /* private: nasconde memb2 dalla documentazione */
             int memb2;
-        }
+          };
+          /* Qui torna tutto pubblico, l'ambito private è terminato */
           struct {
             void *memb3;
             int memb4;
-          }
-        }
+          };
+        };
         union {
           struct {
             int memb1;
@@ -366,10 +372,23 @@ Anche i tipi di dato per prototipi di funzione possono essere documentati::
    * Description of the type.
    *
    * Context: Locking context.
-   * Return: Meaning of the return value.
+   * Returns: Meaning of the return value.
    */
    typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);
 
+Documentazione delle variabili
+-------------------------------
+
+Generalmente il formato di un commento kernel-doc per una variabile è
+il seguente::
+
+  /**
+   * var var_name - Brief description.
+   *
+   * Description of the var_name variable.
+   */
+   extern int var_name;
+
 Documentazione di macro simili a oggetti
 ----------------------------------------
 
@@ -433,6 +452,10 @@ del `dominio Sphinx per il C`_.
 ``%CONST``
   Il nome di una costante (nessun riferimento, solo formattazione)
 
+  Esempi::
+
+    %0    %NULL    %-1    %-EFAULT    %-EINVAL    %-ENOMEM
+
 ````literal````
   Un blocco di testo che deve essere riportato così com'è. La rappresentazione
   finale utilizzerà caratteri a ``spaziatura fissa``.
@@ -484,15 +507,22 @@ la seguente sintassi::
   See :c:func:`my custom link text for function foo <foo>`.
   See :c:type:`my custom link text for struct bar <bar>`.
 
+Per ulteriori dettagli, consultate la documentazione del `dominio Sphinx per
+il C`_.
+
+.. note::
+   Le variabili non vengono automaticamente collegate tramite riferimenti
+   incrociati. Per queste, dovete aggiungere esplicitamente un riferimento
+   incrociato del dominio C.
 
 Commenti per una documentazione generale
 ----------------------------------------
 
 Al fine d'avere il codice ed i commenti nello stesso file, potete includere
 dei blocchi di documentazione kernel-doc con un formato libero invece
-che nel formato specifico per funzioni, strutture, unioni, enumerati o tipi
-di dato. Per esempio, questo tipo di commento potrebbe essere usato per la
-spiegazione delle operazioni di un driver o di una libreria
+che nel formato specifico per funzioni, strutture, unioni, enumerati, tipi
+di dato o variabili. Per esempio, questo tipo di commento potrebbe essere
+usato per la spiegazione delle operazioni di un driver o di una libreria
 
 Questo s'ottiene utilizzando la parola chiave ``DOC:`` a cui viene associato
 un titolo.
@@ -565,6 +595,8 @@ identifiers: *[ function/type ...]*
   Include la documentazione per ogni *function* e *type*  in *source*.
   Se non vengono esplicitamente specificate le funzioni da includere, allora
   verranno incluse tutte quelle disponibili in *source*.
+  *type* può essere un identificatore di tipo ``struct``, ``union``,
+  ``enum``, ``typedef`` o ``var``.
 
   Esempi::
 
@@ -601,7 +633,25 @@ dai file sorgenti.
 Come utilizzare kernel-doc per generare pagine man
 --------------------------------------------------
 
-Se volete utilizzare kernel-doc solo per generare delle pagine man, potete
-farlo direttamente dai sorgenti del kernel::
+Per generare le pagine man di tutti i file che contengono marcatori
+kernel-doc, eseguite::
+
+  $ make mandocs
+
+Oppure, chiamando direttamente ``script-build-wrapper``::
+
+  $ ./tools/docs/sphinx-build-wrapper mandocs
+
+Il risultato sarà disponibile nella cartella ``/man`` dentro la cartella
+di output (predefinita: ``Documentation/output``).
+
+Opzionalmente, è possibile generare un sottoinsieme di pagine man usando
+SPHINXDIRS:
+
+  $ make SPHINXDIRS=driver-api/media mandocs
+
+.. note::
 
-  $ tools/docs/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man
+   Quando si usa SPHINXDIRS={subdir}, verranno generate le pagine man solo
+   per i file che si trovano esplicitamente all'interno di un file
+   ``Documentation/{subdir}/.../*.rst``.
diff --git a/Documentation/translations/it_IT/doc-guide/maintainer-profile.rst b/Documentation/translations/it_IT/doc-guide/maintainer-profile.rst
new file mode 100644
index 000000000000..02eb9d1c796c
--- /dev/null
+++ b/Documentation/translations/it_IT/doc-guide/maintainer-profile.rst
@@ -0,0 +1,60 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-ita.rst
+
+Profilo del manutentore del sottosistema di documentazione
+==========================================================
+
+Il "sottosistema" della documentazione è il punto di coordinamento
+centrale per la documentazione del kernel e la relativa infrastruttura.
+Copre la gerarchia sotto Documentation/ (con l'eccezione di
+Documentation/devicetree), diverse utilità sotto scripts/ e, almeno in
+parte, LICENSES/.
+
+Vale la pena notare, però, che i confini di questo sottosistema sono più sfumati
+del normale. Molti altri manutentori di sottosistemi preferiscono mantenere il
+controllo di alcune parti di Documentation/, e molti altri ancora vi applicano
+liberamente delle modifiche quando è conveniente. Oltre a ciò, buona parte della
+documentazione del kernel si trova nel codice sorgente sotto forma di commenti
+kerneldoc; questi sono solitamente (ma non sempre) mantenuti dal manutentore del
+sottosistema pertinente.
+
+La lista di discussione per la documentazione è linux-doc@vger.kernel.org.
+Le patch dovrebbero essere inviate contro l'albero docs-next quando
+possibile.
+
+Aggiunta alla checklist di invio
+--------------------------------
+
+Quando si apportano modifiche alla documentazione, dovreste generare
+effettivamente la documentazione e assicurarvi che non siano stati
+introdotti nuovi errori o avvisi. Generare i documenti in HTML e osservare
+il risultato aiuterà a evitare fraintendimenti spiacevoli su come le cose
+verranno rappresentate.
+
+Tutta la nuova documentazione (incluse le aggiunte a documenti esistenti)
+dovrebbe idealmente giustificare, da qualche parte nel changelog, chi sia
+il pubblico a cui è destinata; in questo modo, ci assicuriamo che la
+documentazione finisca nel posto giusto. Alcune categorie possibili
+sono: sviluppatori del kernel (esperti o principianti), programmatori
+dello spazio utente, utenti finali e/o amministratori di sistema, e
+distributori.
+
+Date chiave del ciclo
+---------------------
+
+Le patch possono essere inviate in qualsiasi momento, ma la risposta sarà
+più lenta del solito durante la finestra d'integrazione. L'albero della
+documentazione tende a chiudersi tardi, prima dell'apertura della finestra
+d'integrazione, poiché il rischio di regressioni dovute a patch sulla
+documentazione è basso.
+
+Cadenza di revisione
+--------------------
+
+Sono (Jonathan Corbet) l'unico manutentore del sottosistema di documentazione, e
+svolgo questo lavoro nel mio tempo libero, quindi la risposta alle patch sarà a
+volte lenta. Cerco sempre di inviare una notifica quando una patch viene
+integrata (o quando decido che non può esserlo). Non esitate a inviare un
+sollecito se non avete ricevuto risposta entro una settimana dall'invio di una
+patch.
diff --git a/Documentation/translations/it_IT/doc-guide/parse-headers.rst b/Documentation/translations/it_IT/doc-guide/parse-headers.rst
index b0caa40fe1e9..9276b9ebe9bd 100644
--- a/Documentation/translations/it_IT/doc-guide/parse-headers.rst
+++ b/Documentation/translations/it_IT/doc-guide/parse-headers.rst
@@ -1,195 +1,195 @@
 .. include:: ../disclaimer-ita.rst
 
-:Original: Documentation/doc-guide/index.rst
-
-=========================================
-Includere gli i file di intestazione uAPI
-=========================================
+=====================================
+Includere i file di intestazione uAPI
+=====================================
 
 Qualche volta è utile includere dei file di intestazione e degli esempi di codice C
 al fine di descrivere l'API per lo spazio utente e per generare dei riferimenti
 fra il codice e la documentazione. Aggiungere i riferimenti ai file dell'API
-dello spazio utente ha ulteriori vantaggi: Sphinx genererà dei messaggi
+dello spazio utente ha un ulteriore vantaggio: Sphinx genererà dei messaggi
 d'avviso se un simbolo non viene trovato nella documentazione. Questo permette
 di mantenere allineate la documentazione della uAPI (API spazio utente)
 con le modifiche del kernel.
-Il programma :ref:`parse_headers.py <it_parse_headers>` genera questi riferimenti.
-Esso dev'essere invocato attraverso un Makefile, mentre si genera la
-documentazione. Per avere un esempio su come utilizzarlo all'interno del kernel
-consultate ``Documentation/userspace-api/media/Makefile``.
+Il programma :ref:`parse_headers.py <it_parse_headers>` genera questi
+riferimenti. Esso dev'essere invocato attraverso un Makefile, mentre si genera
+la documentazione. Per avere un esempio su come utilizzarlo all'interno del
+kernel consultate ``Documentation/userspace-api/media/Makefile``.
 
 .. _it_parse_headers:
 
-parse_headers.py
-^^^^^^^^^^^^^^^^
+tools/docs/parse_headers.py
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 NOME
 ****
 
+parse_headers.py - analizza un file C al fine di identificare funzioni,
+strutture, enumerati e definizioni, e creare riferimenti per un libro Sphinx.
 
-parse_headers.py - analizza i file C al fine di identificare funzioni,
-strutture, enumerati e definizioni, e creare riferimenti per Sphinx
+USO
+***
 
-SINTASSI
-********
+parse-headers.py [-h] [-d] [-t] ``FILE_IN`` ``FILE_OUT`` ``FILE_RULES``
 
+SINOSSI
+*******
 
-\ **parse_headers.py**\  [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
+Converte un file d'intestazione o un file sorgente C ``FILE_IN`` in un testo
+ReStructured Text incluso mediante il blocco ..parsed-literal con riferimenti
+alla documentazione che descrive l'API. Accetta opzionalmente un file
+``FILE_RULES`` che descrive quali elementi debbano essere ignorati o il cui
+riferimento debba puntare ad un tipo/nome diverso da quello predefinito.
 
-Dove <options> può essere: --debug, --usage o --help.
+Il file generato viene scritto in ``FILE_OUT``.
 
+Il programma è capace di identificare ``define``, ``struct``, ``typedef``,
+``enum`` e ``symbol`` di un enumerato, creando i riferimenti per ognuno di
+loro.
 
-OPZIONI
-*******
+Inoltre, esso è capace di distinguere le ``#define`` utilizzate per
+specificare le macro specifiche di Linux usate per definire gli ``ioctl``.
 
+Il file ``FILE_RULES``, opzionale, contiene un insieme di regole come le
+seguenti::
 
+    ignore ioctl VIDIOC_ENUM_FMT
+    replace ioctl VIDIOC_DQBUF vidioc_qbuf
+    replace define V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ :c:type:`v4l2_event_motion_det`
 
-\ **--debug**\
+ARGOMENTI POSIZIONALI
+*********************
 
- Lo script viene messo in modalità verbosa, utile per il debugging.
+  ``FILE_IN``
+      File C d'ingresso
 
+  ``FILE_OUT``
+      File RST generato
 
-\ **--usage**\
+  ``FILE_RULES``
+      File delle eccezioni (opzionale)
 
- Mostra un messaggio d'aiuto breve e termina.
-
-
-\ **--help**\
+OPZIONI
+*******
 
- Mostra un messaggio d'aiuto dettagliato e termina.
+  ``-h``, ``--help``
+      mostra un messaggio d'aiuto e termina
+  ``-d``, ``--debug``
+      aumenta il livello di debug. Può essere usato più volte
+  ``-t``, ``--toc``
+      invece di un blocco letterale, genera nel file RST una tabella
+      dell'indice (TOC)
 
 
 DESCRIZIONE
 ***********
 
-Converte un file d'intestazione o un file sorgente C (C_FILE) in un testo
-reStructuredText incluso mediante il blocco ..parsed-literal
-con riferimenti alla documentazione che descrive l'API. Opzionalmente,
-il programma accetta anche un altro file (EXCEPTIONS_FILE) che
-descrive quali elementi debbano essere ignorati o il cui riferimento
-deve puntare ad elemento diverso dal predefinito.
-
-Il file generato sarà disponibile in (OUT_FILE).
-
-Il programma è capace di identificare *define*, funzioni, strutture,
-tipi di dato, enumerati e valori di enumerati, e di creare i riferimenti
-per ognuno di loro. Inoltre, esso è capace di distinguere le #define
-utilizzate per specificare i comandi ioctl di Linux.
-
-Il file EXCEPTIONS_FILE contiene due tipi di dichiarazioni:
-\ **ignore**\  o \ **replace**\ .
-
-La sintassi per ignore è:
-
-ignore \ **tipo**\  \ **nome**\
-
-La dichiarazione \ **ignore**\  significa che non verrà generato alcun
-riferimento per il simbolo \ **name**\  di tipo \ **tipo**\ .
+Crea, a partire da ``FILE_IN``, una versione arricchita di un file
+d'intestazione del kernel con collegamenti incrociati verso ogni tipo di
+struttura dati C, formattandola con la notazione reStructuredText, sia
+come blocco letterale che come tabella dell'indice.
 
+Accetta opzionalmente un file ``FILE_RULES`` che descrive quali elementi
+debbano essere ignorati o il cui riferimento debba puntare ad un valore
+diverso da quello predefinito, e che può opzionalmente definire lo spazio
+dei nomi C da utilizzare.
 
-La sintassi per replace è:
+Ha lo scopo di permettere una documentazione più completa, in cui i file
+d'intestazione della uAPI creino collegamenti incrociati verso il codice.
 
-replace \ **tipo**\  \ **nome**\  \ **nuovo_valore**\
+Il file generato viene scritto in ``FILE_OUT``.
 
-La dichiarazione \ **replace**\  significa che verrà generato un
-riferimento per il simbolo \ **name**\ di tipo \ **tipo**\ , ma, invece
-di utilizzare il valore predefinito, verrà utilizzato il valore
-\ **nuovo_valore**\ .
+Il file ``FILE_RULES`` può contenere tre tipi di dichiarazioni:
+**ignore**, **replace** e **namespace**.
 
-Per entrambe le dichiarazioni, il \ **tipo**\  può essere uno dei seguenti:
+Per impostazione predefinita, vengono create regole per tutti i simboli e
+le definizioni, ma è anche possibile fornire un file di eccezioni. Questo
+file contiene un insieme di regole che seguono la sintassi descritta di
+seguito:
 
+1. Regole ignore:
 
-\ **ioctl**\
+    ignore *tipo* *simbolo*
 
- La dichiarazione ignore o replace verrà applicata su definizioni di ioctl
- come la seguente:
+Rimuove il simbolo dalla generazione dei riferimenti.
 
- #define	VIDIOC_DBG_S_REGISTER 	 _IOW('V', 79, struct v4l2_dbg_register)
+2. Regole replace:
 
+    replace *tipo* *vecchio_simbolo* *nuovo_riferimento*
 
+    Sostituisce *vecchio_simbolo* con *nuovo_riferimento*.
+    *nuovo_riferimento* può essere:
 
-\ **define**\
+    - un semplice nome di simbolo;
+    - un riferimento Sphinx completo.
 
- La dichiarazione ignore o replace verrà applicata su una qualsiasi #define
- trovata in C_FILE.
+3. Regole namespace
 
+    namespace *spazio_dei_nomi*
 
+    Imposta lo *spazio_dei_nomi* C da utilizzare durante la generazione dei
+    riferimenti incrociati. Può essere sovrascritto dalle regole replace.
 
-\ **typedef**\
+Nelle regole ignore e replace, *tipo* può essere:
 
- La dichiarazione ignore o replace verrà applicata ad una dichiarazione typedef
- in C_FILE.
+    - ioctl:
+        per le definizioni della forma ``_IO*``, per esempio le definizioni
+        di ioctl
 
+    - define:
+        per le altre definizioni
 
+    - symbol:
+        per i simboli definiti all'interno di enumerati;
 
-\ **struct**\
+    - typedef:
+        per i typedef;
 
- La dichiarazione ignore o replace verrà applicata ai nomi di strutture
- in C_FILE.
+    - enum:
+        per il nome di un enumerato non anonimo;
 
-
-
-\ **enum**\
-
- La dichiarazione ignore o replace verrà applicata ai nomi di enumerati
- in C_FILE.
-
-
-
-\ **symbol**\
-
- La dichiarazione ignore o replace verrà applicata ai nomi di valori di
- enumerati in C_FILE.
-
- Per le dichiarazioni di tipo replace, il campo \ **new_value**\  utilizzerà
- automaticamente i riferimenti :c:type: per \ **typedef**\ , \ **enum**\  e
- \ **struct**\. Invece, utilizzerà :ref: per \ **ioctl**\ , \ **define**\  e
- \ **symbol**\. Il tipo di riferimento può essere definito esplicitamente
- nella dichiarazione stessa.
+    - struct:
+        per le strutture.
 
 
 ESEMPI
 ******
 
+- Ignora una definizione ``_VIDEODEV2_H`` in ``FILE_IN``::
 
-ignore define _VIDEODEV2_H
-
-
-Ignora una definizione #define _VIDEODEV2_H nel file C_FILE.
-
-ignore symbol PRIVATE
+    ignore define _VIDEODEV2_H
 
+- In una struttura dati come questo enumerato::
 
-In un enumerato come il seguente:
+    enum foo { BAR1, BAR2, PRIVATE };
 
-enum foo { BAR1, BAR2, PRIVATE };
+  Non genererà alcun riferimento incrociato per ``PRIVATE``::
 
-Non genererà alcun riferimento per \ **PRIVATE**\ .
+    ignore symbol PRIVATE
 
-replace symbol BAR1 :c:type:\`foo\`
-replace symbol BAR2 :c:type:\`foo\`
+  Nello stesso enumerato, invece di creare un riferimento incrociato per
+  ogni simbolo, si può far si che tutti puntino al tipo C ``enum foo``::
 
+    replace symbol BAR1 :c:type:\`foo\`
+    replace symbol BAR2 :c:type:\`foo\`
 
-In un enumerato come il seguente:
 
-enum foo { BAR1, BAR2, PRIVATE };
-
-Genererà un riferimento ai valori BAR1 e BAR2 dal simbolo foo nel dominio C.
+- Usa lo spazio dei nomi C ``MC`` per tutti i simboli in ``FILE_IN``::
 
+    namespace MC
 
 BUGS
 ****
 
-Riferire ogni malfunzionamento a Mauro Carvalho Chehab <mchehab@s-opensource.com>
-
+Segnalate qualsiasi malfunzionamento a Mauro Carvalho Chehab
+<mchehab@kernel.org>
 
 COPYRIGHT
 *********
 
+Copyright (c) 2016, 2025 di Mauro Carvalho Chehab <mchehab+huawei@kernel.org>.
 
-Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>.
-
-Licenza GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>.
+Licenza GPLv2: GNU GPL versione 2 <https://gnu.org/licenses/gpl.html>.
 
 Questo è software libero: siete liberi di cambiarlo e ridistribuirlo.
 Non c'è alcuna garanzia, nei limiti permessi dalla legge.
diff --git a/Documentation/translations/it_IT/doc-guide/sphinx.rst b/Documentation/translations/it_IT/doc-guide/sphinx.rst
index a5c5d935febf..70f5b24b6407 100644
--- a/Documentation/translations/it_IT/doc-guide/sphinx.rst
+++ b/Documentation/translations/it_IT/doc-guide/sphinx.rst
@@ -1,8 +1,5 @@
 .. include:: ../disclaimer-ita.rst
 
-.. note:: Per leggere la documentazione originale in inglese:
-	  :ref:`Documentation/doc-guide/index.rst <doc_guide>`
-
 .. _it_sphinxdoc:
 
 =============================================
@@ -36,7 +33,7 @@ Installazione Sphinx
 ====================
 
 I marcatori ReST utilizzati nei file in Documentation/ sono pensati per essere
-processati da ``Sphinx`` nella versione 1.7 o superiore.
+processati da ``Sphinx`` nella versione 3.4.3 o superiore.
 
 Esiste uno script che verifica i requisiti Sphinx. Per ulteriori dettagli
 consultate :ref:`it_sphinx-pre-install`.
@@ -52,24 +49,14 @@ vi raccomandiamo di installare Sphinx dentro ad un ambiente virtuale usando
 ``virtualenv-3`` o ``virtualenv`` a seconda di come Python 3 è stato
 pacchettizzato dalla vostra distribuzione.
 
-.. note::
-
-   #) Viene raccomandato l'uso del tema RTD per la documentazione in HTML.
-      A seconda della versione di Sphinx, potrebbe essere necessaria
-      l'installazione tramite il comando ``pip install sphinx_rtd_theme``.
-
-   #) Alcune pagine ReST contengono delle formule matematiche. A causa del
-      modo in cui Sphinx funziona, queste espressioni sono scritte
-      utilizzando LaTeX. Per una corretta interpretazione, è necessario aver
-      installato texlive con i pacchetti amdfonts e amsmath.
-
-Riassumendo, se volete installare la versione 2.4.4 di Sphinx dovete eseguire::
+Riassumendo, se volete installare l'ultima versione di Sphinx, dovete
+eseguire::
 
-       $ virtualenv sphinx_2.4.4
-       $ . sphinx_2.4.4/bin/activate
-       (sphinx_2.4.4) $ pip install -r Documentation/sphinx/requirements.txt
+       $ virtualenv sphinx_latest
+       $ . sphinx_latest/bin/activate
+       (sphinx_latest) $ pip install -r Documentation/sphinx/requirements.txt
 
-Dopo aver eseguito ``. sphinx_2.4.4/bin/activate``, il prompt cambierà per
+Dopo aver eseguito ``. sphinx_latest/bin/activate``, il prompt cambierà per
 indicare che state usando il nuovo ambiente. Se aprite un nuova sessione,
 prima di generare la documentazione, dovrete rieseguire questo comando per
 rientrare nell'ambiente virtuale.
@@ -99,6 +86,27 @@ Per alcune distribuzioni Linux potrebbe essere necessario installare
 anche una serie di pacchetti ``texlive`` in modo da fornire il supporto
 minimo per il funzionamento di ``XeLaTeX``.
 
+Espressioni matematiche in HTML
+-------------------------------
+
+Alcune pagine ReST contengono delle formule matematiche. Per come funziona
+Sphinx, queste espressioni sono scritte utilizzando la notazione LaTeX. Esistono
+due opzioni per far si che Sphinx rappresenti le espressioni matematiche
+nell'output HTML. La prima è un'estensione chiamata `imgmath`_ che converte le
+espressioni matematiche in immagini e le integra nelle pagine HTML. L'altra è
+un'estensione chiamata `mathjax`_ che delega la rappresentazione delle formule
+matematiche ai browser web capaci di eseguire JavaScript. La prima era l'unica
+opzione per la documentazione del kernel precedente alla versione 6.1 e richiede
+diversi pacchetti texlive, fra cui amsfonts e amsmath.
+
+A partire dalla versione 6.1 del kernel, le pagine HTML con espressioni
+matematiche possono essere generate senza dover installare alcun pacchetto
+texlive. Per maggiori informazioni consultate `Scelta della libreria per le
+formule matematiche`_.
+
+.. _imgmath: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.imgmath
+.. _mathjax: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathjax
+
 .. _it_sphinx-pre-install:
 
 Verificare le dipendenze Sphinx
@@ -136,6 +144,30 @@ Questo script ha i seguenti parametri:
 	Utilizza l'ambiente predefinito dal sistema operativo invece che
 	l'ambiente virtuale per Python;
 
+Installare la versione minima di Sphinx
+---------------------------------------
+
+Quando si modifica il sistema di generazione di Sphinx, è importante
+assicurarsi che la versione minima sia ancora supportata. Al giorno d'oggi,
+sta diventando sempre più difficile farlo sulle distribuzioni moderne, dato
+che non è possibile installarla con Python 3.13 e versioni successive.
+
+Potete verificare la versione minima di Python supportata, così come
+definita in Documentation/process/changes.rst, creando un venv con quella
+versione e installando i requisiti minimi con::
+
+	/usr/bin/python3.9 -m venv sphinx_min
+	. sphinx_min/bin/activate
+	pip install -r Documentation/sphinx/min_requirements.txt
+
+Un test più completo può essere eseguito utilizzando:
+
+	tools/docs/test_doc_build.py
+
+Questo script crea un venv Python per ogni versione supportata, generando
+facoltativamente la documentazione per un intervallo di versioni di
+Sphinx.
+
 
 Generazione della documentazione Sphinx
 =======================================
@@ -143,39 +175,82 @@ Generazione della documentazione Sphinx
 Per generare la documentazione in formato HTML o PDF si eseguono i rispettivi
 comandi ``make htmldocs`` o ``make pdfdocs``. Esistono anche altri formati
 in cui è possibile generare la documentazione; per maggiori informazioni
-potere eseguire il comando ``make help``.
+potete eseguire il comando ``make help``.
 La documentazione così generata sarà disponibile nella sottocartella
 ``Documentation/output``.
 
 Ovviamente, per generare la documentazione, Sphinx (``sphinx-build``)
-dev'essere installato. Se disponibile, il tema *Read the Docs* per Sphinx
-verrà utilizzato per ottenere una documentazione HTML più gradevole.
-Per la documentazione in formato PDF, invece, avrete bisogno di ``XeLaTeX`
-e di ``convert(1)`` disponibile in ImageMagick
-(https://www.imagemagick.org). \ [#ink]_
-Tipicamente, tutti questi pacchetti sono disponibili e pacchettizzati nelle
-distribuzioni Linux.
+dev'essere installato. Per la documentazione in formato PDF, invece,
+avrete bisogno di ``XeLaTeX`` e di ``convert(1)`` disponibile in
+ImageMagick (https://www.imagemagick.org).\ [#ink]_ Tutti questi pacchetti
+sono ampiamente disponibili e pacchettizzati nelle distribuzioni.
 
 Per poter passare ulteriori opzioni a Sphinx potete utilizzare la variabile
-make ``SPHINXOPTS``. Per esempio, se volete che Sphinx sia più verboso durante
-la generazione potete usare il seguente comando ``make SPHINXOPTS=-v htmldocs``.
+make ``SPHINXOPTS``. Per esempio, se volete che Sphinx sia più prolisso
+durante la generazione potete usare il comando
+``make SPHINXOPTS=-v htmldocs``.
 
-Potete anche personalizzare l'ouptut html passando un livello aggiuntivo
+Potete anche personalizzare l'output html passando un livello aggiuntivo
 DOCS_CSS usando la rispettiva variabile d'ambiente ``DOCS_CSS``.
 
-La variable make ``SPHINXDIRS`` è utile quando si vuole generare solo una parte
-della documentazione. Per esempio, si possono generare solo di documenti in
-``Documentation/doc-guide`` eseguendo ``make SPHINXDIRS=doc-guide htmldocs``. La
-sezione dedicata alla documentazione di ``make help`` vi mostrerà quali sotto
-cartelle potete specificare.
+Il tema di base per generare la documentazione HTML viene è "Alabaster"; questo
+tema è distribuito assieme a Sphinx e non necessita di un'installazione
+separata. Il tema di Sphinx può essere sostituito usando la variabile make
+``DOCS_THEME``.
+
+.. note::
+
+   Alcuni potrebbero preferire il tema RTD per l'output in HTML. A seconda
+   della versione di Sphinx, dev'essere installato separatamente, con il
+   comando ``pip install sphinx_rtd_theme``.
+
+Esiste un'altra variabile make, ``SPHINXDIRS``, utile quando si vuole
+generare, a scopo di test, solo una parte della documentazione. Per
+esempio, potete generare i documenti in ``Documentation/doc-guide``
+eseguendo ``make SPHINXDIRS=doc-guide htmldocs``. La sezione dedicata alla
+documentazione di ``make help`` vi mostrerà l'elenco delle sottocartelle
+che potete specificare.
 
 Potete eliminare la documentazione generata tramite il comando
 ``make cleandocs``.
 
-.. [#ink] Avere installato anche ``inkscape(1)`` dal progetto Inkscape ()
-          potrebbe aumentare la qualità delle immagini che verranno integrate
-          nel documento PDF, specialmente per quando si usando rilasci del
-          kernel uguali o superiori a 5.18
+.. [#ink] Avere installato anche ``inkscape(1)`` dal progetto Inkscape
+	  (https://inkscape.org) potrebbe aumentare la qualità delle
+	  immagini integrate nei documenti PDF, specialmente per i rilasci
+	  del kernel dalla versione 5.18 in poi.
+
+Scelta della libreria per le formule matematiche
+------------------------------------------------
+
+A partire dalla versione 6.1 del kernel, mathjax funge da libreria di
+ripiego per le formule matematiche nell'output HTML.\ [#sph1_8]_
+
+La libreria matematica viene scelta in base ai comandi disponibili, come
+mostrato di seguito:
+
+.. table:: Scelta della libreria matematica per l'HTML
+
+    ======== ================= ================
+    Libreria Comandi richiesti Formato immagine
+    ======== ================= ================
+    imgmath  latex, dvipng     PNG (raster)
+    mathjax
+    ======== ================= ================
+
+La scelta può essere sovrascritta impostando la variabile d'ambiente
+``SPHINX_IMGMATH`` come mostrato di seguito:
+
+.. table:: Effetto dell'impostazione di ``SPHINX_IMGMATH``
+
+    ====================== ========
+    Impostazione           Libreria
+    ====================== ========
+    ``SPHINX_IMGMATH=yes`` imgmath
+    ``SPHINX_IMGMATH=no``  mathjax
+    ====================== ========
+
+.. [#sph1_8] La libreria di ripiego richiede Sphinx >=1.8.
+
 
 Scrivere la documentazione
 ==========================
@@ -289,8 +364,19 @@ incrociato quando questa ha una voce nell'indice.  Se trovate degli usi di
 ``c:func:`` nella documentazione del kernel, sentitevi liberi di rimuoverli.
 
 
+Tabelle
+-------
+
+Il formato reStructuredText offre diverse opzioni per la sintassi delle tabelle.
+Lo stile del kernel per le tabelle preferisce la sintassi delle *tabelle
+semplici* o delle *tabelle a griglia*. Per maggiori dettagli consultate il
+`manuale di riferimento reStructuredText per la sintassi delle tabelle`_.
+
+.. _manuale di riferimento reStructuredText per la sintassi delle tabelle:
+   https://docutils.sourceforge.io/docs/user/rst/quickref.html#tables
+
 Tabelle a liste
----------------
+~~~~~~~~~~~~~~~
 
 Il formato ``list-table`` può essere utile per tutte quelle tabelle che non
 possono essere facilmente scritte usando il formato ASCII-art di Sphinx. Però,
@@ -403,6 +489,16 @@ percorso al documento.
 
 Per informazioni riguardo ai riferimenti incrociati ai commenti
 kernel-doc per funzioni o tipi, consultate
+Documentation/translations/it_IT/doc-guide/kernel-doc.rst.
+
+Riferimenti ai commit
+~~~~~~~~~~~~~~~~~~~~~
+
+I riferimenti ai commit di git vengono trasformati automaticamente in
+collegamenti ipertestuali quando sono scritti in uno di questi formati::
+
+    commit 72bf4f1767f0
+    commit 72bf4f1767f0 ("net: do not leave an empty skb in write queue")
 
 .. _it_sphinx_kfigure:
 
-- 
2.47.3

Re: [PATCH] doc:it_IT: align doc-guide translation

[Jonathan Corbet]

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

> Update the Italian translation of Documentation/doc-guide to catch up
> with the following upstream commits:
>
> doc-guide/index.rst:
>   commit a592a36e4937 ("Documentation: use a source-read extension for the index link boilerplate")
>   commit d40981350844 ("doc-guide: add help documentation checktransupdate.rst")
>
> doc-guide/sphinx.rst:
>   commit f1c2db1f145b ("docs: move test_doc_build.py to tools/docs")
>   commit abd61d1ff8f0 ("scripts: sphinx-pre-install: move it to tools/docs")
>   commit 9322af5e6557 ("docs: sphinx: add a file with the requirements for lowest version")
>   commit d6d886005d32 ("Docs: doc-guide: update sphinx.rst Sphinx version number")
>   commit 5ccab49c104c ("docs: doc-guide: clarify latest theme usage")
>   commit b31274d58d21 ("docs: drop the version constraints for sphinx and dependencies")
>   commit 40be2369dc0e ("Documentation: multiple .rst files: Fix grammar and more consistent formatting")
>   commit 3e893e16af55 ("docs: Raise the minimum Sphinx requirement to 2.4.4")
>   commit 86b17aaf2e88 ("docs: automarkup: linkify git revs")
>   commit 35d4a3c67eb5 ("docs/doc-guide: Clarify how to write tables")
>   commit 26d797ffc1c0 ("docs: update sphinx.rst to reflect the default theme change")
>   commit 679b4bc25fc7 ("docs/doc-guide: Add documentation on SPHINX_IMGMATH")
>   commit 4d627ef12b40 ("docs/doc-guide: Mention make variable SPHINXDIRS")
>   commit 7c43214dddfd ("docs/doc-guide: Add footnote on Inkscape for better images in PDF documents")
>
> doc-guide/kernel-doc.rst:
>   commit 827b9458c933 ("docs: kernel-doc.rst: document private: scope propagation")
>   commit eba6ffd126cd ("docs: kdoc: move kernel-doc to tools/docs")
>   commit 90f1d896d59f ("doc-guide: kernel-doc: specify that W=n does not check header files")
>   commit b580fa304c85 ("docs: kernel-doc.rst: document the new "var" kernel-doc markup")
>   commit 8deb5d725b48 ("docs: kernel-doc.rst: don't let automarkup mangle with consts")
>   commit dd3e817e879c ("doc-guide: kernel-doc: add %CONST examples")
>   commit 7e8a8143ecc3 ("docs: add support to build manpages from kerneldoc output")
>   commit 9e6c5870bb44 ("Documentation: kernel-doc: enumerate identifier *type*s")
>   commit 23a0bc285159 ("doc-guide: kernel-doc: document Returns: spelling")
>
> doc-guide/parse-headers.rst:
>   commit 6ae0f2072768 ("docs: parse-headers.rst: Fix a typo")
>   commit 68f3d40ea0ce ("docs: parse-headers.rst: remove uneeded parenthesis")
>   commit d69a03a97a2d ("docs: doc-guide: parse-headers.rst update its documentation")
>
> Also add the translations for the following pages, which had none:
>
> doc-guide/contributing.rst:
>   commit d96574b0b49d ("Add a document on how to contri
>
> doc-guide/maintainer-profile.rst:
>   commit 53b7f3aa411b ("Add a maintainer entry profile for documentation")
>
> doc-guide/checktransupdate.rst:
>   commit d40981350844 ("doc-guide: add help documentation checktransupdate.rst")
>
> Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
> ---
>  .../it_IT/doc-guide/checktransupdate.rst      |  59 ++++
>  .../it_IT/doc-guide/contributing.rst          | 319 ++++++++++++++++++
>  .../translations/it_IT/doc-guide/index.rst    |  13 +-
>  .../it_IT/doc-guide/kernel-doc.rst            |  88 +++--
>  .../it_IT/doc-guide/maintainer-profile.rst    |  60 ++++
>  .../it_IT/doc-guide/parse-headers.rst         | 220 ++++++------
>  .../translations/it_IT/doc-guide/sphinx.rst   | 178 +++++++---
>  7 files changed, 757 insertions(+), 180 deletions(-)
>  create mode 100644 Documentation/translations/it_IT/doc-guide/checktransupdate.rst
>  create mode 100644 Documentation/translations/it_IT/doc-guide/contributing.rst
>  create mode 100644 Documentation/translations/it_IT/doc-guide/maintainer-profile.rst

Applied, thanks.

jon