Introduzione¶

Questa guida mette in evidenza le opzioni di formattazione più avanzate, tra cui ammonizioni, elenchi numerati, tabelle e altro ancora.

Un documento può contenere o meno uno di questi elementi. Se ritenete che il vostro documento possa beneficiare di una formattazione speciale, questa guida vi aiuterà.

Una nota sulle Intestazioni

Le intestazioni non sono caratteri speciali di formattazione, ma sintassi standard di markdown. Includono una singola voce di primo livello:

# Questo è il Primo Livello

e un numero qualsiasi di valori di sottovoci, dai livelli 2 a 6:

## Un livello 2 heading
### Un livello 3 heading
#### Un livello 4 heading
##### Un livello 5 heading
###### Un livello 6 heading

La chiave è che si possono usare tutti i titoli dal 2 al 6, ma solo UNO di livello 1. Mentre il documento viene visualizzato correttamente con più di un'intestazione di livello 1, l'indice generato automaticamente per il documento, che appare sul lato destro, NON viene visualizzato correttamente (o talvolta per niente) con più di un'intestazione. Tienilo a mente quando scrivi i tuoi documenti.

Ammonimenti¶

Gli ammonimenti sono speciali "riquadri" visivi che consentono di richiamare l'attenzione su fatti importanti e di metterli in evidenza. Di seguito sono elencati i tipi di ammonimenti:

tipo	Descrizione
note	visualizza il testo in un riquadro blu
abstract	visualizza il testo in un riquadro azzurro
info	visualizza il testo in un riquadro blu-verde
tip	visualizza il testo in un riquadro blu-verde (icona leggermente più verde)
success	visualizza il testo in un riquadro verde
question "Domanda"	visualizza il testo in un riquadro verde chiaro
warning	visualizza il testo in un riquadro arancione
failure	visualizza il testo in un riquadro rosso chiaro
danger "Pericolo"	visualizza il testo in un riquadro rosso
bug	visualizza il testo in un riquadro rosso
example	visualizza il testo in un riquadro viola
quote	visualizza il testo in una casella grigia
custom ₁	visualizza sempre il testo in un riquadro blu
custom ₂	visualizza il testo nel colore del riquadro della tipologia prescelta

Gli ammonimenti sono illimitati, come si può notare in custom ₁ sopra. È possibile aggiungere un titolo personalizzato a qualsiasi tipo di ammonimento per ottenere il colore del riquadro desiderato per un ammonimento specifico, come indicato nel precedente custom ₂ personalizzato.

Un'ammonimento viene sempre inserito in questo modo:

!!! admonition_type "titolo personalizzato, se presente".

    testo dell'ammonimento

Il testo del corpo dell'ammonimento deve avere un rientro di quattro (4) spazi dal margine iniziale. È facile capire dove si trova, perché sarà sempre allineato sotto la prima lettera del tipo di ammonimento. La riga in più tra il titolo e il corpo non verrà visualizzata, ma il nostro motore di traduzione (Crowdin) ne ha bisogno per funzionare correttamente.

Qui ci sono esempi di ogni tipo di ammonimento e come appariranno nel vostro documento:

Note

testo

Abstract

testo

Info

testo

Tip

testo

Success

testo

Question

testo

Warning

testo

Failure

testo

Danger

testo

Titolo personalizzato

Un tipo custom ₁. Abbiamo usato " custom" come tipo di ammonimento. Di nuovo, questo risulterà sempre in blu.

titolo personalizzato

Un tipo custom ₂. Abbiamo modificato il tipo di ammonimento "warning" con un'intestazione personalizzata. Ecco come appare:

!!! warning "titolo personalizzato"

Ammonimenti espandibili¶

Se un ammonimento ha un contenuto molto lungo, prendete in considerazione un ammonimento espandibile. Ha le stesse caratteristiche di un ammonimento regolare, ma inizia con tre punti interrogativi, anziché con tre punti esclamativi. Si applicano tutte le altre regole degli ammonimenti. Un ammonimento espandibile assomiglia a questo:

Avvertenze sul contenuto

Si tratta di un avviso, con poco contenuto. Per questo si dovrebbe usare un ammonimento normale, ma questo è solo un esempio!

Che si presenta così nell'editor:

??? warning "Avvertenze sul contenuto"

    Si tratta di un avviso, con poco contenuto. Per questo si dovrebbe usare un ammonimento normale, ma questo è solo un esempio!

Contenuto a schede all'interno di un documento¶

