[PLUTO-devel] XPJ Format reloaded
Marco Marongiu
bronto a tiscali.com
Dom 30 Gen 2005 18:12:03 CET
A beneficio di tutti (spero non a beneficio di inventario) ricommento da
capo il file che definisce il formato di XPJ, scritto esso stesso in
XPJ; in allegato avete anche una sua possibile conversione in HTML. I
file sono sempre quelli "famosi" delle specifiche 0.1
Il formato fu pensato principalmente per descrivere gli articoli del
Journal, ma si cerco` di lasciare spazio per possibili utilizzi diversi
(e io ne approfittai per scrivere con successo della documentazione
tecnica per l'azienda dove lavoravo prima).
Il formato e` costruito in modo che non ci sia testo sparso se non in un
numero molto ristretto di tag.
Il root tag e` <article>, seguito a ruota dalle metainformazioni sul
documento. le metainformazioni seguono passo passo il dublin core:
Il titolo:
<title>The XPJ articles format</title>
Gli autori, corredati eventualmente da un URL sulla quale trovare
maggiori informazioni sugli autori stessi:
<!--
author is equivalent to DC's Creator Element, and
may appear more than once
-->
<author url="mailto:bronto at crs4.it">Marco Marongiu</author>
<author url="mailto:mari at trifida.it">Marina Sturino</author>
L'argomento dell'articolo, per il quale potremmo stabilire un dizionario
di valori ammessi:
<subject>PLUTOWare</subject>
Chi pubblica l'articolo, p.e.:
<publisher>PLUTO Free Software Users Group</publisher>
Chi ha contribuito a scriverlo, stessa sintassi di author:
<contributor url="mailto:nicolafragale at libero.it">Nicola
Fragale</contributor>
<contributor url="mailto:mano at pluto.linux.it">Germano Rizzo</contributor>
<contributor>The PLUTO Journal Staff</contributor>
La data in formato W3CDTF, come prescrive il dublin core:
<date>2002-01-25</date>
> Element Name: Date
> Label: Date
> Definition: A date of an event in the lifecycle of the resource.
> Comment: Typically, Date will be associated with the creation or availability of the resource. Recommended best practice for encoding the date value is defined in a profile of ISO 8601 [W3CDTF] and includes (among others) dates of the form YYYY-MM-DD.
Il tipo di contenuto. Anche qui dovremmo forse fare lo sforzo di
inventarci un dizionario specifico per il PJ
<type>Technical Article</type> <!-- fixed? -->
Il formato in cui e` scritto il documento. Per noi sarebbe sempre
text/xml (e in effetti, come si vede, avevo il dubbio se tenerlo o no)
<format>text/xml</format> <!-- fixed. Should we write it? -->
Una breve stringa che identifichi, dica che cosa e` questo documento:
<identifier>XPJ Specification, version 0</identifier>
trovate degli esempi nelle specifiche DC:
> Element Name: Identifier
> Label: Resource Identifier
> Definition: An unambiguous reference to the resource within a given context.
> Comment: Recommended best practice is to identify the resource by means of a string or number conforming to a formal identification system. Formal identification systems include but are not limited to the Uniform Resource Identifier (URI) (including the Uniform Resource Locator (URL)), the Digital Object Identifier (DOI) and the International Standard Book Number (ISBN).
La lingua in cui e` scritto l'articolo, secondo specifiche DC:
<lang>it-IT</lang> <!-- equivalent of DC's Language Element -->
> Element Name: Language
> Label: Language
> Definition: A language of the intellectual content of the resource.
> Comment: Recommended best practice is to use RFC 3066 [RFC3066] which, in conjunction with ISO639 [ISO639]), defines two- and three-letter primary language tags with optional subtags. Examples include "en" or "eng" for English, "akk" for Akkadian", and "en-GB" for English used in the United Kingdom.
Questa e` roba nostra: la licenza con cui distribuiamo il documento
<rights>This Document may be redistributed under the terms
specified in the GNU Free Documentation Language</rights>
Segue quindi l'abstract del documento. Anche in questo caso, stiamo
pensando a delle informazioni definite nel DC: un paragrafo che dia un
sommario del documento:
<abstract>
<!--
this section is equivalent to the DC's Description Element
and must contain only a paragraph of PCDATA
-->
This document describes the XPJ documentation format. XPJ is an
XML format specially suited for writing technical articles. Articles
may be published on the world wide web in a variety of formats:
HTML, XHTML, PDF(TM), PostScript(TM), LaTeX, plain text, RDF, RSS
and, obviously, XML :-)
</abstract>
> Element Name: Description
> Label: Description
> Definition: An account of the content of the resource.
> Comment: Examples of Description include, but is not limited to: an abstract, table of contents, reference to a graphical representation of content or a free-text account of the content.
Seguono poi i capitoli. Il titolo e` in un tag a parte (e non in un
attributo) in modo da poter usare PCDATA (e non solo CDATA): possiamo
sbizzarrirci ad usare le entita` (p.e.: simboli matematici e lettere
greche) se serve
<chapter>
<title>This title can contain PCDATA</title>
I capitoli possono contenere paragrafi di testo o sottocapitoli, le
<section>:
<chapter>
<title>Chapters can have sections, too</title>
<p>Yes, they really do!</p>
<section>
<title>Embedding code in articles</title>
Un tag che va subito messo in evidenza e' <kw>, keyword. Con questo tag
marchiamo appunto le keyword, che poi il "processore" che trasformera`
l'articolo potra` catalogare automaticamente. Ad esempio, nel HTML
trovate il tag meta corrispondente:
<meta name="DC.Subject" content="keywords, META tags, dc:subject, code
tag, listing tag, keyword, link tag, url attribute, id attribute,
tables, appendix tag, bio tag, emph tag, sup tag, sub tag">
Torniamo a XPJ. C'e` tutto quello che serve per inserire porzioni di
codice inline o listati estesi:
<p>
Short, inline sections of <code>computer code</code>, like
commands for example, are marked using the <kw>code
tag</kw>. Longer blocks of code should use the <kw>listing
tag</kw> instead. For example:
</p>
<listing><![CDATA[
#!/bin/bash
# This section of code should be written as-is
# It is good practice to put it inside a [CDATA[...] section
# to avoid character escaping.
# How a system administrator makes love:
touch me
make love
more sex
yes please
]]></listing>
Elenchi, eventualmente ricorsivi:
<list>
<item>first item</item>
<item>second item</item>
<list>
<item>second.first item</item>
<item>second.second item</item>
<item>item with a <kw>keyword</kw></item>
</list>
<item>third item</item>
</list>
OCCHIO!!! Il testo va *solo* dentro <item>, non sparso in giro!
Link e ancore per i riferimenti incrociati, come in HTML:
<p>
We have the <kw>link tag</kw> to create links,
<link url="http://www.pluto.linux.it">like this</link>, for
example. We use the <kw>url attribute</kw> to create
links and <link id="sample_anchor">the <kw>id
attribute</kw></link> to create anchors, which we could
<link url="#sample_anchor">refer to</link>.
</p>
Tabelle:
<table>
<row>
<cell type="heading" cols="2">Writers</cell>
</row>
<row>
<cell rows="2" type="heading">XPJ writers</cell>
<cell>Marco Marongiu</cell>
</row>
<row>
<cell>Marina Sturino</cell>
</row>
</table>
che in HTML possono essere tradotte per esempio cosi`:
<div align="center"><table cellpadding="0" cellspacing="0">
<tr>
<th colspan=2>Writers</th>
</tr>
<tr>
<th rowspan=2>XPJ writers</th>
<td>Marco Marongiu</td>
</tr>
<tr>
<td>Marina Sturino</td>
</tr>
</table></div>
E ci sono anche figure, che sono pensate un po` alla latex dove c'e` un
environment figure che contiene le figure vere e proprie:
<figures>
<figure url="image.jpg">A small caption here</figure>
<figure url="another.jpg">Another figure, another
caption</figure>
</figures>
Il HTML contiene una traduzione di questo blocco:
<div align="center"><table cellspacing="0" cellpadding="0">
<tr align="center"><td><a name="image.jpg"><img
src="image.jpg"></a></td><td><a name="another.jpg"><img
src="another.jpg"></a></td></tr>
<tr><th><span class="caption">Figura 1: A small caption
here</span></th><th><span class="caption">Figura 2: Another figure, another
caption</span></th></tr>
</table></div>
Non c'e` praticamente nessun supporto per effetti tipografici, a parte
apice e pedice, e abbiamo i soliti tag che permettono di enfatizzare
certe sezioni di testo (come farne a meno?):
<list>
<item>Use the <kw>emph tag</kw> to <emph>emphasize
text</emph>;</item>
<item>use the <kw>sup tag</kw> for <sup>superscripts</sup>;</item>
<item>use the <kw>sub tag</kw> for <sub>subscripts</sub></item>
</list>
e ovviamente, note a pie` pagina:
<p>
Yes, you have footnotes<fn id="need">we know you need
them</fn>. You should be thankful about it! <!-- :-) -->
</p>
Per chiudere, ci sono appendici e bibliografia
<appendix>
e` come un capitolo, ma cambia la numerazione e la referenziazione
automatica, e:
<biblio>
<bibitem>
<!-- a subset of DC-like elements allowed here:
* author
* publisher
* HREF (CAZZO! Come si chiamava l'elemento del DC???) -->
<author>Someone</author>
<author>Someone else</author>
<title>Mastering the shift key</title>
<publisher>Uncle SAMS</publisher>
Description of this book goes here...
</bibitem>
e un piccolo paragrafo di PCDATA per le note biografiche degli autori
dell'articolo:
<bio face="myface.jpg">
<!-- Just one small paragraph of PCDATA, thanks -->
Marco Marongiu is just another perl hacker. Don't contact him, he
is nasty!
</bio>
Questo e` XPJ e perche' e` fatto in questo modo.
Ciao
--bronto
-------------- next part --------------
A non-text attachment was scrubbed...
Name: format.xml
Type: text/xml
Size: 6263 bytes
Desc: not available
Url : http://lists.pluto.it/pipermail/pluto-devel/attachments/20050130/83ba6552/format-0001.bin
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.pluto.it/pipermail/pluto-devel/attachments/20050130/83ba6552/format-0001.html
Maggiori informazioni sulla lista
pluto-devel