La sezione "Reference" presenta la guida di riferimento online di Biferno e delle classi e funzioni definite dall'utente. La «Reference On Line» presente sul sito www.biferno.it è una versione semplificata della sezione "Reference" di bifernoadmin.

Figura 4.1. Esempio di documentazione (classe folder)

Nella colonna di sinistra sono elencate tutte le classi predefinite (Predefined Classes), seguite dalle classi definite dall'utente (Application Classes, ovvero quelle implementate in linguaggio Biferno e caricate nell'applicazione corrente). Se si clicka sul link Functions (in fondo alla lista delle classi) si accede ad una pagina con l'elenco di tutte le funzioni predefinite (Predefined Functions) seguite dalle funzioni definite dall'utente (Application Functions).

Clickando sul nome di una classe si accede alla documentazione della classe. Nella parte superiore vengono presentate quattro colonne contenenti:

La prima pagina documenta anche il significato e lo scopo della classe e il suo costruttore. In particolare per quanto riguarda la classe vengono mostrati i seguenti campi della documentazione:

di seguito viene poi mostrata la documentzaione del costruttore della classe. In particolare per quanto riguarda il costruttore della classe vengono mostrati i seguenti campi della documentazione:

inoltre viene mostrato il prototipo del costruttore stesso.

Clickando su un metodo, proprietà, costante o errore si accede alla relativa documentazione. In ogni pagina vengono mostrati i seguenti campi di documentazione (quanto detto di seguito per i metodi si applica, se non specificato diversamente, anche alle proprietà, costanti o errori):

La documentazione delle funzioni è del tutto simile a quella dei metodi delle singole classi

Ogni pagina di documentazione contiene un link per modificare la documentazione stessa («Update Man Page»). Accedendo a questa pagina (protetta da password) è possibile modificare il contenuto di tutti i campi della documentazione.

In fondo alla pagina viene mostrata una anteprima della pagina di documentazione così come mostrata agli utenti.

Nei vari campi si deve inserire il relativo testo di documentazione tenendo presente le due seguenti regole:

Dopo aver riempito le caselle, premendo il bottone "Modify Man Page" i dati vengono inviati a Reference che li assembla in un unico file di documentazione. Tale file costituisce la struttura fondamentale della Guida di Riferimento e sarà consultato da Biferno ogni volta che verrà richiesta la documentazione di un certo metodo, funzione, proprietà, costante, errore o classe.

Ogni file di documentaaione può documentare uno dei seguenti elementi di Biferno (documentation unit):

Tale file deve essere anche distribuito insieme alla implementazione della propria classe (o metodo etc...). In questo modo si dà agli utenti la possibilità di consultarne la documentazione sul proprio servizio di Reference.

Il file di documentazione viene salvato in formato XML. Tuttavia non è richiesta alcuna conoscenza dell'XML da parte dell'utente per poter agire sul file in quanto la struttura interna viene completamente gestita da Biferno. Il paragrafo successivo tuttavia spiega come sia possibile, per gli utenti più esperti, controllare maggiormante la formattazione dei campi di documentazione.

Il file di documentazione creato da Biferno (man page) è un file XML che segue le regole di una DTD (Document Type Definition) definita da Biferno. Per i più curiosi, alla fine del paragrafo (vedi Figura 4.2, «La DTD per la documentazione di Biferno»), riportiamo la struttura della versione attuale della DTD di Biferno.

L'utente che sta editando la documentazione non deve comunque preoccuparsi di tutti i tag della DTD in quanto, come detto, Biferno assembla automaticamente i testi inseriti in altrettanti tag XML definiti dalla DTD.

E' possibile tuttavia inserire i seguenti tag all'interno dei campi della documentazione per ottenere una maggior controllo sulla struttura della documentazione stessa:

E' importante non inserire altri tag della DTD autonomamente per non interferire in maniera scorretta col processo di creazione dell'XML eseguito automaticamente da Reference.

E' possibile vedere il sorgente del file XML prodotto da Reference clickando sul link «Show Man File». Clickando invece sul link «Show Man XML» si può esaminare il file XML così come processato dal Browser. Quest'ultima operazione può essere utile per validare il file, verificando così di non aver inserito tag invalidi nel testo.

In linea di principio è possibile, per utenti esperti di XML, produrre il file di documentazione con qualunque editor di testo a partire dalla struttura della DTD di Biferno, di seguito riportata:

<?xml version='1.0' encoding='UTF-8' ?>
<!-- Biferno documentation DTD version 1.0 -->
<!ENTITY % isolat1 SYSTEM "./iso-lat1.ent">
<!ENTITY % isolat2 SYSTEM "./iso-lat2.ent">
<!ENTITY % isopub SYSTEM "./iso-pub.ent">
<!ENTITY % isonum SYSTEM "./iso-num.ent">
%isolat1;
%isolat2;
%isopub;
%isonum;
<!-- ********************* -->
<!ELEMENT bifdoc (class | method | property | constant | error | function)+>
<!-- ********************* -->
<!ELEMENT class (name , purpose? , descr , see_also? , note?)>
<!ATTLIST class  implem (c | b) #REQUIRED >
<!-- ********************* -->
<!ELEMENT method (pclass , name , purpose? , prototype , descr , returns? ,
                  errors? , see_also? , note?)>
