Manuali, Subversion, UDO

Questa pagina descrive come noi gestiamo le sorgenti del manuale con Subversion e UDO.

Niente è Più Vecchio del Vostro Manuale Stampato Ieri.

I Manuali devono sempre essere al passo/seguire lo sviluppo delle applicazioni. Quindi è consigliabile avere la sorgente del vostro manuale su un server condiviso, questo per dare a tutti gli autori e localizzatori del manuale accesso diretto ai dati. Noi crediamo che Subversion sia lo strumento perfetto per questo scopo.

Subversion Gestisce Dati Per Modifiche Correnti

Grazie a Subversion (di seguito chiamata SVN) noi diamo ai nostri autori e localizzatori del manuale diretto accesso alla nostra sorgente del manuale e ci assicuriamo che nessuno possa danneggiare le sorgenti, autori multipli possono lavorare allo stesso file allo stesso tempo e tutti avranno sempre un unico stato.

Quale autore di manuali, non dovrete comprendere completamente SVN, solo un pò:

1. Repository
   I dati del manuale sono immagazzinati in un 'repository' sul nostro SVN server. Il repository rappresenta sempre lo stato corrente/attuale dei dati per tutti gli autori.
2. Checkout
   Se scaricate/download dati dal SVN server nel vostro computer (checkout), voi create una Copia di Lavoro -''Working Copy' sul vostro hard drive, che potrete modificare come volete.
3. Commit
   Quando voi inviate di ritorno i vostri file/cambiamenti al SVN server (commit), verranno presi/acquisiti e da quel momento saranno a disposizione di tutti gli altri autori.

Società Chiusa!

Solo i nostri sviluppatori, autori di manuale e localizzatori ottengono l'accesso al nostro SVN server. Il server SVN serve e gestisce i vari repositories ma ogni repository ha i suoi permessi di accesso. Noi riteniamo: Troppa libertà può causare problemi. Se volete avere accesso ad un certo repository sul nostro SVN server, necessiterete di un SVN account e di una SVN password. Entrambe sono disponibili a richiesta.

Come Avere i Dati?

OS X

Se lavorate con Apple developer tool Xcode, non dovrete installare nessun altro strumento dal momento che Xcode supporta SVN automaticamente. Dovrete solo attivarlo. Consultate il manuale di Xcode su come farlo.

Altrimenti una interfaccia grafica utente (GUI) di Subversion è necessaria, per fare del Checkout e Commit qualcosa di più divertente di un command line.

• Subversion
• SVN GUI: SmartSVN
• opzionale SVN GUI: svnX

Windows

Subversion e interfaccia grafica (GUI) per SVN sono necessarie, per fare del Checkout e Commit qualcosa di più divertente di un command line. Raccomandiamo il GUI tool TortoiseSVN.

• Subversion
• SVN GUI: TortoiseSVN

Come si Presentano le Sorgenti del Manuale?

Noi scriviamo i manuali in formato UDO, un formato documento universale con un approccio facile. I repositories sono organizzati come l'esempio seguente (si riferisce a applicazioni OS X):

/cs.lproj/
/cs.lproj/<Help Book name>/
/da.lproj/
/da.lproj/<Help Book name>/
/de.lproj/
/de.lproj/<Help Book name>/
/en.lproj/
/en.lproj/<Help Book name>/
/fr.lproj/
/fr.lproj/<Help Book name>/
/it.lproj/
/it.lproj/<Help Book name>/
/nl.lproj/
/nl.lproj/<Help Book name>/
/UDoSource/
/UDoSource/_INCLUDE/
/UDoSource/<various folders>
/UDoSource/<ProjectName>_main_cs.u
/UDoSource/<ProjectName>_main_da.u
/UDoSource/<ProjectName>_main_de.u
/UDoSource/<ProjectName>_main_en.u
/UDoSource/<ProjectName>_main_fr.u
/UDoSource/<ProjectName>_main_it.u
/UDoSource/<ProjectName>_main_nl.u

La struttura della cartella *.lproj come mostrata sopra, è una copia delle cartelle relative ai progetti lingue per l'applicazione. Contengono le cartelle dell'Apple Help Book che possono essere copiate direttamente nella sorgente dell'applicazione.

La cartella UDoSource contiene tutti i dati che devono essere localizzati. Abbiamo definito la nostra nomenclatura per l'uso delle estensioni dei files, come segue:

• .cs = Ceco files testo
• .da = Danese files testo
• .de = Tedesco files testo
• .en = Inglese files testo
• .fr = Francese files testo
• .it = Italiano files testo
• .nl = Olandese files testo

• .u = UDO command files
• .ui = UDO include files
• .uli = UDO library include files

Naturalmente i repositories non necessariamente contengono esattamente i sopracitati files, cartelle e lingue.

Formato UDO, di che si tratta?

UDO usa una sintassi molto semplice per strutturare testo, aggiungere attributi testo, incluso immagini, links ecc. La caratteristica importante in UDO è il suo approcio facile, inoltre offre molti comandi. Noi cerchiamo di evitare il 'sovraccarico caratteristiche' nel nostro manuale e usiamo pochi elementi di sintassi UDO. Questi sono alcuni esempi:

Testo Strutturato

!begin_node inizia un nuovo capitolo.
!end_node finisce un capitolo.
# all'inizio linea avvisa UDO di ignoarre l'intera linea (linea commenti).
!hline mostra una linea orrizontale.
(!nl) forza una interruzione di linea. (Fondamentalmente UDO chiude una paragrafo testo quando riconosce due fine linea.)

Attributi Testo

(!B) e (!b) cambia grassetto font on/off.
(!I) e (!i) cambia corsivo font on/off.
(!U) e (!u) cambia sottolineato on/off.

(Ci sono molti altri comandi attributo; non li utilizziamo in gran parte.)

Liste

!begin_itemize e !end_itemize intervallo di una lista non ordinata.
!begin_enumerate e !end_enumerate intervallo di una lista numerata.
!begin_description e !end_description intervallo di una lista descrittiva.
!item inzia un item della lista.

(Ci sono molti altri comandi layout; non li utilizziamo in gran parte.)