[indice generale] [precedente] [successivo] [indice analitico] [note introduttive]

94. Stile letterario

Questo capitolo, a conclusione della parte dedicata all'editoria, vuole essere solo un riferimento essenziale alla definizione di uno stile letterario, e il contenitore di una piccola raccolta di regole che dovrebbero semplificare la vita di chi scrive documenti elettronici.

L'autore di questo documento non è proprio la persona migliore per scrivere di queste cose, e lo si può vedere leggendo in qualunque parte di questi Appunti. Tuttavia, è importante almeno affrontare l'argomento sottolineando alcuni concetti importanti.

Come sempre, tutte le segnalazioni di errore sull'ortografia, la sintassi e il contenuto di questo documento, sono gradite.

94.1 Uniformità

Il concetto di stile letterario potrebbe essere espresso semplicemente spiegando l'esigenza che c'è di realizzare un documento uniforme: sia dal punto di vista visivo, sia dal punto di vista espressivo. Questo coinvolge quindi l'aspetto grammaticale (ortografia, sintassi, lessico, ecc.) e l'aspetto estetico-tipografico (impaginazione, tipi di carattere, dimensione, ecc.) o artistico.

L'esigenza di una uniformità visiva deriva dal piacere e dal rilassamento che può dare al lettore un documento impaginato e strutturato in un modo ordinato e chiaro. Nello stesso modo è importante l'uniformità grammaticale, cosa particolarmente delicata in una lingua come la nostra in cui sono consentite molte variazioni, data la varietà linguistico-culturale delle varie regioni.

Il novello scrittore di documentazione tecnica, che scrive e impagina senza l'aiuto di un editore, tende a comprendere l'esigenza di uno stile tipografico, dimenticando che esiste anche uno stile espressivo-grammaticale.

94.1.1 Lavoro di gruppo

Il problema dell'uniformità stilistica si accentua quando si deve collaborare alla realizzazione di un progetto letterario. L'uniformità non è più solo un fatto di coerenza personale, ma di coerenza complessiva di tutto il gruppo.

La coordinazione dei vari collaboratori è un problema delicato, e diviene essenziale la stesura di uno standard letterario complessivo. Alle volte questo ferisce la sensibilità di alcuni collaboratori e genera discussioni senza fine, né soluzione. *1*

94.2 Regole di composizione del testo

Il modo migliore per definire uno stile grammaticale è lo studio su un testo di grammatica. Qui si vogliono solo raccogliere alcuni punti essenziali che non possono essere ignorati. In effetti, il tipico autore di testi a carattere tecnico, specialmente in ambito volontario come nel caso di questo documento, ha un'ottima conoscenza dell'argomento trattato, e una pessima padronanza della lingua.

94.2.1 Punteggiatura e spaziatura

La punteggiatura si compone di quei simboli che consentono di separare le parole e di delimitare le frasi.

94.2.2 Utilizzo dei simboli di interpunzione

L'uso della punteggiatura nella lingua italiana è definito da regole molto vaghe che si prestano a facili eccezioni di ogni tipo. Qui si elencano solo alcuni concetti fondamentali.

94.2.3 Accenti e troncamenti

Nella lingua italiana scritta, l'uso degli accenti è un fatto puramente convenzionale. Ciò significa che l'accento non indica necessariamente il suono che ha effettivamente la lettera accentata, ma solo la sua rappresentazione consueta. *2*

indicativo di dare (dà valore) da preposizione (da voi)
è verbo e congiunzione
avverbio (resta là) la articolo
avverbio (vado lì) li pronome
congiunzione (né questo né quello) ne pronome (ne voglio ancora)
pronome tonico (pieno di sé) se pronome atono o congiunzione
avverbio (dice di sì) si pronome

Tabella 94.1: Elenco dei monosillabi accentati più importanti e dei loro equivalenti (omografi) non accentati.

