Gentoo Logo

Guida a Gentoo Metadoc XML

Indice:

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

Si osservi che l'ultimo punto è ancora in fase embrionale e probabilmente non subirà ulteriori sviluppi. Alcuni gruppi di traduzione usano script basati su trads-doc per amministrare le traduzioni, altri usano strumenti di traduzione online. Se si inizia il lavoro di traduzioni per Gentoo, presentarsi in #gentoo-doc o chiedere aiuto alla mailing list gentoo-doc@gentoo.org.

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:

Codice 2.1: Apertura del file XML

<?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.

Codice 2.2: Dichiarazioni di MetadocXML (Inglese)

<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.

Codice 2.3: Dichiarazioni di MetadocXML (versioni tradotte)

<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.

Codice 2.4: Esempio d'uso di 'members'

<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.

Codice 2.5: Esempio d'uso di 'categories'

<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.

Codice 2.6: Esempio d'uso di 'files'

<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, fileid che lo mette in relazione con l'attributo id di un'entità file corrispondente con il file principale del documento.

Nel caso di un capitolo di manuale, l'entità doc deve contenere un'altra entità bookref che stabilisce la relazione con la pagina principale del manuale. Questa entità contiene due attributi, chiamati vpart e vchap che si riferiscono ai corrispondenti paret e capitolo del documento all'interno del manuale.

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.

Codice 2.7: Esempio d'uso di 'docs'

<docs>
  <doc fileid="ldap-howto">
    <memberof>sysadmin_specific</memberof>
    <bugs>
      <bug>102481</bug>
      <bug stopper="yes">1151330</bug>
    </bugs>
  </doc>
  <doc fileid="uml">
    <memberof>sysadmin_general</memberof>
  </doc>
</docs>

Esempio di file metadoc.xml

Il sito Gentoo usa un file metadoc.xml per aggregare le informazioni su tutta la sua documentazione. È possibile vedere la versione corrente online.

3.  File Correlati con MetadocXML

Indice Generato Automaticamente

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

Codice 3.1: Indice Generato Dinamicamente

<?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:

Codice 3.2: Elenco generato dinamicamente

<?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:

Codice 3.3: Elenco delle categorie

<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:

Codice 3.4: Documento di riepilogo generato dinamicamente

<?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/>.

Codice 3.5: I tag 'intro' e 'overview'

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

<overview/>


Stampa

Aggiornato il 4 settembre 2011

Oggetto: Questa guida, destinata agli sviluppatori, spiega come usare il formato Metadoc XML che permette al Gentoo Documentation Project di gestire la gerarchia della documentazione e consente di immagazzinare un maggior numero di informazioni riguardo ciascun documento.

Sven Vermeulen
Autore

Xavier Neys
Redazione

José María Alonso
Redazione

Massimo Canali
Traduzione

Donate to support our development efforts.

Copyright 2001-2014 Gentoo Foundation, Inc. Questions, Comments? Contact us.