Quando si scrive un articolo, un commento nel forum, o anche solo una pagina del blog, capita spesso di dover inserire alcune porzioni di codice, ad esempio per riportare un file di configurazione, o per indicare comandi da dare in una shell.

A differenza del testo discorsivo, in cui gli spazi e gli "a capo" possono essere modificati con grande libertà per riempire al meglio lo spazio disponibile sulla pagina, il codice dev'essere riportato così com'è, rispettando la spaziatura originaria e possibilmente usando un carattere a larghezza fissa, senza legature e con glifi chiaramente distinguibili.

C'è un metodo semplicissimo per ottenere tutto questo: basta racchiudere il codice tra i tag [code] e [/code].

Esistono due varianti di questi tag: il modo in linea e quello in blocco. Il primo si usa quando si vuole inserire all'interno del normale testo una piccola porzione di codice, tipicamente una parola chiave (come vm.dirty_writeback_centisecs), o il nome di un file (come /etc/apt/sources.list), o ancora un comando molto breve (come chmod a+r *.jpg). In questi casi è sufficiente circondare le parole chiave con i tag, così:

[code]/etc/sources.list[/code]

La variante in blocco si usa invece per creare un paragrafo a sé stante contenente solo codice, ad esempio per riportare un estratto di un file:

deb http://it.archive.debian.org/debian/ testing main
# Uncomment the following line to include non-free packages
#deb http://it.archive.debian.org/debian/ testing contrib non-free

Questa modalità si attiva andando a capo subito dopo il tag [code], così:

[code]
deb http://it.archive.debian.org/debian/ testing main
# Uncomment the following line to include non-free packages
#deb http://it.archive.debian.org/debian/ testing contrib non-free
[/code]

Linguaggi diversi

Quando si riporta una porzione di codice è buona norma indicarne il linguaggio. Così facendo, le parole chiave e gli altri costrutti tipici di quel linguaggio sono automaticamente evidenziati con colori diversi, per facilità di lettura.

Il linguaggio va specificato modificando leggermente il tag di apertura aggiungendo l'attributo lang: ad esempio [code lang=bash] segnala l'inizio di uno script per la shell, [code lang=c] indica un pezzo di sorgente in linguaggio C, e così via.

I seguenti linguaggi sono definiti:

• "bash" - comandi e script per la shell Bash
• "c" e "cpp" - linguaggi C e C++
• "cmdline" - trascrizione di sessioni di shell (vedere dettagli più sotto)
• "java", "javascript", "php", "python" e "ruby" - comuni linguaggi di programmazione e markup
• "xorg" - file di configurazione xorg.conf

Numeri di riga

A volte è utile inserire un estratto di file indicando sulla sinistra i numeri di riga. Ecco un esempio che mostra, al contempo, l'uso del linguaggio "xorg":

Section "Extensions"
  Option "Composite" "Enable"
EndSection
 
Section "DRI"
  Mode 0666
EndSection

Questo effetto si ottiene aggiungendo al tag di apertura l'attributo start=1 (dove al posto di 1 si può mettere il numero da cui deve partire la numerazione). Ovviamente questo attributo si può aggiungere a quello per specificare il linguaggio; il riquadro precedente è stato infatti ottenuto con questo codice:

[code lang=xorg start=1]
Section "Extensions"
  Option "Composite" "Enable"
EndSection
 
Section "DRI"
  Mode 0666
EndSection 
[/code]

È bene comunque non abusare di questa funzionalità, perché i numeri sulla sinistra rendono difficile per il lettore copiare e incollare la porzione di codice.

Approfondimento su bash e cmdline

Tra i vari linguaggi riconoscuti, due sono particolarmente utili in un forum che tratta di problemi di installazione e configurazione: "bash" e "cmdline".

Il primo si usa per riportare uno script di shell o sue porzioni. Dà per scontato che ogni riga sia un comando shell. Riconosce i costrutti tipici della shell Bash, evidenziando con colori diversi variabili, comandi, parole chiave, opzioni, stringhe e commenti.

Il secondo è molto simile, ma applica la formattazione solo alle righe che iniziano con # o $ e lascia inalterate le altre. Si usa quando si vuole riportare un misto di comandi dati in una shell e gli output di tali comandi. È molto comune imbattersi in passaggi come il seguente:

$ grep root /etc/shadow
grep: /etc/shadow: Permesso negato
$ su
Password:
# grep root /etc/shadow
root:$6$41pzW$7kC2pzLeJfgwkYB/Ww9Edb:14853:0:99999:7:::

La prima e la terza riga sono comandi impartiti dall'utente, come suggerisce il prompt $; la quinta riga è un comando dato come amministratore, come suggerisce il prompt #. Tutte le altre sono l'output stampato a video. Racchiudendo questo blocco tra i tag [code lang=cmdline] e [/code], la formattazione viene applicata alla prima, terza e quinta riga, mentre "salta" le altre. Per inciso, l'effetto finale è esattamente quello che si può osservare nel riquadro precedente. Il riquadro che segue, invece, è ciò che si otterrebbe specificando, per puro esercizio, il linguaggio "bash" invece che "cmdline":

$ grep root /etc/shadow
grep: /etc/shadow: Permesso negato
$ su
Password:
# grep root /etc/shadow
root:$6$41pzW$7kC2pzLeJfgwkYB/Ww9Edb:14853:0:99999:7:::

Come si può notare, la formattazione è del tutto errata e fuorviante.

Infine, quando si usa il linguaggio "cmdline", occorre ricordarsi di usare come prompt un semplice # oppure $ e non prompt più complessi come quello dell'esempio seguente, che infatti non viene riconosciuto!

root@localhost:/usr/local $ uname -a
Linux 2.6.32 #1 SMP Fri Jun 27 03:23:20 UTC 2008 i686 GNU/Linux

Trucchetti

Una volta capito come funziona il tag [code], è utile conoscere alcune scorciatoie.

Innanzitutto il linguaggio "bash" è quello predefinito e non è quindi necessario esplicitarlo.

Il secondo trucco è che [code lang=x]...[/code] si può abbreviare in [x]...[/x], qualunque sia x.

Infine, i tag possono essere scritti nello stile BBcode, cioè racchiusi da parentesi quadre (come in questa guida), oppure nello stile HTML, cioè racchiusi tra i segni di minore e maggiore.

Mettendo insieme questi trucchi, ecco modi diversi ma del tutto equivalenti per riportare uno script di shell:

• [code]...[/code]
• [code lang=bash]...[/code]
• [bash]...[/bash]
• <code>...</code>
• <bash>...</bash>

Guida di Matteo Cortese su DebianItalia.org