Guida a Gentoo Metadoc XML

1.  Introduzione

Perchè c'è Bisogno di MetadocXML?

MetadocXML non è una necessità, è semplicemente una risorsa aggiuntiva per il Gentoo Documentation Project per tener traccia dei documenti, anche di quelli che non sono collocati nell'area [gentoo]/xml/htdocs/doc.

Grazie a MetadocXML ora è possibile:

• tenere traccia dei documenti appartenenti all'area 'project' del nostro spazio web (/proj) oltre a quelli che trovi nell'area della documentazione normale (/doc)
• dividere la documentazione in diverse categorie (o sottocategorie) con il vantaggio ulteriore che ora possiamo generare automaticamente un indice di riepilogo dei documenti (e molto altro)
• tenere traccia della documentazione dei membri non ufficiali del team (come i traduttori)
• utilizzare sezioni dei documenti più corposi (i manuali -- handboooks) come guide indipendenti destinate a determinati argomenti
• assegnare bug a particolari documenti con la possibilità di mascherare un documento nel caso di un bug critico
• verificare con facilità se un documento tradotto è, o meno, aggiornato al suo omologo in Inglese

Tieni presente che l'ultimo punto è ancora in fase embrionale e probabilmente non subirà ulteriori sviluppi. Esistono infatti strumenti più potenti e con maggiori funzionalità (come lo script di Xavier: trads-doc).

I team di traduttori che non fanno uso di MetadocXML non si devono preoccupare - non avranno nessun problema - non ci sono cambiamenti a GuideXML che richiedano MetadocXML.

Come Funziona MetadocXML?

Tutto ruota attorno a un file principale dove verranno organizzate le meta-informazioni sulla documentazione esistente. Chiameremo questo file metadoc.xml. Questo file sarà probabilmente collocato nelle rispettive aree principali di localizzazione linguistica (/doc/${LANGUAGE}) anche se non è ancora stato stabilito.

Questo file conterrà le seguenti meta-informazioni:

• I membri del team
• Le categorie di appartenenza dei documenti
• I file contemplati
• I documenti contemplati
• I bug che fanno parte di un documento

Accanto a metadoc.xml è possibile avere un file indice generato automaticamente (chiamato index.xml), un elenco completo di tutta la documentazione (chiamato list.xml) e un elenco completo di tutti i membri del team, di tutti i file e di tutti i bug (chiamato overview.xml).

2.  metadoc.xml

La struttura

metadoc.xml inizia con la consueta stringa di inizializzazione XML e con l'intestazione per il CVS di Gentoo:

<?xml version='1.0' encoding="UTF-8"?>
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/metadoc.xml,v 1.25 2004/12/23 09:51:30 swift Exp $ -->
<!DOCTYPE metadoc SYSTEM "/dtd/metadoc.dtd">

Ora vengono inserite le dichiarazioni proprie di MetadocXML.

<metadoc lang="en">

I traduttori, mediante l'attributo /doc/en/metadoc.xml, dovranno fare riferimento a /doc/en/metadoc.xml. Questo permette a metadoc di individuare file non tradotti e di verificare se le versioni dei documenti tradotti e degli originali coincidono.

<metadoc lang="codice della lingua"
parent="/doc/en/metadoc.xml">

