Questo capitolo raccoglie alcune convenzioni importanti relative all'opera a2. Le annotazioni sulla terminologia sono separate in un altro capitolo.
In informatica si utilizzano delle unità di misura e dei moltiplicatori ben conosciuti, ma senza uno standard simbolico ben definito. Nel testo di questo documento si usano le convenzioni elencate nel seguito.
In particolare è bene distinguere tra il nome di un'unità di misura e il simbolo che la rappresenta: quando si parla dell'unità si usa il nome esteso, minuscolo; quando si indica un valore si deve usare il simbolo. In altri termini, si può parlare di hertz in generale, ma poi si indicano n Hz per indicarne una quantità precisa.
Quando si nominano i prefissi moltiplicatori, come «mega», «giga» e «tera», si usano le iniziali minuscole anche se il simbolo corrispondente è dato dalla loro iniziale maiuscola.
|
Alle volte verrebbe da enfatizzare di tutto. Qui si annotano le cose che per regola non vengono enfatizzate.
Valori numerici
I valori numerici di qualunque sistema di numerazione non vengono enfatizzati e i valori espressi in base diversa da 10 si indicano come si vede qui: 11 = 0B16 = 138 = 10112. In particolare, le lettere alfabetiche utilizzate per le basi di numerazione superiori a 10, sono maiuscole.
Classi di indirizzi IPv4
Le classi di indirizzi IPv4 sono definite da lettere alfabetiche maiuscole che qui non vengono enfatizzate.
Indirizzi IPv4
Gli indirizzi numerici IPv4, a ottetti, vengono rappresentati così come sono, senza enfatizzazioni, utilizzando eventualmente il simbolo * per rappresentare l'indifferenza del valore di uno o più ottetti.
Indirizzi IPv6
Gli indirizzi numerici IPv6 vengono rappresentati così come sono, senza enfatizzazioni, utilizzando lettere minuscole.
Denominazione dei record di risorsa nel DNS
Le sigle usate nel DNS per identificare i record di risorsa dei file di definizione delle zone, sono scritti usando lettere maiuscole, senza enfatizzazioni.
Comandi del modem
I comandi AT e gli altri comandi dei modem vengono indicati utilizzando lettere maiuscole e senza enfatizzazioni. Ci possono essere eccezioni a questa regola, per esempio quando il contesto fa riferimento a una stringa che in quel caso particolare corrisponde proprio a un comando da inviare al modem.
I valori numerici da zero a nove vengono rappresentati preferibilmente in lettere, soprattutto per evitare ambiguità nella lettura, a meno che si presentino le condizioni seguenti:
il numero è seguito da un simbolo (secondo il SI o anche altre convenzioni), per cui si preferisce lasciarlo espresso in cifre;
il numero fa parte di un intervallo, dove l'altro valore è composto da due o più cifre, così si lascia in cifra anche il primo, dal momento che non ci possono essere ambiguità.
In generale, in questo documento, i nomi riferiti a degli «eseguibili», ovvero i programmi e gli script, sono indicati in modo evidenziato, esattamente come si utilizzano nel sistema operativo, senza cambiamenti nella collezione alfabetica delle lettere maiuscole e minuscole. Quando però il programma riveste un'importanza particolare, può assumere una denominazione diversa da quella che si usa nel nome del file eseguibile, oppure semplicemente si può decidere di trattarlo come qualcosa di più importante.
Per fare un esempio pratico, quando si parla di shell si fa riferimento alla shell Bash, alla shell Korn, alla shell C,... mentre l'eseguibile vero e proprio potrebbe essere bash, ksh, csh,... Lo stesso vale per i programmi che meritano questa attenzione anche se il loro nome (verbale) non cambia.
In generale, il nome di un programma applicativo, di un pacchetto o di altre situazioni analoghe, viene indicato con l'iniziale maiuscola, salvo eccezioni che possono derivare dall'uso acquisito in una qualche forma differente, escludendo a ogni modo l'uso di sole lettere minuscole.
|
Il nome di un programma eseguibile va annotato in forma dattilografica, esattamente come deve essere scritto per avviarlo, ovvero come indicato nel file system. Nell'ambito dello stile dell'opera, quando si scrive il nome di un programma senza voler fare riferimento al file eseguibile, il nome in questione non può essere annotato usando solo lettere minuscole, anche se l'autore originale fa così. |
La tabella u113.2 elenca alcune delle scelte di stile nell'uso dei nomi dei programmi distinguendo tra «eseguibile» e qualcosa di diverso: applicativo, pacchetto, servizio, sistema e simili, riferite a forme che costituiscono un'eccezione rispetto alla regola generale.
|
Tabella u113.2. Stile nell'uso dei nomi dei programmi distinguendo tra «eseguibile» e «applicativo», limitatamente ad alcune eccezioni.
|
Gli acronimi non sono sempre ottenuti con le sole iniziali delle parole che compongono il nome di qualcosa; inoltre, non c'è alcuna necessità pratica nell'evidenziare la corrispondenza tra le lettere usate e la frase corrispondente. In questo senso, la descrizione degli acronimi che si fa con l'elemento dacronym ha un aspetto uniforme: l'iniziale maiuscola e il resto del testo in minuscolo, tranne nel caso in cui si tratti di termini che rappresentano dei nomi importanti o degli altri acronimi, oppure quando la lingua di origine impone l'uso della maiuscola. Seguono alcuni esempi:
|
Il problema della costruzione di un indice analitico è già trattato nel capitolo sullo stile letterario in generale. All'interno dell'opera a2 ci sono delle particolarità che è bene precisare.
In particolare, l'indice analitico realizzato con il sistema di composizione di a2 consente l'uso di un carattere dattilografico attraverso l'uso dell'elemento code e delle forme di evidenziamento particolari per combinazioni di tasti (reali o virtuali) e per codici ASCII:
|
|
|
|
|
I termini inseriti nell'indice analitico vanno scritti usando lettere minuscole, a meno che si tratti di nomi particolari che vanno sempre scritti in un modo prestabilito.
La descrizione di un acronimo, inserita per esteso, si scrive con le stesse regole usate per l'elemento dacronym, per cui l'iniziale è maiuscola.
Il nome di un applicativo, di un pacchetto, di un servizio, di un sistema e simili, va scritto nello stesso modo usato nel testo normale, senza cambiare lo stato delle lettere maiuscole e minuscole.
Il nome di file e directory va scritto esattamente come appare nel sistema operativo, utilizzando un carattere dattilografico, tenendo conto che i file eseguibili vanno indicati senza percorso, mentre gli altri dovrebbero contenerlo.
Il nome delle variabili di ambiente va scritto esattamente come appare nel sistema operativo (generalmente si tratta di nomi scritti con lettere maiuscole), usando un carattere dattilografico, lasciando il dollaro come prefisso.
Quando si inserisce il nome di un applicativo che possiede un eseguibile con lo stesso nome, non si annota anche il nome dell'eseguibile. In pratica, se si inserisce la voce «Pippo» senza enfatizzazione, non si annota anche la voce «pippo», corrispondente all'eseguibile omonimo, in modo dattilografico; al massimo, si inserisce un'altra volta la stessa voce «Pippo». Infatti, chi cerca notizie sul programma Pippo, o sull'eseguibile pippo, si troverebbe in difficoltà nello scegliere tra l'una e l'altra voce. Quando invece un applicativo si articola in programmi eseguibili differenti, è sensato annotare sia il nome dell'applicativo, sia i nomi degli eseguibili che vengono descritti in modo particolare.
Quando la voce «Pippo» è comunque una cosa diversa da «pippo», le due voci vanno annotate esattamente e separatamente. Per esempio, si può fare riferimento al protocollo FTP e poi al programma eseguibile ftp. Il lettore può sentirsi confuso dalla distinzione, ma in tal caso è necessaria.
Si utilizza il singolare, salvo eccezioni dovute al fatto che il termine al singolare possa intendersi come una cosa differente da ciò che si vuole realmente.
La prima parola dovrebbe essere un sostantivo, o comunque è necessario sostantivare l'inizio della voce da inserire nell'indice analitico.
Non si inizia una voce dell'indice analitico con un verbo; nel caso si può sostantivare il verbo. Per esempio, al posto di «salvare i dati» si può inserire la voce «salvataggio dei dati».
Il sistema di composizione non consente l'indicazione di sottoclassificazioni nell'indice analitico, per cui si usa la tecnica seguente:
voce: sottoclassificazione |
Questo fatto implica che i due punti vadano usati solo per questo scopo nelle voci dell'indice analitico; inoltre, diventa inopportuno l'inserimento di una sottoclassificazione ulteriore.
Una sottoclassificazione non è sottoposta all'obbligo di essere formulata usando il singolare; tuttavia, in caso di conflitto, si deve preferire la forma al singolare.
Una sottoclassificazione inizia con un sostantivo, così come iniziano le voci normali. Per esempio, «salvataggio: recuperare i dati» va sostituito con «salvataggio: recupero dei dati».
Non si usa il trattino per indicare una sottoclassificazione. Per esempio, «salvataggio -- recupero dei dati» va sostituto con «salvataggio: recupero dei dati».
Quando si inserisce una voce in una sezione, non si inserisce nuovamente nelle sottosezioni relative. In pratica, se si inserisce la voce «Pippo» in corrispondenza dell'inizio di un capitolo, non si inserisce nuovamente la stessa voce in altre sezioni inferiori dello stesso capitolo.
Le voci dell'indice analitico vanno inserite in riferimento alle sezioni opportune. Per esempio, la parola «file» potrebbe trovarsi in quasi tutte le pagine di un testo di informatica, mentre dovrebbe essere fatto un richiamo solo a quelle sezioni in cui si spiega di cosa si tratta (ammesso che ci sia).
I riferimenti per la generazione dell'indice analitico vanno posti preferibilmente nel titolo della sezione a cui fanno riferimento, come nell'esempio seguente:
|
Come si vede, viene indicato prima il titolo e subito dopo l'elenco dei riferimenti da inserire nell'indice, che riguardano la sezione.
Inserendo le voci dell'indice analitico nell'ambito del titolo di una sezione, si comprende che non abbia senso ripetere la stessa voce nelle sottosezioni relative.
La gestione corretta delle «enfatizzazioni» è sempre un problema serio di coerenza, soprattutto se si considera il fatto che l'enfatizzazione non implica solo la composizione finale con un aspetto particolare, ma anche la classificazione dell'oggetto per qualche fine. In particolare, l'elemento special non genera alcuna enfatizzazione, ma serve a dare una classificazione al termine inserito, per qualche ragione. L'opera a2 usa le convenzioni che vengono sintetizzate in questa sezione.
<samp>stringa</samp> |
Si usa all'interno di un testo normale per delimitare delle stringhe che hanno un valore letterale e si riferiscono in qualche modo a un'informazione tecnica. In particolare, si indicano in questo modo:
i nomi degli eseguibili;
gli esempi di opzioni di una riga di comando;
i nomi delle variabili di ambiente (senza il dollaro iniziale);
i nomi di elementi SGML (compreso XML e altre applicazioni);
gli esempi di istruzioni, comandi e direttive di qualunque tipo;
tutte le informazioni tecniche letterali che non ricadono in situazioni differenti.
<code>nome</code> |
Si tratta di una forma di enfatizzazione molto simile a quella dell'elemento samp, riservata a situazioni particolari:
può essere usata per ottenere un carattere dattilografico nelle voci dell'indice analitico;
l'elemento code può essere usato come unico elemento contenuto all'interno di dt, quando in condizioni normali questo sarebbe stato rappresentato con l'elemento samp;
l'elemento code può essere usato come unico elemento contenuto all'interno di faqh3 o qh3, quando in condizioni normali questo sarebbe stato rappresentato con l'elemento samp.
<file>file</file> |
Nel testo normale, i nomi di file e directory, con o senza percorsi, vanno inseriti nell'elemento file. In generale, il nome di un file o di una directory dovrebbe sempre contenere l'informazione del percorso, salvo che si tratti implicitamente della directory corrente, oppure che non si possa stabilire una posizione precisa.
|
Si usa la convenzione delle shell derivate da quella di Bourne, per cui il simbolo |
In un percorso del genere si può inserire l'elemento var, per descrivere una parte variabile dello stesso; inoltre è ammesso l'uso di caratteri jolly elementari, ovvero asterisco e punto interrogativo, per fare riferimento a più file.
I nomi delle directory terminano sempre con la barra finale: / o \ a seconda del sistema operativo a cui si fa riferimento.
Quando si vuole fare riferimento a un file contenente un documento che dovrebbe essere raggiungibile in ogni sistema che abbia installato un certo applicativo, si può usare eventualmente l'elemento uri, indicando un URI di tipo file:, allo scopo di consentire l'accesso ipertestuale al file stesso. Naturalmente, ciò ha senso se l'URI che si indica è valido; quindi non è il caso di indicare caratteri jolly in un indirizzo del genere.
<var>metavariabile</var> |
L'elemento var serve a delimitare una metavariabile, ovvero qualcosa che descrive ciò che va sostituito al suo posto. Non si indicano con questo elemento altri tipi di variabili, come potrebbero essere le variabili di ambiente o quelle di un programma scritto con un certo linguaggio. In tal caso, si userebbe piuttosto l'elemento samp.
L'elemento var va usato prevalentemente all'interno dell'elemento syntax, nei modelli sintattici, ma può essere usato utilmente anche dentro un elemento samp, quando una parte della stringa non è fissa, così come in un elemento file, per lo stesso motivo.
Eccezionalmente, si può indicare un comando con l'inserzione di un elemento var all'interno del testo da digitare, ovvero l'elemento type. Tuttavia, in condizioni normali, si preferisce fare questo in un elemento syntax, se il contesto lo consente.
È consentita l'inserzione dell'elemento var anche all'interno di un elemento pre, quando non è opportuno l'uso di un elemento syntax al suo posto.
|
Il nome di una metavariabile dovrebbe descrivere ciò che rappresenta, mentre non deve essere un esempio del contenuto. |
Per evitare confusione, il nome va scritto usando possibilmente lettere minuscole, dove le varie parti possono essere separate da un trattino basso, come nel caso di mia_variabile. Naturalmente si possono usare anche i numeri, purché sia chiaro che servono solo a individuare la metavariabile, come nel caso di nome_1, nome_2,... nome_n. È da escludere l'uso di altri segni, perché creerebbero confusione, dal momento che i nomi delle variabili non appaiono delimitati. Se possibile è meglio evitare l'uso dell'apostrofo.
Se possibile, è meglio comporre il nome delle metavariabili usando termini normali (non abbreviati o fusi assieme), in modo da non doverli inserire inutilmente nel vocabolario del controllo ortografico.
<dfn>definizione</dfn> |
L'elemento dfn serve a delimitare una definizione, ovvero un termine che viene introdotto in riferimento a un contesto particolare. Va usato solo quando viene introdotto e non ha altro scopo che quello di generare una forma di evidenziamento uniforme.
Lo stesso termine può apparire in contesti differenti e con un significato diverso; pertanto, l'uso dell'elemento dfn vale in quanto riferito al contesto particolare a cui appartiene la parola evidenziata.
In generale, è bene evitare la proliferazione di evidenziamenti del genere, che vanno limitati alle situazioni in cui si vuole cogliere l'attenzione del lettore.
<strdfn>definizione_straniera</strdfn> |
L'elemento strdfn serve a delimitare un termine o una definizione in lingua straniera, che non si intende utilizzare nel testo come terminologia normale, ma solo per spiegare, eventualmente, a cosa si sta facendo riferimento.
<em>testo</em> <strong>testo</strong> <small>testo</small> <big>testo</small> |
Le forme di evidenziamento generico vanno usate con molta parsimonia, perché non esiste una regola generale per il loro utilizzo. In particolare, un carattere ingrandito ottenuto con l'elemento big è utile nella realizzazione di presentazioni (lucidi per lavagna luminosa).
<bibref>titolo</bibref> |
Si usa l'elemento bibref, nel testo normale, per delimitare il titolo di un documento o di un'opera di qualunque tipo.
<dacronym>descrizione_acronimo</dacronym> |
Si usa l'elemento dacronym, nel testo normale, per delimitare la descrizione di un acronimo.
<acronym>acronimo</acronym> |
Questo elemento dovrebbe servire per delimitare un acronimo, secondo la logica del sistema di composizione, ma attualmente gli acronimi non vengono delimitati in alcun modo.
<kbd>combinazione_tasti</kbd> |
L'elemento kbd viene usato per indicare tasti (della tastiera) o combinazioni di tasti da premere. I nomi dei tasti vanno indicati come previsto (tabella u114.4, nel capitolo u114) e le combinazioni si ottengono inserendo uno spazio non interrompibile ( ) tra i vari nomi o tra i simboli corrispondenti.
Nelle tabelle, quando si elencano tasti e combinazioni di tasti, si può fare a meno di questa forma di enfatizzazione.
<vkbd>combinazione_virtuale</vkbd> |
L'elemento vkbd viene usato per indicare tasti o combinazioni di tasti in forma virtuale. La denominazione segue abbastanza quella usata per la configurazione della tastiera della console dei sistemi GNU/Linux. Per esempio si può scrivere <Control_c> (che di solito si ottiene in pratica con la combinazione reale [Ctrl c]) e <Meta_c> (che di solito si ottiene con la combinazione reale [Alt c]).
<kp>tastiera_numerica</kp> |
L'elemento kp viene usato per indicare tasti premuti sulla tastiera numerica, all'interno dell'elemento kbd. Per esempio, <kbd>Ctrl Alt <kp>+</kp></kbd>, indica la richiesta di premere i tasti «control», «alt» e il tasto «+» della tastiera numerica: [Ctrl Alt +].
<button>pulsante_grafico</button> |
L'elemento button viene usato per indicare il nome di pulsanti grafici, anche in presenza di terminali a caratteri, che si selezionano attraverso un cursore o un puntatore grafico. Non si usa questo elemento per indicare l'uso della tastiera normale.
<menuitem>voce_di_menù</menuitem> |
Si delimitano in questo modo le voci di un programma grafico o di uno per terminali a caratteri che abbia un comportamento simile a quelli grafici, che siano riconducibili a scelte di un menù di funzioni. Rientrano in questa situazione i menù a tendina, i nomi delle etichette dei lembi di una sistema di cartelle, oppure il nome di un tipo di selezione che non sia riconducibile a un pulsante.
Questo elemento può essere usato anche per evidenziare le voci che rappresentano un tipo di casella di selezione, oppure le etichette dei campi in cui deve essere inserito qualche tipo di informazione.
<asciicode>nome_ascii</asciicode> |
Si delimitano in questo modo i nomi di caratteri speciali ASCII, che secondo la tradizione sono rappresentati da abbreviazioni con lettere maiuscole, così come le sequenze tradizionali derivate dalla telescrivente. La tabella u113.10 elenca tutti i caratteri che possono essere rappresentati in questo modo, mostrando anche il risultato dell'utilizzo dell'elemento.
La sequenza di più caratteri del genere si ottiene semplicemente mettendo a contatto più elementi asciicode, come per esempio nel caso di <CR><LF>.
<uristr>uri_non_ipertestuale</uristr> |
L'elemento uristr si affianca all'elemento uri, con lo scopo di rappresentare degli indirizzi URI per i quali non si vuole realizzare un riferimento ipertestuale. Ciò si rende necessario quando si scrive un indirizzo di fantasia o un indirizzo che si vuole conservare pur non essendo più valido. Si usa questo elemento anche quando si tratta di nomi a dominio, senza l'indicazione di una risorsa precisa.
<special special="name">nome</special> |
Serviva a delimitare, senza evidenziare, un nome, ma è in corso di eliminazione.
<special special="ttid">termine</special> |
Serve a delimitare, senza evidenziare, un termine particolare, espresso in italiano, per il quale si vuole avere un controllo. In generale ciò serve a seguire delle definizioni che non sono comuni ed è bene mantenere coerenti, per non confondere il lettore. Un'altra ragione per questo utilizzo è quello di facilitare la ricerca di tali definizioni nel momento in cui si decidesse di sostituirle con altre. Ciò si rende necessario perché un termine può avere quel certo significato speciale solo in un contesto particolare; pertanto, solo in questi casi va delimitato così.
I termini delimitati in questo modo sono evidenziati nel capitolo u114 con l'aggiunta di un asterisco.
<special special="ttsc">termine</special> |
Serve a delimitare, senza evidenziare, un termine particolare, espresso in inglese (o in un'altra lingua straniera), che per qualche ragione non sia traducibile, ma che non sia ancora stato acquisito completamente nella lingua italiana. L'elenco di questi termini si trova nella tabella u114.2 (capitolo u114).
<indexentry>...<code>stringa</code>...</indexentry> |
<indexentry>...<kbd>stringa</kbd>...</indexentry> |
<indexentry>...<vkbd>stringa</vkbd>...</indexentry> |
<indexentry>...<kp>stringa</kp>...</indexentry> |
<indexentry>...<asciicode>stringa</asciicode>...</indexentry> |
Nell'ambito delle voci dell'indice analitico, si possono usare alcuni elementi che comportano una forma di evidenziazione particolare. Si tratta di code (che va usato per tutte le situazioni in cui, nel testo normale si userebbe sia samp, sia code), asciicode, kbd, vkbd e kp.
|
Tabella u113.10. Elenco dei caratteri speciali che si possono inserire nell'elemento asciicode.
|
In generale, il contenuto di un file o quanto emesso da un programma attraverso standard output e standard error, viene rappresentato in un elemento per il testo preformattato. Tuttavia, si manifestano dei problemi estetici, dovuti alla suddivisione del testo in pagine e al riconoscimento del contesto.
Per controllare la possibilità o meno di spezzare il testo tra più pagine, si inserisce l'elemento che lo contiene in un riquadro (l'elemento object) fisso, che, a seconda di ciò che si preferisce, possa essere spezzato o meno:
|
In questo caso, evidentemente, si tratta di un listato che non si può spezzare; la scelta se mantenere unito o consentire la divisione in più pagine dipende naturalmente dalla lunghezza del testo.
Per quanto riguarda l'uso di linee e bordi di separazione, all'inizio del sorgente sono dichiarate alcune macro per la definizione dello stile, in modo da consentire in un secondo momento di cambiare l'aspetto generale. Si distinguono i casi seguenti, dimostrati da esempi:
listato riferito al contenuto di un file su disco (che può essere anche uno script);
|
|
listato riferito a quanto emesso attraverso lo standard output o lo standard error;
|
|
listato riferito a quanto appare sullo schermo a seguito dell'utilizzo di un programma interattivo;
|
|
La coerenza in ciò che poi si traduce in forme di enfatizzazione del testo è la cosa più importante da definire e anche la più difficile da mantenere. Tuttavia, ci sono altre considerazioni da fare su elementi che potrebbero sembrare più ovvi.
I titoli della serie tomeheading, h0, h1, h2, h3, h4, testh1, slideh1, sheeth1, faqh2 e qh2, vanno scritti senza inserire enfatizzazioni di alcun genere. Tuttavia, si possono e si devono inserire gli elementi special. In caso di necessità, si può delimitare qualche termine particolare solo usando le parentesi angolari uncinate standard.
Come si vede, a questa regola fanno eccezione faqh3 e qh3 che invece possono contenere le enfatizzazioni comuni di un testo normale.
Le tabelle vanno realizzate nel modo più semplice possibile, cercando di evitare contorsioni, allo scopo di facilitare la lettura anche a un utente che si limiti a scorrere il documento in forma di testo puro e semplice. Solo eccezionalmente è utile la realizzazione di tabelle HTML, racchiuse nell'elemento html, per rappresentare schemi particolari, come nel caso delle schede riepilogative.
Quando una figura può essere realizzata facilmente utilizzando semplicemente caratteri ASCII, conviene evitare la grafica, per consentire la visualizzazione della stessa anche in forma di testo puro. Si ottiene facilmente una figura del genere con l'elemento asciiart, oppure anche solo con verbatimpre.
A seconda dei tipi di composizione si possono avere pagine che hanno altezze molto diverse. Quando si realizza una tabella o una figura, occorre verificare che la composizione A4 normale avvenga correttamente; di conseguenza sono poi corrette anche le altre forme.
Vengono usate delle sezioni marcate per inserire delle annotazioni da ottenere solo nella stampa di bozze. Queste sezioni marcate fanno riferimento all'entità parametrica RM. Di solito si fanno queste annotazioni utilizzando delle note a piè pagina. Si distinguono due tipi di segnalazioni: un'informazione da ricordare e un problema non risolto, da sistemare in un secondo momento. Si osservino i due esempi seguenti:
|
|
«a2» 2013.11.11 --- Copyright © Daniele Giacomini -- appunti2@gmail.com http://informaticalibera.net