Documentation/translations/it_IT/doc-guide/parse-headers.rst

   1 .. include:: ../disclaimer-ita.rst
   2
   3 .. note:: Per leggere la documentazione originale in inglese:
   4           :ref:`Documentation/doc-guide/index.rst <doc_guide>`
   5
   6 =========================================
   7 Includere gli i file di intestazione uAPI
   8 =========================================
   9
  10 Qualche volta è utile includere dei file di intestazione e degli esempi di codice C
  11 al fine di descrivere l'API per lo spazio utente e per generare dei riferimenti
  12 fra il codice e la documentazione. Aggiungere i riferimenti ai file dell'API
  13 dello spazio utente ha ulteriori vantaggi: Sphinx genererà dei messaggi
  14 d'avviso se un simbolo non viene trovato nella documentazione. Questo permette
  15 di mantenere allineate la documentazione della uAPI (API spazio utente)
  16 con le modifiche del kernel.
  17 Il programma :ref:`parse_headers.pl <it_parse_headers>` genera questi riferimenti.
  18 Esso dev'essere invocato attraverso un Makefile, mentre si genera la
  19 documentazione. Per avere un esempio su come utilizzarlo all'interno del kernel
  20 consultate ``Documentation/media/Makefile``.
  21
  22 .. _it_parse_headers:
  23
  24 parse_headers.pl
  25 ^^^^^^^^^^^^^^^^
  26
  27 NOME
  28 ****
  29
  30
  31 parse_headers.pl - analizza i file C al fine di identificare funzioni,
  32 strutture, enumerati e definizioni, e creare riferimenti per Sphinx
  33
  34 SINTASSI
  35 ********
  36
  37
  38 \ **parse_headers.pl**\  [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
  39
  40 Dove <options> può essere: --debug, --usage o --help.
  41
  42
  43 OPZIONI
  44 *******
  45
  46
  47
  48 \ **--debug**\
  49
  50  Lo script viene messo in modalità verbosa, utile per il debugging.
  51
  52
  53 \ **--usage**\
  54
  55  Mostra un messaggio d'aiuto breve e termina.
  56
  57
  58 \ **--help**\
  59
  60  Mostra un messaggio d'aiuto dettagliato e termina.
  61
  62
  63 DESCRIZIONE
  64 ***********
  65
  66 Converte un file d'intestazione o un file sorgente C (C_FILE) in un testo
  67 ReStructuredText incluso mediante il blocco ..parsed-literal
  68 con riferimenti alla documentazione che descrive l'API. Opzionalmente,
  69 il programma accetta anche un altro file (EXCEPTIONS_FILE) che
  70 descrive quali elementi debbano essere ignorati o il cui riferimento
  71 deve puntare ad elemento diverso dal predefinito.
  72
  73 Il file generato sarà disponibile in (OUT_FILE).
  74
  75 Il programma è capace di identificare *define*, funzioni, strutture,
  76 tipi di dato, enumerati e valori di enumerati, e di creare i riferimenti
  77 per ognuno di loro. Inoltre, esso è capace di distinguere le #define
  78 utilizzate per specificare i comandi ioctl di Linux.
  79
  80 Il file EXCEPTIONS_FILE contiene due tipi di dichiarazioni:
  81 \ **ignore**\  o \ **replace**\ .
  82
  83 La sintassi per ignore è:
  84
  85 ignore \ **tipo**\  \ **nome**\
  86
  87 La dichiarazione \ **ignore**\  significa che non verrà generato alcun
  88 riferimento per il simbolo \ **name**\  di tipo \ **tipo**\ .
  89
  90
  91 La sintassi per replace è:
  92
  93 replace \ **tipo**\  \ **nome**\  \ **nuovo_valore**\
  94
  95 La dichiarazione \ **replace**\  significa che verrà generato un
  96 riferimento per il simbolo \ **name**\ di tipo \ **tipo**\ , ma, invece
  97 di utilizzare il valore predefinito, verrà utilizzato il valore
  98 \ **nuovo_valore**\ .
  99
 100 Per entrambe le dichiarazioni, il \ **tipo**\  può essere uno dei seguenti:
 101
 102
 103 \ **ioctl**\
 104
 105  La dichiarazione ignore o replace verrà applicata su definizioni di ioctl
 106  come la seguente:
 107
 108  #define        VIDIOC_DBG_S_REGISTER    _IOW('V', 79, struct v4l2_dbg_register)
 109
 110
 111
 112 \ **define**\
 113
 114  La dichiarazione ignore o replace verrà applicata su una qualsiasi #define
 115  trovata in C_FILE.
 116
 117
 118
 119 \ **typedef**\
 120
 121  La dichiarazione ignore o replace verrà applicata ad una dichiarazione typedef
 122  in C_FILE.
 123
 124
 125
 126 \ **struct**\
 127
 128  La dichiarazione ignore o replace verrà applicata ai nomi di strutture
 129  in C_FILE.
 130
 131
 132
 133 \ **enum**\
 134
 135  La dichiarazione ignore o replace verrà applicata ai nomi di enumerati
 136  in C_FILE.
 137
 138
 139
 140 \ **symbol**\
 141
 142  La dichiarazione ignore o replace verrà applicata ai nomi di valori di
 143  enumerati in C_FILE.
 144
 145  Per le dichiarazioni di tipo replace, il campo \ **new_value**\  utilizzerà
 146  automaticamente i riferimenti :c:type: per \ **typedef**\ , \ **enum**\  e
 147  \ **struct**\. Invece, utilizzerà :ref: per \ **ioctl**\ , \ **define**\  e
 148  \ **symbol**\. Il tipo di riferimento può essere definito esplicitamente
 149  nella dichiarazione stessa.
 150
 151
 152 ESEMPI
 153 ******
 154
 155
 156 ignore define _VIDEODEV2_H
 157
 158
 159 Ignora una definizione #define _VIDEODEV2_H nel file C_FILE.
 160
 161 ignore symbol PRIVATE
 162
 163
 164 In un enumerato come il seguente:
 165
 166 enum foo { BAR1, BAR2, PRIVATE };
 167
 168 Non genererà alcun riferimento per \ **PRIVATE**\ .
 169
 170 replace symbol BAR1 :c:type:\`foo\`
 171 replace symbol BAR2 :c:type:\`foo\`
 172
 173
 174 In un enumerato come il seguente:
 175
 176 enum foo { BAR1, BAR2, PRIVATE };
 177
 178 Genererà un riferimento ai valori BAR1 e BAR2 dal simbolo foo nel dominio C.
 179
 180
 181 BUGS
 182 ****
 183
 184 Riferire ogni malfunzionamento a Mauro Carvalho Chehab <mchehab@s-opensource.com>
 185
 186
 187 COPYRIGHT
 188 *********
 189
 190
 191 Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>.
 192
 193 Licenza GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
 194
 195 Questo è software libero: siete liberi di cambiarlo e ridistribuirlo.
 196 Non c'è alcuna garanzia, nei limiti permessi dalla legge.