Articoli Manifesto Tools Links Canali Libri Contatti ?
SIForge

SIForge XML (6ML)

Abstract
In questo articolo verrà presentato il linguaggio a marcatori usato per impostare un documento per il publish su SIForge.
Data di stesura: 01/09/2002
Data di pubblicazione: 01/09/2002
Ultima modifica: 04/04/2006
di Marco Lamberto Discuti sul forum   Stampa

Convenzioni usate in questo documento

All'interno della definizione di un tag la presenza di un parametro fra parentesi quadre ("[", "]") sta ad indicare che questo è opzionale.

Quando un parametro può assumere un valore fra una lista di valori predefiniti questi sono elencati separati da un carattere di "pipe" ("|").
I puntini "..." indicano invece un valore qualsiasi.

Prima di cominciare

È importante sottolineare che essendo un documento XML non è possibile usare direttamente i caratteri "<", ">" ed "&", è quindi obbligatorio adottare le entities equivalenti "&lt;", "&gt;" e "&amp;".
Ogni tag XML deve essere chiuso: subito ("<tag />") o dopo un blocco a cui si riferisce ("<tag> ... </tag>").

Organizzazione del materiale per il publish

Il file xml deve avere un nome minuscolo formato da una o più parole separate da "_". Orientativamente è possibile usare quelle del titolo previa eliminazione di punteggiatura, articoli e congiunzioni.

Assieme al file XML, se è la prima volta che venite pubblicati, è necessario un altro file contenente il vostro nome e cognome assieme ad una breve e concisa descrizione.
Il vostro "authid" (da inserire nell'articolo) corrisponderà al vostro nome e cognome, minuscoli, separati da un carattere "_".

Sorgenti, immagini e qualsiasi altro documento devono essere contenuti in una directory avente lo stesso nome dell'articolo senza estensione .xml. Ogni file deve essere referenziato nel sorgente xml con un path relativo.

$ /bin/ls -R .
.:
python-intro.xml python-intro

./python-intro:
lastrdf.xml rdfparser.py
In questo esempio supponiamo che Mario Rossi abbia scritto un articolo contenente un paio di immagini ed un link ad un sorgente di esempio, questo è quello che ci aspetteremo di ricevere:
mario_rossi.txt
critiche_linguaggi_oo.xml
critiche_linguaggi_oo/grafico1.gif
critiche_linguaggi_oo/grafico2.gif
critiche_linguaggi_oo/Test1.java
In particolare il file di descrizione dell'autore e l'articolo XML conterranno qualche cosa di simile a questi due esempi:
Mario Rossi
laureato in ... lavora presso ... progettazione ...
<article
  topic="Linguaggi"
  title="Critiche ai linguaggi OO"
  author="mario_rossi"
  date="20020915"
>
  <abstract>
    In questo articolo cerchero` di ...
  </abstract>

  <body>
    I moderni linguaggi
    ...
    <img src="critiche_linguaggi_oo/grafico1.gif" alt="Diffusione" />
    ...
    <img src="critiche_linguaggi_oo/grafico2.gif" />
    ...
  </body>

  <resources>
    <resource id="test1" url="critiche_linguaggi_oo/Test1.java">
      Sorgente di esempio.
    </resource>
  </resources>
</article>

Struttura di base

Il file XML è suddivisibile in tre sezioni: l'abstract, il body con l'articolo vero e proprio ed una sezione opzionale di risorse.
<article topic="..." title="..." author="authid[,audthid,...]" date="yyyymmdd" [company="..."]>
  <abstract>
    ... l'abstract ...
  </abstract>

  <body>
    ... l'articolo ...
  </body>

  <resources>
    <resource id="..." [url="..."]>
      ... descrizione della risorsa ...
    </resource>
    ... altre risorse ... 
  </resources>
</article>

HTML subset

All'interno dell'articolo è possibile usare un subset di HTML (da usarsi secondo lo standard XHTML, estensione XML di HTML), nel particolare sono ammessi i seguenti tags:
<i> <b> <code>
<dl> <dt> <dd>
<ul> <ol> <li>
<table> <tr> <th> <td>

Paragrafi e separazione delle linee

<p />
<br />
Il paragrafo per (nostra) scelta non deve essere racchiuso tra i classici <p> e </p> ma semplicemente terminato con un <p />.

Per andare a capo basta usare un <br />.

Immagini

<img src="..." [alt="..."] [id="..."] [dynscale="..."] />
Le immagini sono molto semplici da usare, non prevedono dei link. Per farlo è sempre bene mettere un link esplicito nel testo.
[Figura 1]

Figura 1: Immagine di esempio con didascalia

Osservala a dimensioni reali

Questa immagine non ha didascalia.

[Figura 2]

Figura 2

Per ogni immagine è possibile specificare un id da poter referenziare con un tag link [I].

Il campo dynscale serve per specificare un rapporto per riscalare l'immagine (es. 0.5 riscala l'immagine alla meta`) e genera del codice JavaScript per farne il resize alle dimensioni reali a richiesta (utile per gli screenshots).