Alle volte, l'uso delle vocali accentate può creare problemi tecnici, dovuti alla loro mancanza nell'insieme di caratteri a disposizione. In Italia, e nei paesi dell'Europa centrale, si utilizza la codifica ISO-8859-1 (latin-1) che contiene tutte le nostre lettere accentate. Nelle circostanze in cui ciò non è attuabile (per esempio quando si dispone di un sistema configurato male, o la tastiera non dispone dei simboli necessari), occorre utilizzare delle tecniche di rappresentazione che dipendono dal programma utilizzato per la composizione.

94.2.3.1 SGML

SGML, comprendendo in questo anche HTML, dispone di una serie di codici macro standardizzati elencati nella tabella 94.2.

Vocale accentata Macro corrispondente
à à
è è
ì ì
ò ò
ù ù
é é

Tabella 94.2: Vocali accentate attraverso l'uso di macro SGML.

94.2.3.2 TeX - LaTeX

TeX, e di conseguenza LaTeX, dispongono di una serie di codici elencati nella tabella 94.3.

Vocale accentata Codice TeX corrispondente
à \`a
è \`e
ì \`{\i}
ò \`o
ù \`u
é \'e

Tabella 94.3: Vocali accentate per TeX.

94.2.3.3 Testo puro

Quando si scrive un file di testo puro e semplice, e non è possibile utilizzare la codifica ISO-8859-1, si può utilizzare un trucco con cui si usa un apice opportuno subito dopo la vocale da accentare. Naturalmente questa tecnica può valere solo per la lingua italiana in cui gli accenti si pongono solo nelle vocali finali. Visivamente il risultato è molto simile a quello corretto.

Vocale accentata Vocale apostrofata corrispondente
à a`
è e`
ì i`
ò o`
ù u`
é e'

Tabella 94.4: Trucco per rappresentare le vocali accentate quando non si può fare altrimenti.

94.2.4 Uso delle maiuscole

L'iniziale maiuscola si utilizza all'inizio del periodo e per evidenziare i nomi propri. Nel dubbio è meglio evitare di utilizzare le maiuscole. La lingua italiana fa un uso diverso delle maiuscole rispetto ad altre lingue. Il novello scrittore di documenti tecnici tende a lasciarsi influenzare dall'uso che si fa delle maiuscole nella lingua inglese. Per questo è bene ribadire che in italiano l'uso di queste deve essere ridotto al minimo indispensabile.

94.2.5 Plurali

94.2.6 Elenchi

Gli elementi puntati, o numerati, possono essere composti da elementi brevi, oppure da interi periodi. Se tutti gli elementi sono brevi:

La descrizione appena fatta mostra un esempio di elenco del genere. Se anche uno solo degli elementi è troppo lungo, è bene trasformare tutti gli elementi in periodi terminati da un punto. In tal caso, se l'elenco viene introdotto da una frase, anch'essa termina con un punto.

Ci possono essere situazioni in cui queste indicazioni non sono applicabili: come sempre è necessario affidarsi al buon senso.

94.3 Traduzioni e termini stranieri

Le traduzioni rappresentano un problema in più, dal punto di vista dell'uniformità stilistica espressiva, soprattutto perché sono frequentemente il risultato di un lavoro di gruppo. Il problema più grave è rappresentato dalla traduzione o dall'acquisizione di quei termini che non fanno parte del linguaggio comune.

L'attività di traduzione è tanto più delicata se si considerano i vincoli posti dalle convenzioni internazionali che regolano l'editoria. In breve, la traduzione deve essere autorizzata dall'autore originale, verso il quale ci si assume la responsabilità del buon esito di questa operazione.

Per questo, la traduzione non può alterare il contenuto espresso dall'autore originale, e nemmeno chiarirlo. Nello stesso modo, una traduzione deve sempre essere accompagnata dall'indicazione dei nomi dei traduttori che l'hanno realizzata.

94.3.1 Quando non si traduce

Come sempre, la scelta di tradurre o meno un termine tecnico deve essere affidata al buon senso, e al confronto con altri traduttori. Qui si elencano brevemente alcuni punti su cui si può basare la decisione di non tradurre.

94.3.2 Acquisizione di termini inglesi