La formattazione dei contenuti a schede è simile a quella degli ammonimenti. Invece di tre punti esclamativi o tre punti interrogativi, inizia con tre segni uguali. Tutta la formattazione dell'ammonimento (4 spazi, ecc.) si applica a questo contenuto. Ad esempio, la documentazione potrebbe richiedere una procedura diversa per una diversa versione di Rocky Linux. Quando si usa il contenuto a schede per le versioni, la release più recente di Rocky Linux deve essere la prima. Al momento della stesura del presente documento, il codice è 9.0:

9.08.6

La procedura per farlo in 9.0

La procedura per farlo in 8.6

Che si presenterebbe così nell'editor:

=== "9.0"

    La procedura per farlo in 9.0

=== "8.6"

    La procedura per eseguire questa operazione in 8.6

Ricordate che tutto ciò che rientra nella sezione deve continuare a utilizzare il rientro di 4 spazi fino al completamento della sezione. Questa è una funzione molto utile!

Liste numerate¶

Le liste numerate sembrano facili da creare e da usare e, una volta che ci si è abituati, lo sono davvero. Se si dispone di un unico elenco di elementi senza alcuna complessità, questo tipo di formato va bene:

1. Elemento 1

2. Elemento 2

3. Elemento 3

Elemento 1
Elemento 2
Elemento 3

Se è necessario aggiungere blocchi di codice, righe multiple o addirittura paragrafi di testo a un elenco numerato, il testo deve avere la stessa indentazione di quattro (4) spazi utilizzata per gli ammonimenti.

Tuttavia, non è possibile allinearli con gli occhi sotto l'elemento numerato perché questo ha uno spazio in meno. Se si utilizza un buon editor di markdown, è possibile impostare il valore di tabulazione a quattro (4), il che renderà la formattazione un po' più semplice.

Ecco un esempio di elenco numerato a più righe, con un blocco di codice aggiunto per buona norma:

Quando si tratta di elenchi numerati a più righe che includono blocchi di codice o altri elementi, si può usare l'indentazione spaziale per ottenere ciò che si desidera.

Ad esempio: questo ha un rientro di quattro (4) spazi e rappresenta un nuovo paragrafo di testo. Inoltre, aggiungiamo un blocco di codice all'interno. È anche rientrato degli stessi quattro (4) spazi del nostro paragrafo:
```
dnf update
```
Ecco il nostro secondo articolo in elenco. Poiché si è utilizzato il rientro di quattro (4) spazi (sopra), viene visualizzato con la sequenza di numerazione successiva (2), ma se si fosse inserito l'elemento 1 senza il rientro (nel paragrafo e nel codice successivi), questo verrebbe visualizzato di nuovo come elemento 1, il che non è ciò che si desidera.

Ecco come appare il testo raw:

1. Quando si tratta di elenchi numerati a più righe che includono blocchi di codice o altri elementi, si può usare l'indentazione spaziale per ottenere ciò che si desidera.

    Ad esempio: questo ha un rientro di quattro (4) spazi e rappresenta un nuovo paragrafo di testo. Inoltre, aggiungiamo un blocco di codice all'interno. È anche rientrato degli stessi quattro (4) spazi del nostro paragrafo:

    ```


    dnf update
    ```

2. Ecco il nostro secondo articolo in elenco. Poiché si è utilizzato il rientro di quattro (4) spazi (sopra), viene visualizzato con la sequenza di numerazione successiva (2), ma se si fosse inserito l'elemento 1 senza il rientro (nel paragrafo e nel codice successivi), questo verrebbe visualizzato di nuovo come elemento 1, il che non è ciò che si desidera.

Tabelle¶

Le tabelle ci aiutano a disporre le opzioni di comando o, nel caso precedente, i tipi di ammonimento e le descrizioni. Ecco come è stata inserita la tabella nella sezione Ammonimenti:

| tipo      | Descrizione                                                                     |
|-----------|---------------------------------------------------------------------------------|
| note      | visualizza il testo in un riquadro blu                                          |
| abstract  | visualizza il testo in un riquadro blu                                          |
| info      | visualizza il testo in un riquadro blu-verde                                    |
| tip       | visualizza il testo in un riquadro blu-verde (icona leggermente più verde)      |
| success   | visualizza il testo in un riquadro verde                                        |
| question  | visualizza il testo in un riquadro verde chiaro                                 |
| warning   | visualizza il testo in un riquadro verde chiaro                                 |
| failure   | visualizza il testo in un riquadro rosso chiaro                                 |
| danger    | visualizza il testo in un riquadro rosso                                        |
| bug       | visualizza il testo in un riquadro rosso                                        |
| example   | visualizza il testo in un riquadro viola                                        |
| quote     | visualizza il testo in una casella grigia                                       |
| custom <sub>1</sub> | visualizza sempre il testo in un riquadro blu                         |
| custom <sub>2</sub> | visualizza il testo nel colore del riquadro della tipologia prescelta |