<!ATTLIST method  static      (yes | no )  #REQUIRED
                  visibility  (private | public | protected )  #REQUIRED
                  varargs     (yes | no )  'no'
                  nonames     (yes | no )  'no' >
<!-- ********************* -->
<!ELEMENT property (pclass , name , purpose? , return_value , descr , returns? , 
                    errors? , see_also? , note?)>
<!ATTLIST property  static      (yes | no )  #REQUIRED
                    visibility  (private | public | protected )  #REQUIRED >
<!-- ********************* -->
<!ELEMENT constant (pclass , name , purpose? , return_value , descr , returns? , 
                    errors? , see_also? , note?)>
<!ATTLIST constant  static      (yes | no )  #REQUIRED
                    visibility  (private | public | protected )  #REQUIRED >
<!-- ********************* -->
<!ELEMENT error (pclass , name , purpose? , return_value , descr , errors? , 
                 see_also? , note?)>
<!ATTLIST error  visibility  (private | public | protected )  #REQUIRED >
<!-- ********************* -->
<!ELEMENT function (name , purpose? , prototype , descr , returns? , errors? , 
                    see_also? , note?)>
<!ATTLIST function  implem 	(c | b) #REQUIRED
		    varargs (yes | no )  'no'
                    nonames (yes | no )  'no' >
<!-- ********************* -->
<!ELEMENT prototype (return_value? , param_list?)>
<!ELEMENT pclass (#PCDATA)>
<!ELEMENT name (#PCDATA)>
<!ELEMENT purpose (par)>
<!ELEMENT return_value (pclass , aeclass? , aelevel?)>
<!ELEMENT aeclass (#PCDATA)>
<!ELEMENT aelevel (#PCDATA)>
<!ELEMENT param_list (param)+>
<!-- ********************* -->
<!ELEMENT param (pclass , ptarget?, name , default? , aeclass? , aelevel? , descr)>
<!ATTLIST param  mandatory  (yes | no | undef )  'undef'>
<!-- ********************* -->
<!ELEMENT ptarget (#PCDATA)>
<!ELEMENT default (#PCDATA)>
<!ELEMENT descr (par | code)+>
<!ELEMENT returns (par | code)+>
<!ELEMENT errors (par | code)+>
<!ELEMENT see_also (par | code)+>
<!ELEMENT note (par | code)+>
<!ELEMENT par (#PCDATA | link | code | inlinecode)*>
<!-- ********************* -->
<!ELEMENT link (#PCDATA)>
<!ATTLIST link  linkend CDATA  #REQUIRED >
<!-- ********************* -->
<!ELEMENT inlinecode (#PCDATA)>
<!ELEMENT code (#PCDATA)>

    

una volta completato, il file va copiato in una cartella che abbia per nome il nome della classe di cui fa parte il metodo, proprietà, costante o errore (o il nome «function» se si tratta di una funzione, o il nome della classe stessa se si tratta della pagina di descrizione di una classe). Questa cartella va poi copiata in una delle due seguenti posizioni:

(se si hanno dubbi sul posizionamento dei file si può comunque eseguire l'operazione da Reference e vedere dove questi vengono automaticamente posizionati).

Questo è un esempio di file di documentazione (il metodo IsDate della classe string):

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE bifdoc SYSTEM "http://www.tabasoft.it/biferno/bfdocdtd/bifdoc.dtd">
<bifdoc>
	<method static="no" visibility="public">
		<pclass>string</pclass>
		<name>IsDate</name>
		<purpose><par>Check the string for a 
		valid date</par></purpose>
		<prototype>
			<return_value>
				<pclass>boolean</pclass>
			</return_value>
			<param_list>
			<param>
				<pclass>string</pclass>
				<name>format</name>
				<descr><par>specifies the expected 
				order of day, month, year ( the default is the 
				one defined by the application variable 
				DATE_FORMAT). A dash (-), a forward slash (/), 
				or the separator defined in DATE_FORMAT 
				can be used as 
				separators.</par></descr>
			</param>
			</param_list>
		</prototype>
		<descr><par>The IsDate method of the 
		string class returns 
		true if the string has the format of a valid
		date</par></descr>
		<note><par>Example:
		<code>
		aDate = "24-10-2001"
		check_date = aDate.IsDate("d-m-y") //returns true
		check_date = aDate.IsDate("y-m-d") //returns false
		</code></par></note>
        </method>
</bifdoc>

La seconda linea contiene la dichiarazione di DTD. Il file di DTD è disponibile online sul sito di tabasoft. Reference esegue la validazione ogni volta che una pagina viene modificata (bottone "Modify Man Page" della pagina "Update Man Page") e solo se l'estensione di Biferno xml_bfr è stata caricata all'avvio. Tuttavia, se un utente non è connesso ad Internet può continuare a modificare le pagine, ignorando il messaggio di errore nella validazione ("no DTD found!"). Potrà in seguito controllare la validità dei file risalvandoli più tardi, con una connessione di rete attiva.

I seguenti file sono anche inclusi dalla DTD:

questo non dovrebbe tuttavia riguardare mai l'utente in quento questi files sono anch'essi presenti nella stessa cartella della DTD: http://www.tabasoft.it/biferno/bfdocdtd