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