lf257, Applications: Usare BibTexML in DocBook XML per Scrivere Articoli Scientifici

LinuxFocus article number 257 http://linuxfocus.org

Egon Willighagen
<egonw(at)linuxfocus.org>

L'autore:

Specalizzato in chimica all'Universita di Nijmegen, sta conseguendo un PhD sulla ricerca per la rappresentazione delle molecole nella stessa università. Gioca a basket e programmaapplicazioni Java.

Tradotto in Italiano da:
Monja Da Riva <mdariva(at)inwind.it>

Usare BibTexML in DocBook XML per Scrivere Articoli Scientifici

Premessa:

In questo articolo mostrerò come usare BibTex come sistema per creare riferimenti in DocBook XML. Per semplificarne l'utilizzo ho sviluppato alcuni strumenti, che ora sono pacchetti nella distribuzione di JReferences.

_________________ _________________ _________________

Introduzione

Gli utenti LaTeX sanno quanto sia utile BibTex. È uno strumento molto comodo per creare riferimenti ad altri testi scentifici senza preoccuparsi molto dell'output, che risulterà corretto in ogni caso - per esempio dando le corrette impostazioni, ma senza alcun intervento manuale. Esattamente come LaTeX. Inoltre, nella letteratura scientifica è molto comune numerare i riferimenti con apici, come questo¹, e questi numeri devono essere in ordine progressivo. BibTex si occupa anche di questo.