Quando si decide di lasciare inalterato il termine straniero nel testo italiano, si pone il problema di stabilire il modo con cui questo possa convivere con il resto del testo. L'unica regola sicura è la verifica dell'uso generale, attraverso la discussione nelle liste specializzate. Tuttavia si possono definire alcune regole di massima, per dare l'idea del problema.

È importante osservare che nell'ambito delle traduzioni di documenti tecnici, nella stragrande maggioranza dei casi, si ha a che fare con l'inglese. Infatti, l'acquisizione di un termine straniero tende a seguire logiche differenti a seconda della lingua di origine. Per comprenderlo basta pensare con quanta facilità si potrebbe acquisire un termine francese, come ``console'', rispetto a un termine inglese.

Quando il termine che non si traduce non è di uso comune nell'ambiente a cui si rivolge il documento, dovrebbe essere evidenziato in corsivo tutte le volte che viene utilizzato. Per chiarire meglio il concetto, un termine tecnico può essere o meno di uso comune per il pubblico di lettori a cui si rivolge: se si tratta di un termine considerato normale per quell'ambiente, non è il caso di usare alcuna evidenziazione.

94.3.3 Stesura di un glossario

Quando si traduce un documento è importante la preparazione di un glossario, ossia una raccolta di traduzioni standard che permettono di mantenere uniformità nel documento tradotto. Questo diventa tanto più importante quando si lavora in gruppo, o si partecipa alla traduzione di un gruppo di opere che fanno parte di uno stesso ambito tecnico.

Un glossario del genere non può essere un documento statico, in quanto si ha la necessità di aggiornare continuamente il suo contenuto; se non altro per estenderlo.

Nell'ambito della documentazione Linux, ci si può iscrivere alla lista it@li.org per chiedere informazioni sul lavoro già svolto e per discutere termini non ancora definiti dal glossario in corso di realizzazione. Per iscriversi basta inviare un messaggio email a majordomo@li.org contenente nel corpo (e non nell'oggetto) il testo seguente.

subscribe it

L'invio di messaggi al gruppo di discussione va indirizzato poi a it@li.org.

Eventualmente si può scaricare il glossario attuale da ftp://ftp.linux.it/pub/ILS/People/md/glossario.tgz, tenendo presente che il moderatore della lista desidera che non sia ulteriormente distribuito, in modo da evitare che si diffondano versioni obsolete.

Come ultima nota è opportuno chiarire che un glossario per la traduzione può essere solo uno strumento, per l'utilizzo da parte di persone in grado di capire il contesto in cui i termini sono usati, e di stabilire se le voci corrispondenti del glossario sono applicabili alle situazioni particolari.

94.3.4 Opere originali

Anche l'autore di un'opera originale di carattere tecnico, si imbatte in problemi simili a quelli dei traduttori. Infatti, quando l'acquisizione di un termine tecnico straniero riguarda solo l'ambito specializzato per il quale si scrive, si può dubitare del modo giusto di utilizzarlo.

Per questo, anche gli autori di opere originali possono avere la necessità di preparare un glossario e di discutere le espressioni migliori per un determinato concetto.

94.4 Stile tipografico

La definizione dello stile tipografico è un altro punto delicato nella definizione dello stile letterario generale. Di solito, la sua preparazione, è compito del tipografo o del coordinatore di un gruppo di autori/traduttori.

Il modo migliore per stabilire e utilizzare uno stile tipografico è quello di usare un sistema SGML, attraverso cui definire un DTD che non permetta alcun dubbio nella relazione che ci deve essere tra le varie componenti di un documento. In questo modo, gli autori hanno solo in compito di qualificare correttamente le varie componenti del testo, senza pensare al risultato finale, per modificare il quale si può semmai intervenire sul sistema di conversione successivo.

Le sezioni seguenti trattano dei problemi legati alla definizione di uno stile tipografico per la redazione di documenti tecnico-informatici, mostrando prevalentemente esempi in SGMLtools (LinuxDoc) e a volte anche in LaTeX. L'idea è presa dalla guida di stile del gruppo di documentazione Linux: LDP (Linux Documentation Project), ma le indicazioni si basano sulle consuetudini tipografiche italiane.

94.4.1 Blocchi di testo

