| Firebird Documentation Index → Scrivere documenti per Firebird → Pubblicare sul sito web |
|
|
|
Prima di pubblicare i documenti, è necessario ricostruire i file in formato HTML e PDF. Questo è documentato nella guida Come fare i manuali di Firebird. Per proseguire si assume che si siano fatti con successo i file in formato HTML e PDF.
Il sistema di ricostruzione da un nome automatico a ciascun file
prendendolo dall'ID dell'elemanto principale che il documento DocBook
contiene. I nomi dei file in formato HTML multipagina non vanno
cambiati, questi file servono per essere utilizzati in rete, e cambiare
un solo nome file potrebbe distruggere tutti i link contenuti nelle
altre pagine. Ma i file PDF sono spesso scaricati dal lettore, ed avere
nomi come qsg2.pdf o
ubusetup.pdf in una directory di download oppure
sul proprio desktop non aiuta per niente a
riconoscerli come manuali di Firebird. Pertanto ecco qui alcune linee
guida per dare un nome ai file PDF:
Assicurarsi che il nome contenga la parola
Firebird, possibilmente all'inizio;
Farlo assomigliare al titolo del documento, magari accorciandolo;
Usare i trattini («-») per separare fra loro le parole;
Se diventa troppo lungo, eliminare parole come «manuale», «guida», «Come-fare-per» ecc., a meno che possa provocare confusione;
Usare la propria lingua (quella del documento), ma solo caratteri ASCII (niente accenti, ecc.)
Se (e solo se) applicando le precedenti regole risultasse un nome file già esistente in un'altra lingua, aggiungergli la lingua (o una sua abbreviazione).
Per esemplificare queste linee guida, ecco alcuni nomi file esistenti:
Firebird-2.0-QuickStart.pdf
Firebird-Security.pdf
MSSQL-to-Firebird.pdf
Firebird-Generator-Guide.pdf
Firebird-nbackup.pdf
Firebird-2.0-Schnellanleitung.pdf
Firebird-1.5-Arranque.pdf
Firebird-et-Null.pdf
Firebird-nbackup-fr.pdf
Firebird-su-Ubuntu.pdf
Firebird-nbackup-nl.pdf
Guia-Escrita-Firebird.pdf
Firebird-1.5-BystryjStart.pdf
Firebird-Perehod-s-MSSQL.pdf
Se e quando si pubblicheranno files in formato HTML singola
pagina, per intenderci quelli fatti con build
monohtml, daremo loro lo stesso nome del corrispondente file
PDF, ma con l'estensione .html,
naturalmente.
Avendo i diritti di accesso in scrittura sul server web di
Firebird, ci si deve collegare con un client SFTP a web.firebirdsql.org e depositare i file
propriamente rinominati in:
/srv/www/htdocs/pdfmanual (documenti in
inglese)
/srv/www/htdocs/pdfmanual/it (documenti
in italiano)
/srv/www/htdocs/pdfmanual/fr (documenti
in francese)
/srv/www/htdocs/pdfmanual/ja (documenti
in giapponese)
ecc.
Le note di rilascio invece vanno in:
/srv/www/htdocs/rlsnotes
/srv/www/htdocs/rlsnotes/it
ecc.
Senza i diritti di accesso al server, si deve chiedere a qualcun altro se può farlo per voi, oppure, se si è membri del progetto, chiedere un nome utente ed una password sul server.
Bisogna assicurarsi di depositare tutti i file necessari:
i file HTML che insieme formano il manuale o i manuali.
il file del foglio di stile
firebirddocs.css (se è stato modificato
dall'ultimo deposito).
tutte le immagini che sono state modificate o aggiunte nel
sottodirettorio images.
Per far funzionare tutti i link, potrebbe essere necessario
ricostruire e depositare tutto il libro (book) padre del documento creato o aggiornato,
o addirittura l'intero insieme (set).
Ad ogni modo, va depositato il tutto in:
/srv/www/htdocs/manual
(Documenti in Inglese)
/srv/www/htdocs/manual/it (Documenti in
Italiano)
/srv/www/htdocs/manual/fr (Documenti in
francese)
e così via...
Se le pagine in questione appartengono ad un altro insieme base
che non sia il default firebirddocs (cioè ad
esempio a papers oppure a
rlsnotes) non vanno messe in quelle directory. Non
sonostate ancora definite delle regole precise, ma gli HTML
multipagina generati da insiemi differenti non dovrebbero essere
mischiati. Se si rischia di nascere una situazione del genere, meglio
parlarne prima nella lista firebird-docs.
L'indice della documentazione di Firebird (Firebird Documentation Index) che è in http://www.firebirdsql.org/index.php?op=doc è uno script PHP che preleva la maggior parte del suo contenuto dalle informazioni contenute in file di dati nel server. Dopo aver aggiornato file esistenti che sono già nell'indice, è già tutto a posto, a meno che non si sia cambiato il nome del file. Nel caso invece in cui si sia creato un nuovo documento o una nuova traduzione, questa va aggiunta all'indice. Ecco come si fa:
Cercare nell'indice della documentazione quale categoria meglio si confà al documento. Le categorie sono al momento indicate con la testata a caratteri arancione.
Connettersi al server, cambiare la directory corrente a
/srv/www/htdocs/doc e
cercare i file che cominciano con Cat_.
Aprire quello della categoria desiderata.
Leggere le istruzioni in cima al file, e se lo avete fatto già altre 100 volte prima, controllate che non sia cambiato niente.
Creare una nuova sezione cominciando con il titolo del documento in inglese, seguito da una linea per ogni versione disponibile che deve avere un formato speciale. Per un nuovo documento, la sezione assomiglia a questa:
Firebird Uninstallation Howto en:/manual/fb-uninstall.html en:/pdfmanual/Firebird-Uninstall.pdf
Ogni linea di versione inizia con il codice del
linguaggio, seguito dal carattere di due punti
(«:»), infine c'è l'URL di un
file. Per i documenti che sono sul nostro server, l'URL è
semplicemente il percorso «assoluto» dalla radice
del server. Le singole sezioni sono separate da linee vuote.
In ogni categoria della pagina web dell'indice della
documentazione Firebird, i documenti sono ordinati come le
singole sezioni nel file. L'ordine delle linee di versione
all'interno di una sezione è invece irrilevante.
Salvare il file. Se l'avete modificato nel vostro computer, ridepositatelo sul server. Aggiornando la pagina dell'indice della documentazione di Firebird nel vostro navigatore internet, verificare se il documento è elencato esattamente dove si desidera e se i link funzionano bene: notare che va controllato se i link sono nelle giuste colonne (HTML nella colonna centrale, PDF ed ogni altra cosa nell'ultima a destra).
Lo script PHP fa un buon lavoro nel determinare il tipo di documento, ma ci sono casi in cui sbaglia. Se succede, aggiungere il tipo di file tra parentesi graffe subito dopo l'URL nella linea della versione:
en:http://www.ibphoenix.com/main.nfs?a=ibphoenix&page=ibp_60_sqlref{html}Quando tutto è a posto, si può confermare la categoria
aggiornata nel CVS. Se si è fatta l'estrazione completa del
modulo web di
Firebird da SourceForge, si troveranno i file delle categorie
(ed altro ancora) nella directory web/website/doc. Si deve usare il
proprio nome utente e password SourceForge per prelevare,
altrimenti non si riuscirà ad aggiornare le modifiche. Sempre
nel manuale Come
fare i manuali di Firebird è descritto come si fa a
lavorare con la CVS.
Consultare l'indice della documentazione per verificare a quale categoria appartiene il documento. Le categorie sono indicate con testate a caratteri arancione al momento.
Collegarsi al server, e cambiare la directory di lavoro
a /srv/www/htdocs/doc
cercando i file che iniziano con Cat_.
Aprire quello che corrisponde alla categoria
desiderata.
Trileggere le istruzioni all'inizio del file.
Cercare la sezione del documento e aggiungere la linea (o le linee) per la versione aggiunta, per esempio:
Firebird Uninstallation Howto
en:/manual/fb-uninstall.html
en:/pdfmanual/Firebird-Uninstall.pdf
fr:/manual/fr/fb-uninstall-fr.html
fr:/pdfmanual/fr/Deinstaller-Firebird.pdfL'ordine delle linee di versione è irrilevante all'interno di una sezione, ma il titolo dev'essere in cima.
I passi 5, 6, e 7 sono identici a quelli specificati nel caso di un nuovo documento.
|
| Firebird Documentation Index → Scrivere documenti per Firebird → Pubblicare sul sito web |