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

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