Dopo metadoc andranno inseriti i seguenti elementi (esattamente in quest'ordine):

• version per tenere traccia delle modifiche
• members che dichiara i membri di un determinato team di traduttori
• categories che dichiara le categorie di appartenenza
• files che contiene tutti i file contemplati da Metadoc
• docs che contiene tutti i documenti contemplati da Metadoc

L'elemento 'version'

Il numero di versione dovrebbe essere incrementato quando viene aggiunto o rimosso un documento o un file, quando viene cambiato un 'path' o per qualsiasi modifica che vada a influire sulle versioni tradotte del documento.

L'elemento 'members'

All'interno dell'elemento members è possibile dichiarare due tipi di membri: lead e member. lead deve essere noto alla Gentoo Developers Relations dato che consiste soltanto nel nickname del leader del team e vi fa riferimento nella Gentoo Memberlist. member può essere uno Sviluppatore Gentoo (nel qual caso consiste nel suo nickname) oppure un collaboratore.

Nel caso di un collaboratore, l'elemento member avrà due attributi, mail e fullname; rispettivamente, l'indirizzo di posta elettronica e il nome completo del collaboratore.

<members>
  <lead>swift</lead>
  <lead>neysx</lead>
  <member>dertobi123</member>
  <member mail="gentoo_contributor@gmail.com" fullname="John
Doe">jdoe</member>
</members>

L'elemento 'categories'

All'interno dell'elemento categories è possibile dichiarare soltanto elementi cat. Ogni elemento cat contempla una Categoria e utilizza un parametro obbligatorio, id, per riferirsi ad essa. È anche possibile definire il parametro parent nel caso una categoria sia elemento 'figlio' di un'altra categoria.

In questo caso, l'attributo parent fa riferimento alla categoria 'padre' mediante l'attributo id.

<categories>
  <cat id="faq">Frequently Asked Questions</cat>
  <cat id="install">Installation Related Resources</cat>
  <cat id="install_guides">Installation Guides</cat>
</categories>

L'elemento 'files'

L'elemento files contiene soltanto elementi file.

Ogni elemento file fa riferimento a un determinato file XML. Ha un parametro obbligatorio, id, che può essere visto come una chiave primaria di ricerca del file. Metadoc confronterà, nel proprio file 'padre' (definito nell'elemento radice), il nome del file con lo stesso attributo id per verificare se si tratta di una traduzione o di un file non tradotto. Nel secondo caso il nome sarà identico.

Lo stesso file metadoc.xml potrà trovarsi in elenco e apparire così nella pagina di riepilogo.

<files>
  <file id="metadoc">/doc/en/metadoc.xml</file>
  <file id="ati-faq">/doc/en/ati-faq.xml</file>
</files>

L'elemento 'docs'

L'elemento docs contiene soltanto elementi doc.

Ogni elemento doc ha un attributo obbligatorio, id che ha il ruolo di chiave primaria del documento.

All'interno di ogni elemento doc deve essere presente almeno un elemento 'figlio': l'elemento fileid che fa riferimento all'attributo id dell'elemento file corrispondente al file principale del documento.

Consideriamo il caso di un capitolo di un manuale: deve riferirsi alla pagina principale del manuale stesso (il file XML di livello più alto). L'elemento fileid contiene a sua volta due attributi, vpart e vchap, che fanno riferimento alla sezione e al capitolo a cui appartiene il documento.

All'interno dell'elemento doc possiamo inserire altri due elementi:

• Uno o più elementi memberof che si riferisce alla categoria (o alle categorie) alla quale appartiene il documento (ricorda che un documento può appartenere a più categorie).
• Un elemento bugs che contiene a sua volta uno o più elementi bug. Un elemento bug fa riferimento al numero identificativo di un bug presente nel documento. Nel caso si trattasse di un bug importante, è possibile assegnare all'elemento bug un attributo stopper="yes" che impedirà al documento di apparire nella pagina indice.

<docs>
  <doc id="handbook_x86">
    <memberof>install_guides</memberof>
    <fileid>handbook-x86</fileid>
    <bugs>
      <bug>70753</bug>
    </bugs>
  </doc>
  <doc id="portage-intro">
    <memberof>gentoo_portage</memberof>
    <fileid vpart="2" vchap="1">handbook-x86</fileid>
  </doc>
  <doc id="uml">
    <memberof>sysadmin_general</memberof>
    <fileid>uml</fileid>
  </doc>
</docs>

3.  File Correlati con MetadocXML

Indice Generato Automaticamente

Per generare un indice automaticamente, è necessario iniziare un documento come segue:

<?xml version='1.0' encoding='UTF-8'?>
<?xml-stylesheet href="/xsl/metadoc.xsl" type="text/xsl"?>
<?xml-stylesheet href="/xsl/guide.xsl"   type="text/xsl"?>

<!-- $Header$ -->

<!DOCTYPE dynamic SYSTEM "/dtd/metadoc.dtd">

<!-- Sostituire a "/doc/en/metadoc.xml" il percorso al file
metadoc desiderato -->
<dynamic metadoc="/doc/en/metadoc.xml">
<title>Gentoo Documentation Resources</title>
<intro>

(...)

</intro>

<catid>faq</catid>
<catid>install</catid>

</dynamic>

Tra i tag intro devi inserire le sezioni che desideri visualizzare a inizio pagina. Potresti scrivere anche una breve introduzione e fornire al lettore i contatti a cui fare riferimento in caso di errori di traduzione o per altri problemi.

Tra i tag intro puoi usare il formato GuideXML iniziando da section.

I tag catid fanno riferimento alle categorie principali usate nell'indice dinamico. Devi elencare tutte le categorie principali che trovi nel tuo documento metadoc. Non devi elencare nessuna categoria 'figlia' di un'altra categoria.

Elenchi Generati Dinamicamente

Un elenco generato dinamicamente inizia esattamente come un documento indice:

<?xml version='1.0' encoding='UTF-8'?>
<?xml-stylesheet href="/xsl/metadoc.xsl" type="text/xsl"?>
<?xml-stylesheet href="/xsl/guide.xsl"   type="text/xsl"?>

<!-- $Header$ -->

<!DOCTYPE dynamic SYSTEM "/dtd/metadoc.dtd">

<!-- Sostituire a "/doc/en/metadoc.xml" il percorso al file
metadoc desiderato -->
<dynamic metadoc="/doc/en/metadoc.xml">
<title>Gentoo Documentation Listing</title>

Come si può notare, non esiste il tag intro. Ora occorre aggiungere tutte le categorie principali che verranno inserite nell'Elenco. A differenza degli indici generati (che mostrano anche le informazioni introduttive di ciascun documento) aggiungiamo le categorie, taggate con list, tra i tag listing:

<listing>
  <list>faq</list>
  <list>install</list>
</listing>

Documenti di Riepilogo Generati Dinamicamente

Un documento di riepilogo inizia allo stesso modo dei due appena descritti:

<?xml version='1.0' encoding='UTF-8'?>
<?xml-stylesheet href="/xsl/metadoc.xsl" type="text/xsl"?>
<?xml-stylesheet href="/xsl/guide.xsl"   type="text/xsl"?>

<!-- $Header$ -->

<!DOCTYPE dynamic SYSTEM "/dtd/metadoc.dtd">

<!-- Sostituire a "/doc/en/metadoc.xml" il percorso al file
metadoc desiderato -->
<dynamic metadoc="/doc/en/metadoc.xml">
<title>Documentation Development Overview</title>

Anche qui puoi aggiungere una breve introduzione in formato GuideXML tra i tag intro, iniziando dall'elemento section. Dopodichè è sufficiente inserire un tag <overview/>.

<intro>
(...)
</intro>

<overview/>

I contenuti di questo documento sono rilasciati sotto la licenza Creative Commons - Attribution / Share Alike.