DocBook sta diventando il mio metodo preferito per scrivere testo ogni giorno di più, per la sintassi XML molto lineare, il grande supporto per creare siti web (es. il sito CDK, http://cdk.sf.net/, è stato scritto completamente con DocBook) e pagine man. Il passo successivo per me era usare DocBook per scrivere articoli scientifici. Per questo mi serviva BibTex. Così ho scritto JReferences.

JReferences fa poco di più di quella che fa BibTex. Come BibTex, ha uno strumento per autonumerare i riferimenti da un database in formato solo testo, ma ne ha anche di più. Supporta più formati sia in input che in output, ha un backend MySQL a cui si può accedere tramite un frontend PHP. Tenta anche di essere un database di riferimenti, come EndNote. Tuttavia, essendo un progetto open source (licenza GPL) che non ha attratto molti altri sviluppatori oltre a me stesso, sta crescendo molto lentamente. Questo non significa che non sia utile, lo vedrete nel seguito dell'aricolo.

Alla data di pubblicazione originaria di quest'articolo JReferences era stato sviluppato fino alla versione 0.7.2. Questo articolo considera appunto questa.

Un Articolo con DocBook

Consideriamo l'esempio che trovate nel pacchetto JReferences.

<?xml version="1.0"?>
<!DOCTYPE article PUBLIC
"-//JReferences//DTD DocBook JReferences Module //EN"
                         "../dtd/jreferences.dtd" []>
<article>

  <jref:mode>Number</jref:mode>

  <articleinfo>
    <title>Test Article</title>
    <author><firstname>Egon</firstname>
	<surname>Willighagen</surname></author>
    <date> 3 May 2000</date>
  </articleinfo>

  <section>
    <title>Some section</title>
    <para>This is a text with a reference
   <jref:cite id="Steinbeck99"/>.</para>
    <para>And now for some more serious tests, we
    add a second reference <jref:cite id="Bachrach99"/>.
    And again the first reference <jref:cite id="Steinbeck99"/>.
    </para>
  </section>

  <jref:reflist/>

</article>

Commenterò quest'esempio riga per riga. La prima riga è la riga comune (opzionale) che indica la sintassi di qeusto file, che appunto è XML. Le righe dalla seconda alla quarta indicano che il linguaggio XML che è usato è DocBook, ma che al posto di usare il modulo DTD è usato il JReference. Il normale DocBook XML non conosce JReference, e usare il DTD darebbe documenti non validi. Il modulo JReference, invece, riconosce sia DocBook che JReference (per chi conosce DocBook: niente supporto per SVG o MathML ancora). Usare questo modulo, quindi, vi dà la possiblità di rendere valido il documento di nuovo. L'esempio sopra è un documendo DocBook valido.

La quinta riga contiene il tag iniziale dell'articolo. Alla settima linea comincia il divertimento.L'elemento <jref:mode> viene usato per dire a JReference che tipo di riferimento numerico deve essere usato. Nell'introduzione ho già detto che normamente si usano gli apici. Ci sono comunque tante alternative. JReference supporta [1], ¹, e [Steinbeck99]. L'ultimo si ottiene dal codice usato nel riferimento, l'esempio usa la prima opzione.

Le righe successive contengono alcuni elementi base di DocBook, la prossima riga veramente interessante è la 17. In questa linea il primo riferimento viene citato. Gli utenti LaTeX userebbero \cite{}; la sintassi JReference è <jref:cite id="SomeID"/>. L'ID corrisponde al riferimento nel database, che verrà spiegato più avanti. Il paragrafo successivo della sezione contiene altre due citazioni, una delle quali corrisponde sempre al primo riferimento.

Per includere l'elenco dei riferimenti, si usa <jref:reflist/> come alla riga 24. Questo comando JReferences convertirà la lista dei riferimenti in formato DocBook, nell'ordine in cui i riferimenti sono citati.

Il database BibTeXML

Il sistema JReferences ha bisogno di un database, molto simile ai file *.bib di Latex/BibTex. JReferences supporta sia un backend BibTeXML, che altri (come MySQL per esempio). BibTeXML è stato sviluppato da Vidar Gundersen e Zeger Hendrikse. L'esempio nel pacchetto JReferences (0.7.2) non usa BibTeXML ancora, ma l'articolo di esempio utilizzerà un file BibTeXML come:

<?xml version="1.0" encoding="UTF-8"?>
<bibtex:file xmlns:bibtex="http://www.bitjungle.com/~bibtex/">

<bibtex:entry bibtex:id="Steinbeck99">
  <bibtex:article>
    <bibtex:title>JChemPaint - Using
        the Collaborative Forces of the Internet to
        Develop a Free Editor for 2D Chemical
        Structures</bibtex:title>
    <bibtex:author>Steinbeck, C. and
                      Krause, S. and
                      Willighagen, E.</bibtex:author>
    <bibtex:year>2000</bibtex:year>
    <bibtex:volume>5</bibtex:volume>
    <bibtex:pages>93-98</bibtex:pages>
  </bibtex:article>
</bibtex:entry>

<bibtex:entry bibtex:id="Bachrach99">
  <bibtex:article>
    <bibtex:title>End-User Customized Chemistry Journal
    Articles</bibtex:title>
    <bibtex:author>Bachrach, S. and
                      Krassavine, A. and
                      Burleigh, D.</bibtex:author>
    <bibtex:journal>J.Chem.Inf.Comput.Sci.</bibtex:journal>
    <bibtex:year>1999</bibtex:year>
    <bibtex:volume>39</bibtex:volume>
    <bibtex:pages>81-85</bibtex:pages>
  </bibtex:article>
</bibtex:entry>

</bibtex:file>

La seconda riga contiene il tag iniziale per l'elemento radice <bibtex:file>. Un file di questo tipo contiene uno o più <bibtex:entry> elementi. Ogni entry consiste di un tipo di riferimento BibTeXML: article, book, inbook, incollection, unpublished, misc e others. Ogni riferimento di questo tipo contiene elementi specifici per quel tipo, alcuni dei quali sono ripetuti come <bibtex:title> e <bibtex:year>. Il pacchetto JReference include il DTD BibTeXML in modo che ogni editor XML che usa DTD potrà facilmente visualizzare documenti BibTeXML. Inoltre, JReference contiene Meta DTD per Kate di KDE 3.x (cfr. Editing DocBook XML Documents) che sono installati automaticamente in $HOME/.kde/share/apps/katexmlplugin.

Editare file BibTeXML con Kate, i suoi plugin XML e il Meta DTD BibTeXML di JReferences.

Generare un bibliografia

Considerate i due file di esempio seguenti. Il documento DocBook è salvato come article.docbookxml, e il database dei riferimenti come references.bibtexml. JReferences ancora non contiene uno strumento come il programma bibtex, ma lo stesso risultato può essere ottenuto con pochi comandi. Per poter usare i comandi sotto elencati dovete aver installato JReference in un sistema Unix-like, come Linux (vedere sotto):

jref-clear --filedb
jref-set --filedb --bibtexml references.bibtexml
jref-number --filedb article.docbookxml > article-numbered.docbookxml

Il file risultante, chiamato article-numbered.docbookxml, è un documento DocBook XML 4.1.2 valido, senza alcun elemento <jref:*> e può essere processato con qualsiasi altro strumento e utilizzato per converire il documento DocBook XML in, per esempio, PDF. (cfr. per esempio Realizzare documenti PDF con DocBook .

Il PDF risultante con rifermenti numerati e bibliografia inclusa.

Questo è tutto quello che dovete sapere. O, quasi...

Impostare gli Stili

C'è un'altra cosa interessante. BibTex supporta gli stili, perchè la maggior parte delle riviste ha degli specifici requisiti sull'aspetto della bibliografia. JReferences contiene solo due stili al momento. Il primo è una specie di formato standard di DocBook XML, che non è realmente uno stile. E' disponibile inoltre uno stile richiesto dall'American Chemical Society (ACS).

L'elemento <jref:reflist> ha un attributo @style con il quale potete impostare lo stile da usare al posto di quello di default. Per usare lo stile ACS dovete sostituire la riga 23 con

<jref:reflist style="ACS"/>

Installing JReferences

JReferences richeide Java 1.3 (o superiore), Xerces, Log4J e DocBook XML DTD 4.1.2. Alcune opzioni richiedono componenti aggiuntivi, come python (per conversioni tra BibTex e BibTeXML), e Perl (per pulire l'output BibTex di EndNote).

Se avete installato tutto questo, potete procedere all'installazione di JReference:

./configure --prefix=$HOME
make
make install

Se alcuni strumenti non vengono trovati, provate con: --with-xercesdir, --with-log4javadir e --with-sgmldir. Per ulteriori informazioni riguardo a queste opzioni provate con "./configure --help".

Il Progetto

JReference ormai è al suo secondo anno, e pur essendo stato scaricato molte volte non ho ricevuto molti commenti. Quindi questa è la mia esperienza personale. Negli ultimi mesi JReference è stato usato con successo per scrivere un vero articolo scientifico. Tuttavia, come ogni buon progetto open source, ogni commento, bug riportato, patch, idea e racconto di utilizzo positivo sono benvenuti nel sito JReferences.

Riferimenti

Translation information:

en --> -- : Egon Willighagen <egonw(at)linuxfocus.org>

en --> it: Monja Da Riva <mdariva(at)inwind.it>

2005-01-14, generated by lfparser_pdf version 2.51