From ac7711427014a84ba08353df2b77f115565216d8 Mon Sep 17 00:00:00 2001 From: Federico Vaga Date: Sat, 14 Nov 2020 09:33:42 +0100 Subject: doc:it_IT: align Italian documentation Translation for the following patches commit 0aa78b105f57 ("Documentation/changes: Raise minimum supported binutils version to 2.23") commit 7d7178873560 ("Documentation: include sign off for reverts") commit 905705a8fd43 ("docs: programming-languages: refresh blurb on clang support") commit 5ff4aa70bf34 ("docs: submitting-patches: use :doc: for references") commit 030f066f677f ("docs: submitting-patches: describe preserving review/test tags") commit 68e4cd17e218 ("docs: deprecated.rst: Add zero-length and one-element arrays") commit 5429ef62bcf3 ("compiler/gcc: Raise minimum GCC version for kernel builds to 4.8") commit 5b5bbb8cc51b ("docs: process: Add an example for creating a fixes tag") commit 858e6845654d ("docs: dt: convert submitting-patches.txt to ReST format") commit cca73e4946c4 ("docs: Correct the release date of 5.2 stable") commit c170f2eb9648 ("docs: Document cross-referencing between documentation pages") commit 7c8b9e3000f8 ("kernel-doc: Update "cross-referencing from rST" section to use automarkup") commit 27def953b63b ("docs: deprecated.rst: Expand str*cpy() replacement notes") commit 17dca0502314 ("docs: deprecated.rst: Update zero-length/one-element arrays section") commit 3519c4d6e08e ("Documentation: add minimum clang/llvm version") commit 0bddd227f3dc ("Documentation: update for gcc 4.9 requirement") commit 9f364b605f34 ("submitting-patches.rst: presume git will be used") commit 4ebdf7be21d6 ("Documentation/maintainer: rehome sign-off process") commit 7433ff33e8ba ("Documentation/process: expand plain-text advice") commit eb45fb2fb16d ("docs: process: Add cross-link to security-bugs") commit bdc48fa11e46 ("checkpatch/coding-style: deprecate 80-column warning") commit f67281a72b30 ("Documentation: process: step 2: Link to email list fixed") Signed-off-by: Federico Vaga Link: https://lore.kernel.org/r/20201114083342.13935-1-federico.vaga@vaga.pv.it Signed-off-by: Jonathan Corbet --- .../translations/it_IT/doc-guide/kernel-doc.rst | 30 +-- .../translations/it_IT/doc-guide/sphinx.rst | 20 ++ .../translations/it_IT/process/2.Process.rst | 4 +- .../translations/it_IT/process/changes.rst | 22 +- .../translations/it_IT/process/coding-style.rst | 26 +- .../translations/it_IT/process/deprecated.rst | 147 +++++++++- .../translations/it_IT/process/email-clients.rst | 5 + .../it_IT/process/programming-language.rst | 8 +- .../it_IT/process/submitting-patches.rst | 297 +++++---------------- 9 files changed, 296 insertions(+), 263 deletions(-) (limited to 'Documentation/translations') diff --git a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst index 524ad86cadbb..009cdac014b6 100644 --- a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst +++ b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst @@ -419,26 +419,24 @@ del `dominio Sphinx per il C`_. Riferimenti usando reStructuredText ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Per fare riferimento a funzioni e tipi di dato definiti nei commenti kernel-doc -all'interno dei documenti reStructuredText, utilizzate i riferimenti dal -`dominio Sphinx per il C`_. Per esempio:: +Nei documenti reStructuredText non serve alcuna sintassi speciale per +fare riferimento a funzioni e tipi definiti nei commenti +kernel-doc. Sarà sufficiente terminare i nomi di funzione con ``()``, +e scrivere ``struct``, ``union``, ``enum``, o ``typedef`` prima di un +tipo. Per esempio:: - See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`. + See foo() + See struct foo. + See union bar. + See enum baz. + See typedef meh. -Nonostante il riferimento ai tipi di dato funzioni col solo nome, -ovvero senza specificare struct/union/enum/typedef, potreste preferire il -seguente:: +Tuttavia, la personalizzazione dei collegamenti è possibile solo con +la seguente sintassi:: - See :c:type:`struct foo `. - See :c:type:`union bar `. - See :c:type:`enum baz `. - See :c:type:`typedef meh `. + See :c:func:`my custom link text for function foo `. + See :c:type:`my custom link text for struct bar `. -Questo produce dei collegamenti migliori, ed è in linea con il modo in cui -kernel-doc gestisce i riferimenti. - -Per maggiori informazioni, siete pregati di consultare la documentazione -del `dominio Sphinx per il C`_. Commenti per una documentazione generale ---------------------------------------- diff --git a/Documentation/translations/it_IT/doc-guide/sphinx.rst b/Documentation/translations/it_IT/doc-guide/sphinx.rst index f1ad4504b734..090d2949d345 100644 --- a/Documentation/translations/it_IT/doc-guide/sphinx.rst +++ b/Documentation/translations/it_IT/doc-guide/sphinx.rst @@ -364,6 +364,26 @@ Che verrà rappresentata nel seguente modo: - column 3 +Riferimenti incrociati +---------------------- + +Per fare dei riferimenti incrociati da una pagina ad un'altra +specificando il percorso a partire dalla cartella *Documentation*. +Per esempio, se volete aggiungere un riferimento a questa pagina +(l'estensione .rst è opzionale):: + + See Documentation/translations/it_IT/doc-guide/sphinx.rst. + +Se preferite usare un percorso relative allora vi serve la direttiva +Sphinx ``doc``. Per esempio, se volete aggiungere un riferimento a +questa pagina dalla stessa cartella:: + + See :doc:`sphinx`. + +Per maggiori informazioni su come aggiungere riferimenti incrociati a +commenti kernel-doc di funzioni o tipi, leggete +Documentation/translations/it_IT/doc-guide/sphinx.rst. + .. _it_sphinx_kfigure: Figure ed immagini diff --git a/Documentation/translations/it_IT/process/2.Process.rst b/Documentation/translations/it_IT/process/2.Process.rst index 30dc172f06b0..62826034e0b2 100644 --- a/Documentation/translations/it_IT/process/2.Process.rst +++ b/Documentation/translations/it_IT/process/2.Process.rst @@ -123,7 +123,7 @@ iniziale, i kernel ricevono aggiornamenti per più di un ciclo di sviluppo. Quindi, per esempio, la storia del kernel 5.2 appare così (anno 2019): ============== =============================== - 15 settembre 5.2 rilascio stabile FIXME settembre è sbagliato + 7 luglio 5.2 rilascio stabile 14 luglio 5.2.1 21 luglio 5.2.2 26 luglio 5.2.3 @@ -434,7 +434,7 @@ l'elenco principale lo si trova sul sito: http://vger.kernel.org/vger-lists.html Esistono liste gestite altrove; un certo numero di queste sono in -lists.redhat.com. +redhat.com/mailman/listinfo. La lista di discussione principale per lo sviluppo del kernel è, ovviamente, linux-kernel. Questa lista è un luogo ostile dove trovarsi; i volumi possono diff --git a/Documentation/translations/it_IT/process/changes.rst b/Documentation/translations/it_IT/process/changes.rst index 37da4447a40d..cc883f8d96c4 100644 --- a/Documentation/translations/it_IT/process/changes.rst +++ b/Documentation/translations/it_IT/process/changes.rst @@ -32,9 +32,10 @@ PC Card, per esempio, probabilmente non dovreste preoccuparvi di pcmciautils. ====================== ================= ======================================== Programma Versione minima Comando per verificare la versione ====================== ================= ======================================== -GNU C 4.6 gcc --version +GNU C 4.9 gcc --version +Clang/LLVM (optional) 10.0.1 clang --version GNU make 3.81 make --version -binutils 2.21 ld -v +binutils 2.23 ld -v flex 2.5.35 flex --version bison 2.0 bison --version util-linux 2.10o fdformat --version @@ -71,6 +72,16 @@ GCC La versione necessaria di gcc potrebbe variare a seconda del tipo di CPU nel vostro calcolatore. +Clang/LLVM (opzionale) +---------------------- + +L'ultima versione di clang e *LLVM utils* (secondo `releases.llvm.org +`_) sono supportati per la generazione del +kernel. Non garantiamo che anche i rilasci più vecchi funzionino, inoltre +potremmo rimuovere gli espedienti che abbiamo implementato per farli +funzionare. Per maggiori informazioni +:ref:`Building Linux with Clang/LLVM `. + Make ---- @@ -79,7 +90,7 @@ Per compilare il kernel vi servirà GNU make 3.81 o successivo. Binutils -------- -Per generare il kernel è necessario avere Binutils 2.21 o superiore. +Per generare il kernel è necessario avere Binutils 2.23 o superiore. pkg-config ---------- @@ -338,6 +349,11 @@ gcc - +Clang/LLVM +---------- + +- :ref:`Getting LLVM `. + Make ---- diff --git a/Documentation/translations/it_IT/process/coding-style.rst b/Documentation/translations/it_IT/process/coding-style.rst index a346f1f2ce21..c86c4543f249 100644 --- a/Documentation/translations/it_IT/process/coding-style.rst +++ b/Documentation/translations/it_IT/process/coding-style.rst @@ -92,16 +92,22 @@ delle righe. Lo stile del codice riguarda la leggibilità e la manutenibilità utilizzando strumenti comuni. -Il limite delle righe è di 80 colonne e questo e un limite fortemente -desiderato. - -Espressioni più lunghe di 80 colonne saranno spezzettate in pezzi più piccoli, -a meno che eccedere le 80 colonne non aiuti ad aumentare la leggibilità senza -nascondere informazioni. I pezzi derivati sono sostanzialmente più corti degli -originali e vengono posizionati più a destra. Lo stesso si applica, nei file -d'intestazione, alle funzioni con una lista di argomenti molto lunga. Tuttavia, -non spezzettate mai le stringhe visibili agli utenti come i messaggi di -printk, questo perché inibireste la possibilità d'utilizzare grep per cercarle. +Come limite di riga si preferiscono le 80 colonne. + +Espressioni più lunghe di 80 colonne dovrebbero essere spezzettate in +pezzi più piccoli, a meno che eccedere le 80 colonne non aiuti ad +aumentare la leggibilità senza nascondere informazioni. + +I nuovi pezzi derivati sono sostanzialmente più corti degli originali +e vengono posizionati più a destra. Uno stile molto comune è quello di +allineare i nuovi pezzi alla parentesi aperta di una funzione. + +Lo stesso si applica, nei file d'intestazione, alle funzioni con una +lista di argomenti molto lunga. + +Tuttavia, non spezzettate mai le stringhe visibili agli utenti come i +messaggi di printk, questo perché inibireste la possibilità +d'utilizzare grep per cercarle. 3) Posizionamento di parentesi graffe e spazi --------------------------------------------- diff --git a/Documentation/translations/it_IT/process/deprecated.rst b/Documentation/translations/it_IT/process/deprecated.rst index a642ff3fdc8b..07c79d4bafca 100644 --- a/Documentation/translations/it_IT/process/deprecated.rst +++ b/Documentation/translations/it_IT/process/deprecated.rst @@ -95,6 +95,11 @@ Invece, usate la seguente funzione:: header = kzalloc(struct_size(header, item, count), GFP_KERNEL); +.. note:: Se per caso state usando struct_size() su una struttura dati che + in coda contiene un array di lunghezza zero o uno, allora siete + invitati a riorganizzare il vostro codice usando il + `flexible array member <#zero-length-and-one-element-arrays>`_. + Per maggiori dettagli fate riferimento a array_size(), array3_size(), e struct_size(), così come la famiglia di funzioni check_add_overflow() e check_mul_overflow(). @@ -116,7 +121,11 @@ di destinazione. Questo può portare ad un overflow oltre i limiti del buffer e generare svariati tipi di malfunzionamenti. Nonostante l'opzione `CONFIG_FORTIFY_SOURCE=y` e svariate opzioni del compilatore aiutano a ridurne il rischio, non c'è alcuna buona ragione per continuare ad usare -questa funzione. La versione sicura da usare è strscpy(). +questa funzione. La versione sicura da usare è strscpy(), tuttavia va +prestata attenzione a tutti quei casi dove viene usato il valore di +ritorno di strcpy(). La funzione strscpy() non ritorna un puntatore +alla destinazione, ma un contatore dei byte non NUL copiati (oppure +un errno negativo se la stringa è stata troncata). strncpy() su stringe terminate con NUL -------------------------------------- @@ -127,8 +136,12 @@ causati, appunto, dalla mancanza del terminatore. Questa estende la terminazione nel buffer di destinazione quando la stringa d'origine è più corta; questo potrebbe portare ad una penalizzazione delle prestazioni per chi usa solo stringe terminate. La versione sicura da usare è -strscpy(). (chi usa strscpy() e necessita di estendere la -terminazione con NUL deve aggiungere una chiamata a memset()) +strscpy(), tuttavia va prestata attenzione a tutti quei casi dove +viene usato il valore di ritorno di strncpy(). La funzione strscpy() +non ritorna un puntatore alla destinazione, ma un contatore dei byte +non NUL copiati (oppure un errno negativo se la stringa è stata +troncata). Tutti i casi che necessitano di estendere la +terminazione con NUL dovrebbero usare strscpy_pad(). Se il chiamate no usa stringhe terminate con NUL, allore strncpy() può continuare ad essere usata, ma i buffer di destinazione devono essere @@ -140,7 +153,10 @@ strlcpy() La funzione strlcpy(), per prima cosa, legge interamente il buffer di origine, magari leggendo più di quanto verrà effettivamente copiato. Questo è inefficiente e può portare a overflow di lettura quando la stringa non è -terminata con NUL. La versione sicura da usare è strscpy(). +terminata con NUL. La versione sicura da usare è strscpy(), tuttavia +va prestata attenzione a tutti quei casi dove viene usato il valore di +ritorno di strlcpy(), dato che strscpy() ritorna un valore di errno +negativo quanto la stringa viene troncata. Segnaposto %p nella stringa di formato -------------------------------------- @@ -227,3 +243,126 @@ modi: * ``continue;`` * ``goto