Scrivendo documenti che riguardano l'uso del computer, si incorre frequentemente nella necessità scrivere nomi, o intere parti di testo, che devono essere trattati in modo letterale. Può trattarsi di nomi di file e directory, comandi, porzioni del contenuto di file, listati di programmi, ecc. In questi casi è sconsigliabile l'uso di un tipo di carattere proporzionale, perché si rischierebbe di perdere delle informazioni importanti. Si pensi al trattino utilizzato nelle opzioni della maggior parte dei comandi Unix: utilizzando un carattere proporzionale, attraverso un sistema di composizione come LaTeX, si otterrebbe un trattino corto, mentre due trattini posti di seguito genererebbero un trattino normale; e ancora, da tre trattini si otterrebbe un trattino largo.

Altri tipi di problemi sono dati da nomi di altro genere, come i marchi di fabbrica, e dalla necessità di marcare dei concetti quando appaiono per la prima volta.

94.4.1.1 Nomi di file e directory

94.4.1.2 Schermate, listati, e simili

Il testo ottenuto da listati di vario tipo, come gli spezzoni di un programma sorgente, il risultato dell'elaborazione di un comando, o il contenuto di una schermata, possono essere rappresentati convenientemente attraverso un ambiente di inclusione di testo letterale a spaziatura fissa. Generalmente, con LinuxDoc si utilizza l'ambiente verb contenuto in tscreen (l'uso dell'ambiente code è sconsigliabile).

Il problema sta nel fatto che l'ampiezza di tale testo non può superare i margini del corpo del documento, in base al tipo di impaginazione finale che si ritiene dover applicare. Infatti, tale testo non può essere continuato nella riga successiva perché ciò costituirebbe una alterazione delle informazioni che si vogliono mostrare.

Generalmente, non è possibile superare una ampiezza di 80 colonne, pari a quella di un normale schermo a caratteri.

94.4.1.3 Variabili di ambiente

La scelta di rappresentare le variabili utilizzando il dollaro come prefisso, è motivata dalla facilità con cui questa può essere identificata durante la lettura del testo. Tuttavia, questa scelta potrebbe essere discutibile, perché il dollaro non appartiene al nome della variabile, e perché potrebbe indurre il lettore a utilizzarlo sempre, anche quando negli script non si deve. Quindi, il buon senso deve guidare nella decisione finale.

94.4.1.4 Comandi e istruzioni

A volte si ha la necessità di indicare un comando, o una istruzione, all'interno del testo normale. Per questo, è opportuno utilizzare un carattere a spaziatura fissa, come nel caso dei nomi di file e directory, però qui si pone un problema nuovo dovuto alla possibile presenza di spazi e trattini. I programmi di composizione normali tendono a interrompere le righe, quando necessario, in corrispondenza degli spazi ed eventualmente anche dei trattini. Se il comando o l'istruzione che si scrive è breve, è consigliabile l'utilizzo di spazi e trattini non interrompibili. *3*

Quando si utilizza SGML (compreso HTML), si può usare l'entità   per indicare uno spazio non interrompibile, mentre se si usa solo LaTeX, è il carattere tilde (~) che ha questa funzione.

Il problema del trattino non è semplice, perché non esiste un trattino generico non separabile, fine a se stesso. Di trattini ne esistono di varie misure e non sempre esistono corrispondenti per diversi tipi di programmi di composizione.

94.4.1.5 Nomi di applicativi

Quando si fa riferimento al nome di un programma, si pongono due alternative: l'indicazione del file eseguibile oppure del nome attribuito dall'autore al suo applicativo.

Per comprendere la differenza, si può pensare ad Apache: il server HTTP. Non si tratta di un semplice eseguibile, ma di un applicativo composto da diverse parti, in cui l'eseguibile è httpd. Nello stesso modo, nel caso di Perl (il linguaggio di programmazione), si può pensare all'applicativo in generale, composto dalle librerie e tutto ciò che serve al suo funzionamento; oppure si può voler fare riferimento solo all'eseguibile: perl.

Esempi

Ghostscript è un programma molto importante.