Immagine di esempio con dynscale a 0.5

Figura 3: Immagine di esempio con dynscale a 0.5

Links, links, e ancora links!

<link [text="..."] [url|resid|imgid="..."] />
Link di esempio.
Link http://www.siforge.org/about/.
Link a risorsa [1] specificando il "resid".
Link a risorsa con testo specificato[1]
Link a immagine [I] specificando l'"imgid".

Intestazioni, titoli, sezioni, ...

<h1>
<h2>
I tag h1 ed h2 si riferiscono rispettivamente ad una sezione ed ad una sottosezione.

h1: Titolo di sezione

Text ...

h2: Titolo di sottosezione

Text ...

Box, semplici caselle di testo

<box [title="..."] [type="normal|pre|source|console"] [counter="..."] [uri=".."] >
...
</box>
Contenitore generico per incapsulare tabelle, codice di esempio o altro.
Gli argomenti di "counter" e "uri" sono usati solo dai box nella modalità "source". Permettono di impostare la numerazione delle righe, nello specifico "counter" indica il valore d'inizio da cui numerarle.
Il formato dell'argomento di "uri" può essere:
file:sourcefile[:[start][-[end]]]
zip:zipfile:sourcefile[:[start][-[end]]]
L'omissione di entrambi i valori di inizio (start) e fine (end) implica l'inclusione completa del sorgente.

Il percorso di sourcefile e zipfile è relativo alla sotto directory dei dati (avente stesso nome del file dell'articolo, ma senza estensione) contenuta nel percorso dove l'articolo verrà pubblicato.

Alcuni esempi di uri:

file:mix.c
file:mix.c:10
file:mix.c:10-25
zip:archive.zip:mix.c
zip:archive.zip:mix.c:10
zip:archive.zip:mix.c:10-25
Alcuni esempi di box:
Box con valori di default
Altro box ma questa volta con titolo!
#include <stdio.h>

void main(void) {
  int i;

  // nonsense
  for (i = 0; i < 100; i++) {
    puts("this sucks");
  }
}
  1. #include <stdio.h> 
  2.  
  3. void main(void) { 
  4.   int i; 
  5.  
  6.   // nonsense 
  7.   for (i = 0; i < 100; i++) { 
  8.     puts("this sucks"); 
[ko]~$ echo "ciao"
ciao
[ko]~$

Misc

<fixme [text="..."] />
Il tag fixme serve per marcare le parti da sistemare, completare, rivedere.

FIXME

TBW

FIXME

con messaggio di testo

Informazioni sull'autore

Marco Lamberto, laureato in Informatica presso la Statale di Milano, con diversi anni di esperienza sistemistica, di sicurezza e sviluppo prevalentemente in ambienti UNIX (Linux in primis) con linguaggi come C, Java, Perl, PHP, XML, HTML, ...

È possibile consultare l'elenco degli articoli scritti da Marco Lamberto.

Altri articoli sul tema SIForge.

Discuti sul forum   Stampa

Cosa ne pensi di questo articolo?

Discussioni

Questo articolo o l'argomento ti ha interessato? Parliamone.