Come mostrare codice sorgente su una pagina wiki
Situazione
Il repository è montato e ora deve comparire su una pagina wiki — o l'intero albero per la consultazione, oppure un singolo file o un intervallo di righe accanto a una spiegazione.
Panoramica della soluzione
Esistono due marcature. Scambiare l'una con l'altra è l'errore più frequente nell'incorporamento.
| Marcatura | Che cosa mostra | Chi la disegna | Dove funziona |
|---|---|---|---|
{{wk:adogit>…}} | l'albero di cartelle e file dell'intero repository | il plugin wkdoadogit | solo su una pagina sotto la radice dei progetti, per esempio it:projects:dwplugins:repos |
{{source>ado:…}} | il contenuto di un singolo file | il plugin wksourceview tramite lo schema ado | su una pagina sotto la radice dei progetti oppure su una pagina dentro lo spazio dei nomi del mount |
Entrambe passano per gli stessi permessi: l'accesso lo decide lo spazio dei nomi del mount, mai la pagina su cui la marcatura si trova.
Realizzazione
L'albero del repository
{{wk:adogit>wvds:DokuWiki-Plugins:wkdoadogit}}
La forma è {{wk:adogit>connessione:progetto:repository[:ramo[:percorso]]}}. Un ramo omesso indica il ramo predefinito del repository, un percorso omesso la radice. Il suffisso facoltativo region=<nome> offre il browser a una regione laterale della shell:
{{wk:adogit>wvds:DokuWiki-Plugins:wkdoadogit:main:/Domain region=toc}}
Un singolo file
{{source>ado:wvds:DokuWiki-Plugins:wkdoadogit:main:/Domain/MountAclGate.php}}
La forma è {{source>ado:connessione:progetto:repository:ramo:percorso}}. Per questa marcatura tutti e cinque i campi sono obbligatori, quindi indicate sempre il ramo. Un campo vuoto significa rifiuto, non ramo predefinito.
Un intervallo di righe
{{source>ado:wvds:DokuWiki-Plugins:wkdoadogit:main:/Domain/MountAclGate.php#L141-L146}}
Le forme ammesse sono #L25, #L10-L40 e l'aperta #L10-. Il conteggio parte da 1 e l'intervallo viene ridotto alla lunghezza del file. L'intervallo riguarda solo la resa: da Azure DevOps viene sempre trasferito l'intero file.
Opzioni di resa
Le opzioni si scrivono dopo uno spazio. Valgono per wksourceview, non per lo schema ado.
{{source>ado:wvds:DokuWiki-Plugins:wkdoadogit:main:/README.md#L1-L20 mode=block numbers=1 lang=markdown}}
| Opzione | Valori | Predefinito |
|---|---|---|
mode | inline, block, preview o drawer | il valore dell'impostazione default_mode di wksourceview |
numbers | 0 o 1 | il valore dell'impostazione default_numbers |
lang | nome del linguaggio per l'evidenziazione della sintassi | riconosciuto dall'estensione del file |
Note
- Il primo campo è la chiave della connessione, non il suo numero. La connessione si cerca per chiave dentro il progetto DWDO a cui appartiene la pagina; una forma numerica non funziona.
- Ogni incorporamento è una chiamata di rete. Una pagina con una dozzina di incorporamenti paga una dozzina di chiamate, limitate dai tempi massimi e dal tetto di byte in
wkdoado. - Un incorporamento fissato a un ramo si sposta in silenzio. Il testo che spiega la riga 40 continua a essere reso quando il codice è passato alla riga 90. Per le spiegazioni fissate quindi un commit (40 caratteri esadecimali) anziché un ramo.
- Una pagina con un incorporamento non viene messa in cache. Entrambe le marcature disattivano la cache delle pagine, così che il contenuto protetto da permessi non raggiunga il lettore sbagliato.
- I file troppo grandi e quelli binari non vengono resi. Al posto del contenuto compare una scheda di stato; i limiti li fissano
max_bytesemax_linesdiwksourceview. - Un rifiuto non ne indica la causa. Un repository non montato, una connessione sconosciuta e un permesso mancante rispondono volutamente in modo simile.
Argomenti correlati
- Guida: la pagina con il browser – la prima pagina con il browser, con un esempio completo
- Come modificare un file ed eseguire il commit dal wiki – modificare un file ed eseguire il commit dal browser
- Riferimento tecnico: livello di visibilità – chi può vedere il contenuto incorporato
- Diagnostica – che cosa significa ciascuna scheda di stato