nanoBase è un semplice applicativo per Dos.

94.4.1.6 Concetti e termini nuovi

Per questo tipo di evidenziazione si utilizza generalmente un grassetto, meglio ancora se si tratta di un grassetto-corsivo. Ciò è contrario alla tradizione dei testi italiani, in cui questo viene fatto normalmente utilizzando il corsivo puro e semplice. Tuttavia, il grassetto si presta meglio alla composizione in formati molto diversi; per esempio è facilmente ottenibile anche su un documento da visualizzare attraverso uno schermo a caratteri.

Esempi

Questo meccanismo permette di inserire le cosiddette entità interne, con cui si possono definire delle macro.

94.4.1.7 Termini stranieri

A volte è opportuno utilizzare termini stranieri, non tradotti. Quando si tratta di termini non ben acquisiti nel linguaggio comune, almeno per il pubblico a cui si rivolge il documento, è opportuno utilizzare il corsivo tutte le volte in cui il termine viene adoperato.

Un termine tecnico può essere o meno di uso comune per il pubblico di lettori a cui si rivolge: se si tratta di un termine considerato normale per quell'ambiente, non è il caso di usare alcuna evidenziazione.

94.4.1.8 Nomi proprietari

L'indicazione di nomi che fanno riferimento a marchi di fabbrica o simili, va fatta come appare nel copyright o nella nota che fa riferimento al brevetto, rispettando l'uso delle maiuscole e dell'eventuale punteggiatura. Si dovrebbe evitare quindi, di prendere in considerazione un eventuale logo del prodotto. Non è opportuno fare risaltare maggiormente i nomi di questo tipo.

All'interno del testo non è conveniente fare riferimento al detentore del copyright o del brevetto. Di questo problema dovrebbero farsi carico delle note opportune all'inizio del documento che si scrive.

Esempi

Sistema di stampa PostScript...

Scheda SCSI Adaptec...

Unità magnetoottica FUJITSU...

Hewlett Packard

94.4.2 Titoli

Nei testi di lingua italiana, i titoli vanno scritti come se si trattasse di testo normale, con le particolarità seguenti.

Un documento a carattere tecnico viene normalmente suddiviso in segmenti a più livelli. Per avere maggiore facilità nella trasformazione del documento in diversi formati tipografici finali, conviene limitare la scomposizione a un massimo di due livelli. Nel caso di SGMLtools, significa limitarsi a usare sect e sect1.

94.4.2.1 Didascalie

Gli elementi che non fanno parte del flusso normale di un documento, come tabelle e figure, sono generalmente accompagnate da un titolo e da una didascalia. Il titolo serve a identificarle, mentre la didascalia ne descrive il contenuto.

I titoli di tabelle, figure e oggetti simili, seguono le regole dei titoli normali, mentre il testo delle didascalie segue le regole del testo normale. Tuttavia, quando si utilizzano programmi di composizione che permettono di abbinare solo una nota descrittiva, che funga sia da titolo che da didascalia, occorre fare una scelta:

Naturalmente, la scelta fatta deve valere per tutte le descrizioni che si abbinano a questi oggetti di un particolare documento: brevi o lunghe che siano.

94.4.2.2 Elenchi descrittivi

Gli elenchi descrittivi, come quelli che si ottengono con LinuxDoc utilizzando la struttura seguente, possono essere insidiosi, perché potrebbero tradursi in modo differente a seconda del tipo di programma di composizione utilizzato.

<descrip>
<tag>Primo elemento</tag>
	Descrizione del primo elemento,...
	Bla bla bla...
</descrip>

L'elemento descrittivo dell'elenco è in pratica un titolo che introduce una parte di testo generalmente rientrata. Sotto questo aspetto, questo titolo segue le regole già viste per i titoli. Tuttavia, il problema sta nel fatto che si potrebbe essere indotti a riprendere un discorso lasciato in sospeso quando veniva introdotto l'elenco, come nell'esempio seguente.

Bla bla bla bla...

Primo elemento

	Descrizione del primo elemento,...
	Bla bla bla...