Da notare che non è necessario che ogni colonna sia suddivisa per dimensione (come abbiamo fatto nella prima parte della tabella), ma è certamente più leggibile nel file sorgente markdown. La confusione può essere maggiore quando si mettono in fila gli elementi, semplicemente interrompendo le colonne con il carattere pipe "|" ovunque si trovi l'interruzione naturale, come si può vedere nell'ultimo elemento della tabella.

Blocco Citazioni¶

Le virgolette sono in realtà pensate per citare il testo di altre fonti da includere nella documentazione, ma non è obbligatorio usarle in questo modo. Alcuni collaboratori usano le virgolette invece delle tabelle, ad esempio per elencare alcune opzioni. Esempi di virgolette in markdown sono:

> **un elemento** - Una descrizione di quell'elemento

> **un'altra voce** - Un'altra descrizione di quell'elemento

La linea di "spaziatura" aggiuntiva è necessaria per evitare che le linee si sovrappongano.

L'aspetto finale è questo quando la pagina viene visualizzata:

un elemento - Una descrizione dell'elemento un altro elemento - Altra descrizione di un elemento

Blocchi di codice in linea e a livello di blocco¶

Our approach to the use of code blocks is pretty simple. Se il vostro codice è abbastanza breve da poterlo (e volerlo) usare in una riga come quella che avete appena visto, usate dei singoli backtick `:

Una frase con un "comando a scelta".

Qualsiasi comando che non sia usato all'interno di un paragrafo di testo (specialmente i pezzi di codice lunghi con più righe) dovrebbe essere un blocco di codice completo, definito con tripli backtick `:

```bash
sudo dnf install the-kitchen-sink
```

