Questa parte tratta in dettaglio le convenzioni di stile per l’uso di testo «restructured» per il Manuale di Krita.
Si raccomanda di consultare le specifiche ufficiali di reStructuredText e, dato che risiede in Sourceforge, di salvarne una copia nel tuo disco rigido (Sourceforge ha, al momento della stesura di questa guida, alcuni problemi col server):
Pagina Sphinx” sul testo «restructured» – Utile per le direttive specifiche di Sphinx e i ruoli che utilizza per generare, per esempio, indici.
Esistono differenze nei vari metodi di fare le cose tra la documentazione ufficiale di reStructuredText e quella di Sphinx. Questo documento dettaglia le convenzioni suggerite da seguire.
Ogni pagina deve iniziare con i tre elementi seguenti:
Una meta descrizione
Questa è una descrizione generale della pagina. Sarà convertita in un meta tag html che sarà utilizzato dai motori di ricerca:
..meta:::description:Descrizione.
Un elenco degli autori e una licenza.
Serve solo per mantenere traccia di chi ha modificato la pagina e attribuire i crediti. Deve essere racchiusa in un commento in modo che non sia facilmente leggibile dalle macchine. La licenza dell’intero manuale è GDL 1.3 e deve essere anch’essa racchiusa qui:
Sono termini separati da virgola grazie ai quali la pagina sarà indicizzata in Indice. L’indice generato è molto utile sia per i PDF, sia per le persone che non sono sicure del nome esatto del termine che stanno ricercando. Sono definiti come segue:
.. index:: Parola_chiave, Parola chiave con spazi, ! Parola chiave di una definizione principale
Un’etichetta.
Questo serve in modo che possiamo collegarci facilmente alla pagina utilizzando :ref:`label_name`. Cerca di scegliere un buon nome di variabile:
.._label_name:
Dopo l’etichetta devi aggiungere un titolo, dato che :ref:`label_name` si riferirà al titolo per compilare il testo del collegamento.
Queste convenzioni sono stabilite più o meno dalla procedura di conversione da mediawiki a reStructuredText di Pandoc’s. Se necessiti di più di quattro titoli, chiediti prima se la pagina non sia troppo complicata e debba essere divisa.
A volte hai bisogno di collegarti a una sottosezione di una pagina, in tal caso aggiungi un’etichetta sopra il titolo.
I titoli non devono terminare con punteggiatura, dato che saranno utilizzati come nome del collegamento quando ci si collega a un’etichetta.
Il collegamento si crea con :ref:`label_name`. Quando ti serve un nome alternativo, usa :ref:`testorealedamostrare<label_name>`.
Il collegamento a pagine esterne viene creato con `url`_ e `nomedelcollegamento<url>`_, che diverranno il nome del collegamento.
Pandoc preferisce cambiare questi comandi in `nomedelcollegamento`__ e poi aggiungere `` .. __ :url `` alla fine del documento. Questo è il cosiddetto “collegamento ipertestuale anonimo”, il che significa che a seconda dell’ordine in cui appaiono i collegamenti nel testo, l’ordine dei collegamenti alla fine del testo è associato a un altro. Se ciò sembra confuso e difficoltoso, è perché in realtà lo è. Questo è anche il motivo per cui preferiamo evitare collegamenti di questo genere.
Questa è la citazione. È simile a una nota a piè pagina, ad eccezione del fatto che la didascalia è testuale.
Si può anche fare riferimento alla citazione con `citazione<CIT2002>`_.
Nel manuale in realtà non utilizziamo le note a piè pagina, dato che è piuttosto accademico per i nostri lettori. Tuttavia, raduniamo alla fine di una pagina documenti e collegamenti che forniscono maggiori informazioni su un argomento. Sphinx possiede la direttiva ..seealso:: per i collegamenti esterni, mentre reStructuredText suggerisce l’uso di ..rubic::Footnotes per la raccolta specifica di note a piè pagina, dato che funziona bene con LaTeX.
Una didascalia – nota come la prima lettera della didascalia nella direttiva sia allineata con l’opzione :figwidth:.¶
Le immagini devono essere memorizzate nella cartella /images. Se utilizzi /images al posto di images, Sphinx saprà che il percorso dei file non è relativo.
Puoi rendere il testo in corsivo e in grassetto rispettivamente con singolo e doppio asterisco:
*corsivo***grassetto**
Non puoi utilizzare insieme *corsivo e grassetto*, fai dunque una scelta.
Puoi scrivere testo in pedice e apice utilizzando rispettivamente :sub:`testo` e :sup:`testo`.
Tuttavia, usali con molta moderazione. È meglio utilizzare in ogni caso i markup semantici esistenti in Sphinx, perché rende più facile ai traduttori prendere delle decisioni sulla natura del testo da tradurre:
Puoi creare una sorta di forma abbreviata di una parte di testo o un’immagine in questo modo:
..|shorthand|replace::qualcosaol'altro.
ciò significa che se usi |shorthand| nel testo, esso sarà sostituito con “qualcosa o l’altro”. Questo è utile per le immagini e il testo che deve essere formattato in maniera complicata, come nel caso di «LaTeX».
La documentazione di Krita possiede |mouseleft|, |mousemiddle|, |mousescroll| e |mouseright|, che diventano rispettivamente , , e . Essi sono definiti nel file conf.py di Sphinx e vengono allegati a ogni file rst.
Per i collegamenti, se riutilizzi lo stesso collegamento più e più volte, puoi scrivere alla fine del file qualcosa di simile a questo:
In seguito, quando digiti un collegamento, basta che usi `bugzilla`_ per collegarlo a bugzilla indicato da «bugzilla» come testo del collegamento. A sua volta, `KritaManual`_ diventerà un collegamento a docs.krita.org col testo «Krita Manual».
Tra i preferiti! Gli elenchi di definizioni si rivelano molto utili quando hai a che fare con l’elencazione di tutte le opzioni in un’area e stai cercando un modo per aggiungere una breve spiegazione al loro lato.
Le tabelle a griglia complete sono più adatte quando hai la necessità di utilizzare tutte le caratteristiche delle righe e delle colonne, ma sono difficili da creare. Per questo motivo, è meglio creare le tabelle piccole con la sintassi semplice, mentre è meglio creare quelle davvero lunghe utilizzando una direttiva list dato che è molto più semplice da scrivere e da gestire.
Le raccomandazioni sono una sorta di sezione separata cui il lettore deve prestare attenzione.
Le raccomandazioni che si possono utilizzare sono le seguenti (in ordine di importanza):
Suggerimento
I suggerimenti (Hints) si rivelano utili per fornire ulteriori informazioni su un argomento funzionale al testo principale. Per esempio, «openSuse chiama questi pacchetti in modo diverso rispetto a Debian».
Suggerimento
Informazioni aggiuntive su come fare qualcosa, per esempio «Puoi creare un modello per la creazione del tuo documento preferito», oppure «Usa m per rispecchiare le tele e scoprire più facilmente errori nel disegno».
Importante
Qualcosa che è importante da notare ma non necessariamente negativa.
Avvertimento
In generale, quando qualcosa è negativa.
Attenzione
Qualcosa che attira l’attenzione generale. Usalo quando il soggetto è più importante dell’avviso ma non così importante da provocare una perdita di dati.
Attenzione
Da utilizzare per cose che possono causare perdita di dati, come dimenticarsi di salvare o che Python attualmente non possiede funzioni di annullamento delle azioni.
Pericolo
Deve essere utilizzato per le cose che sono dannose per il computer in generale, che include azioni che possono causare blocchi tipo esaurimento di memoria.
Errore
Questo probabilmente non è pertinente per un manuale. Sphinx può creare manualmente questi avvertimenti in determinate situazioni, ma la nostra configurazione non lo fa in modo predefinito.
Avvertimento generico che può contenere del testo.
Detto questo, i righelli orizzontali possono essere creati con ----.
La direttiva rubric (titolo)
La direttiva rubric è una direttiva per titoli che a un primo sguardo assomiglia ad «topic» (argomento), ma laddove l’argomento si occupa di vari paragrafi, rubric in sé si occupa solo del titolo, in questo modo:
..rubric::Ladirettivarubric
Quando utilizzarle, dunque?
Utilizzale solo quando ritieni che l’oggetto sia troppo secondario per avere un proprio titolo.
Argomento
Quando il testo è separato dal flusso, dunque finisce all’interno di un oggetto diverso da quello in cui il testo stesso andrebbe naturalmente.
Rubric
Quando il testo non è separato dal flusso ma non necessita un suo titolo.
Raccomandazioni
Solo quando sono significative. Ciò è vero specialmente per le raccomandazioni di avviso e pericolo, poiché la loro presenza eccessiva rischia di vanificarne l’effetto voluto.
// commento C++intmyFunction(inti){i+=1;// Controlla se più di 12if(i>12){i=0;}returni;}
/* commento CSS */body{margin:0auto;/* 800 è ancora appropriato? */max-width:800px;font-size:16px;color:#333;background-color:#eee;padding:1em;font-family:serif;line-height:1.4;}
<p>questo <spanstyle="font-style:italic">è</span><!-- a HTML comment --> un paragrafo.</p>
Questo non viene normalmente usato nel manuale e deve essere utilizzato solamente quanto è assolutamente obbligatorio rappresentare il contenuto con una formattazione precisa, ma mai per pure ragioni estetiche.
Puoi utilizzare la seguente stringa per includere del testo che ha senso solo per traduzioni non inglesi del manuale, per esempio per fornire come riferimento ai lettori di lingua non inglese i nomi inglesi di un elemento:
Se stai traducendo il manuale in una lingua che di solito non usa spazi intorno alle parole (per es. Cinese e Giapponese), puoi utilizzare un carattere di escape per separare marcatori e parole. Ciò risulta particolarmente utile per i collegamenti alle pagine, tipo questo:
床前\ `明月 <https://krita.org/>`_\ 光
Nota che quando stai traducendo un file PO, devi utilizzare il carattere di escape «barra rovesciata» con un’altra barra rovesciata:
, 
, 
e 
. Essi sono definiti nel file conf.py di Sphinx e vengono allegati a ogni file rst.