Qui si riprende il discorso precedente all'elenco descrittivo.
...

Infatti, l'utilizzo dei rientri fa percepire immediatamente la conclusione dell'elenco stesso. Quando si scrive un documento che dove poter essere convertito in molti formati differenti, che quindi potrebbe essere elaborato da programmi di composizione di vario tipo, può darsi che i rientri vengano perduti, e gli elementi descrittivi dell'elenco appaiano come dei titoli veri e propri. Ma se ciò accade, quando si ricomincia ``il discorso lasciato in sospeso'', sembra che questo appartenga all'argomento dell'ultimo titolo apparso.

Bla bla bla bla...

Primo elemento

Descrizione del primo elemento,...
Bla bla bla...

Qui si riprende il discorso precedente all'elenco descrittivo.
...

Pertanto, se si vogliono utilizzare strutture di questo tipo, è consigliabile che appaiano alla fine di una sezione, quando quello che viene dopo è un titolo di una sezione o di qualcosa di simile.

94.4.3 Note a piè di pagina

Le note a piè pagina sono composte con le stesse regole del testo normale. Quando il riferimento a una nota a piè pagina si trova alla fine di una parola cui segue un segno di interpunzione, è opportuno collocare tale riferimento dopo il simbolo di interpunzione stesso.

94.4.4 Indicizzazione

La costruzione di un indice analitico deriva dall'inserzione di riferimenti all'interno del testo, attraverso opportune istruzioni definite dal tipo di programma usato per la composizione.

LinuxDoc consente attualmente di inserire tali riferimenti all'interno del testo, utilizzando gli ambienti nidx e ncdx, che vengono poi gestiti solo nella composizione attraverso LaTeX, e ignorati in tutti gli altri casi. ncdx si usa per i nomi tecnici (file, directory, variabili di ambiente, ecc.), mentre nidx per tutti gli altri tipi di riferimento.

Le voci inserite in questi riferimenti, che poi formeranno l'indice generale, vanno scelte in modo da essere uniformi, secondo alcune semplici regole.

I riferimenti per la generazione dell'indice generale vanno posti preferibilmente nei luoghi opportuni, in modo da evitare inutili rimandi a pagine che non contengono ciò che si cerca. Per esempio, la parola file potrebbe trovarsi in quasi tutte le pagine di un testo di informatica, mentre sarebbe conveniente che l'indice analitico riporti solo le pagine in cui si parla del concetto che questa parola rappresenta.

I nomi di programmi eseguibili e di file di dati standard, dovrebbero essere inseriti nell'indice analitico, ogni volta che appaiono nel testo.

94.4.5 Riferimenti bibliografici e simili

I riferimenti ad altri documenti dovrebbero contenere tutti gli elementi necessari a identificare la pubblicazione:

Generalmente è consigliabile comporre gli elenchi bibliografici indicando le opere a partire dall'autore, mettendo il titolo in testo corsivo o inclinato, e separando le varie componenti di ogni riferimento bibliografico attraverso delle virgole.

Esempi

Claudio Beccari, LaTeX, Guida a un sistema di editoria elettronica, Hoepli, 1991

94.4.5.1 Riferimenti all'interno del testo

Esempi

Questa sezione fa riferimento a concetti contenuti in LaTeX, Guida a un sistema di editoria elettronica, di Claudio Beccari.

94.5 Riferimenti

---------------------------

AppuntiLinux 1998.11.22 --- Copyright © 1997-1998 Daniele Giacomini - daniele@calion.com


1.) Il vero artista è colui che crea qualcosa di nuovo e non accetta di sottostare alle regole generali. È evidente quindi che costui non potrà lavorare in un gruppo perché non si sottometterà mai alle regole poste dagli altri o dalla consuetudine.

2.) Nell'ambito della documentazione tecnica, sarebbe consigliabile di evitare l'uso di accentazioni non comuni, anche se queste potrebbero essere preferibili in ambienti più raffinati.

3.) Naturalmente questo ha senso se poi il programma di composizione non tenta di suddividere le parole in sillabe.


[indice generale] [precedente] [successivo] [indice analitico] [note introduttive]