La parte bash di questa formattazione è un identificatore di codice non essenziale, ma può essere utile per l'evidenziazione della sintassi. Se si mostra Python, PHP, Ruby, HTML, CSS o qualsiasi altro tipo di codice, "bash" cambierà in base al linguaggio usato. Per inciso, se è necessario mostrare un blocco di codice all'interno di un blocco di codice, basta aggiungere un altro backtick ` al blocco genitore:

````markdown
```bash
sudo dnf install the-kitchen-sink
```
````

E sì, il blocco di codice che avete appena visto ha usato cinque backtick all'inizio e alla fine per renderlo correttamente.

Tastiera¶

Un altro modo per aggiungere più chiarezza possibile ai documenti è quello di rappresentare la digitazione dei tasti su una tastiera nel modo corretto. Questo viene fatto con <kbd>key</kbd>. Ad esempio, per rappresentare la necessità di premere il tasto escape nel documento, si userebbe <kbd>ESC</kbd. Quando è necessario indicare la pressione di più tasti, aggiungere un + tra di essi, come in questo caso:<kbd>CTRL</kbd> + <kbd>F4</kbd>. Se si richiede la pressione simultanea dei tasti, aggiungere "simultaneamente" o "allo stesso tempo" o una frase simile alle istruzioni. Ecco un esempio di istruzione da tastiera nell'editor:

Un'installazione di tipo workstation (con interfaccia grafica) avvia questa interfaccia sul terminale 1. Essendo Linux multiutente, è possibile connettere più utenti più volte, su diversi **terminali fisici** (TTY) o **terminali virtuali** (PTS). I terminali virtuali sono disponibili in un ambiente grafico. Un utente passa da un terminale fisico ad un altro usando <kbd>Alt</kbd> + <kbd>Fx</kbd> dalla riga di comando o utilizzando <kbd>CTRL</kbd> + <kbd>Alt</kbd> + <kbd>Fx</kbd> in modalità grafica.

Ecco come viene visualizzato:

Un'installazione di tipo workstation (con interfaccia grafica) avvia questa interfaccia sul terminale 1. Essendo Linux multiutente, è possibile connettere più utenti più volte, su diversi terminali fisici (TTY) o terminali virtuali (PTS). I terminali virtuali sono disponibili in un ambiente grafico. Un utente passa da un terminale fisico ad un altro usando Alt + Fx dalla riga di comando o utilizzando CTRL + Alt + Fx in modalità grafica.

Simboli di Apice, Pedice e Speciali¶

Le notazioni in apice e in pedice non sono un normale markdown, ma sono supportate nella documentazione di Rocky Linux attraverso i tag HTML usati per lo stesso scopo. L'apice pone il testo inserito tra i tag leggermente al di sopra del testo normale, mentre il pedice lo pone leggermente al di sotto. L'apice è di gran lunga il più usato nella scrittura. Alcuni caratteri speciali appaiono già in apice senza l'aggiunta dei tag, ma è possibile combinare i tag per cambiare l'orientamento di tali caratteri, come si vede con il simbolo del copyright qui sotto. Si può usare l'apice per:

rappresentano numeri ordinali, come 1^st, 2^nd, 3^rd
simboli di copyright e marchi, come ^©, ^TM, o ™, ®
come notazione per riferimenti, come questo¹, questo² e questo³

Alcuni caratteri speciali, come ©, non sono normalmente apicali, mentre altri, come ™, lo sono.

Ecco come appare tutto questo nel codice markdown:

* rappresentano numeri ordinali, come 1<sup>st</sup>, 2<sup>nd</sup>, 3<sup>rd</sup>
* simboli di copyright e marchi, come <sup>&copy;</sup>, <sup>TM</sup> o &trade;, &reg;
* come notazione per riferimenti, come questo<sup>1</sup>, questo<sup>2</sup> e questo<sup>3</sup>

Alcuni caratteri speciali, come &copy;, non sono normalmente apicali, mentre altri come &trade;, lo sono.

Come si può vedere, per forzare l'apice possiamo usare i tag HTML supportati <sup></sup>.

Inserire il pedice con il tag <sub></sub>, come già detto, non viene _{utilizzato molto} nella scrittura.

Apice per i riferimenti¶

Alcuni di voi potrebbero sentire la necessità di fare riferimento a fonti esterne quando scrivono la documentazione. Se avete una sola fonte, potete includerla nella conclusione come un unico link, ma se ne avete più di una¹, potete usare l'apice per annotarle nel testo² e poi elencarle alla fine del documento. Si noti che il posizionamento dei riferimenti deve avvenire dopo la sezione "Conclusioni".

Dopo la conclusione, è possibile inserire le notazioni in un elenco numerato che corrisponde all'apice, oppure come link. Entrambi gli esempi sono mostrati qui:

"Come si usano i multipli nel testo" di Wordy W. McWords https://site1.com
"Using Superscript In Text" di Sam B. Supersecret https://site2.com

o

1 "Come si usano i multipli nel testo" by Wordy W. McWords
2 "Utilizzo dell'apice nel testo" by Sam B. Supersecret

Ecco come si presenta il tutto nel vostro editor:

1. "Come si usano i multipli nel testo" by Wordy W. McWords [https://site1.com](https://site1.com)
2. "Utilizzo dell'apice nel testo" by Sam B. Supersecret [https://site2.com](https://site2.com)

o

[1](https://site1.com) "Come si usano i multipli nel testo" by Wordy W. McWords  
[2](https://site2.com) "Utilizzo dell'apice nel testo" by Sam B. Supersecret

Raggruppare diversi tipi di formattazione¶

La Documentazione Rocky offre alcune eleganti opzioni di formattazione quando si combinano più elementi all'interno di un altro elemento. Per esempio, un ammonimento con un elenco numerato:

Nota

Le cose possono diventare un po' strane quando si raggruppano gli oggetti. Come quando:

Si aggiunge un elenco numerato di opzioni all'interno di un ammonimento
Oppure si aggiunge un elenco numerato con più blocchi di codice:
```
dnf install some-great-package
```
Che è anche all'interno di un elenco numerato di più paragrafi.

Oppure si può avere un elenco numerato, con un'ulteriore ammonimento:

Questo elemento è molto importante

Qui si aggiunge un comando da tastiera all'elemento dell'elenco:

Premere ESC senza un motivo particolare.
Ma questo articolo è qualcosa di molto importante e ha più paragrafi ad esso dedicati

E ha un ammonimento nel mezzo:

Attenzione

Le cose possono diventare un po' strane con più elementi all'interno di diversi tipi di formattazione!

Se si rispettano i magici quattro (4) spazi per rientrare e separare questi elementi, essi verranno visualizzati in modo logico ed esattamente come si desidera. A volte è davvero importante.

È anche possibile incorporare una tabella o una citazione a blocchi (letteralmente qualsiasi tipo di elemento di formattazione) all'interno di un'altra. Qui ci sono un elenco numerato, un ammonimento, una tabella e alcuni elementi di blocco di citazione, tutti raggruppati insieme:

Cercare di tenere il passo con tutto ciò che accade nel documento può essere un vero compito quando si lavora con più elementi.

Se vi sentite sopraffatti, prendete in considerazione:

importante: credo che mi faccia male la testa!

Quando si combinano più elementi di formattazione, il cervello può impazzire. Prendete in considerazione l'idea di assumere un po' di caffeina in più prima di cominciare!

tipo	dose giornaliera di caffeina
tea	alla fine ci arriverete
coffee	per palati esigenti
red bull	Ha un sapore terribile, ma vi farà andare avanti!
mountain dew	eccessivamente ipnotico

zucchero se la caffeina non è di vostro gradimento

soffrire se tutto il resto fallisce, concentrarsi di più

Esistono molti esempi, ma quello riportato sopra illustra come sia possibile annidare tutto all'interno. Ricordate i quattro (4) spazi magici.

Ecco come appare questo esempio nell'editor:

Se si rispettano i magici quattro (4) spazi per separare questi elementi, essi verranno visualizzati in modo logico ed esattamente come si desidera. A volte è davvero importante.

È anche possibile incorporare una tabella o una citazione a blocchi (letteralmente qualsiasi tipo di elemento di formattazione) all'interno di un'altra. Qui ci sono un elenco numerato, un'ammonimento, una tabella e alcuni elementi di citazione a blocchi, tutti raggruppati insieme:

1. Cercare di tenere il passo con tutto ciò che accade nel documento può essere un vero compito quando si lavora con più elementi.

2. Se vi sentite sopraffatti, prendete in considerazione!!! warning "importante: credo che mi faccia male la testa!"

        Quando si combinano più elementi di formattazione, il cervello può impazzire. Prendete in considerazione l'idea di assumere un po' di caffeina in più prima di cominciare!

        | tipo            |   dose giornaliera di caffeina       |
        |-----------------|----------------------------------|
        | tea             | alla fine ci arriverete |
        | coffee          | per palati esigenti        |
        | red bull        | Ha un sapore orribile, ma vi farà andare avanti! |
        | mountain dew    | eccessivamente ipnotico                       |

        > **zucchero** se la caffeina non è di vostro gradimento

        > **soffrire** se tutto il resto fallisce, concentrarsi di più

3. Esistono molti esempi, ma quello riportato sopra illustra come sia possibile annidare tutto all'interno. Ricordate i quattro (4) spazi magici.

Un ultimo punto: i commenti¶

Di tanto in tanto, si potrebbe voler aggiungere un commento al markdown che non verrà visualizzato quando sarà elaborato. Le ragioni sono molteplici. Ad esempio, se si vuole aggiungere un segnaposto per qualcosa che verrà aggiunto in seguito, si può usare un commento per contrassegnare il punto.

Il modo migliore per aggiungere un commento al markdown è usare le parentesi quadre "[]" intorno a due barre in avanti "//" seguite da due punti e dal contenuto. Il risultato sarebbe il seguente:

[//]: Questo è un commento da sostituire in seguito

Un commento dovrebbe avere una riga vuota prima e dopo il commento.

Ulteriori Letture¶

Il documento Rocky Linux come contribuire
Altro sugli ammonimenti
Riferimento rapido Markdown
Ulteriori riferimenti rapidi per Markdown

Conclusione¶

La formattazione del documento con titoli, ammonimenti, tabelle, elenchi numerati e virgolette può aggiungere chiarezza al documento. Quando si utilizzano gli ammonimenti, fare attenzione a scegliere il tipo corretto. In questo modo è più facile capire visivamente l'importanza di una particolare ammonimento.

Non è necessario utilizzare le opzioni di formattazione avanzate. L'uso eccessivo di elementi speciali può aggiungere disordine dove non ce n'è bisogno. Imparare a usare questi elementi di formattazione in modo prudente e corretto può essere molto utile per far capire il proprio punto di vista in un documento.

Infine, per facilitare la formattazione, si consiglia di modificare il valore TAB dell'editor markdown in quattro (4) spazi.

Ultimo aggiornamento: September 18, 2023

Author: Steven Spencer

Contributors: tianci li, Ezequiel Bruni, Krista Burdine, Ganna Zhyrnova