Biferno: manuale di bifernoadmin

bifernoadmin è un servizio web, interamente realizzato in linguaggio Biferno, che permette l'amministrazione remota e la modifica di una applicazione Biferno tramite una interfaccia accessibile da qualunque browser internet.

Per il concetto di applicazione Biferno si veda il Cap. 9 del documento: "Biferno: Language Guide". In generale, per una completa comprensione del presente documento è necessario aver letto il suddetto manuale (disponibile sul sito www.biferno.it) avendo compreso almeno i principi generali di Biferno e delle sue applicazioni.

bifernoadmin viene automaticamente installato all'atto della installazione di Biferno, ma rimane inattivo fino a configurazione completata come descritto in: Sezione 4, «Configurazione e note sulla sicurezza». Esso consiste di una cartella, di nome bifernoadmin, contenente gli script .bfr che implementano tutte le funzionalità del servizio.

Tale cartella viene installata nella directory BifernoHome del computer su cui si installa Biferno

Cos'è BifernoHome

BifernoHome è il percorso della cartella centrale cui fa riferimento Biferno per le proprie impostazioni generali e per il salvataggio di alcuni file utili al suo funzionamento (file di log, file di spool delle mail etc...). La sua posizione dipende dal Sistema Operativo in cui si sta lavorando: Linux: il percorso alla cartella BifernoHome è: /home/BifernoHome MacOSX: il percorso alla cartella BifernoHome è: /Users/BifernoHome Windows: il percorso alla cartella BifernoHome viene specificato dall'utente al momento dell'installazione (default: [Program files]\Biferno\BifernoHome). MacOS Classic: BifernoHome è il percorso della cartella di nome BifernoHome al primo livello del disco di Startup Su tutti i sistemi operativi è anche possibile sapere il percorso della cartella BifernoHome esaminando (in uno script biferno) la proprietà: biferno.home BifernoHome contiene anche l'applicazione main di cui tutte le altre applicazioni sono figlie (per il concetto di sottoapplicazione, o applicazione figlia, e per altri dettagli su BifernoHome si veda il manuale :"Biferno: Language Guide").

Per accedere a bifernoadmin è necessario digitare nel proprio browser la URL della cartella contenente l'applicazione che si vuole amministrare seguita dalla stringa bifernoadmin/index.bfr; la stringa index.bfr è facoltativa se si è impostata correttamente la DirectoryIndex nelle preferenze del server web, cioè la pagina che il server web deve mostrare qualora nella URL sia specificata solamente la directory.

Per esempio, per amministrare l'applicazione contenuta nella cartella MyApplication sul sito www.mysite.com si deve digitare la url:

https://www.mysite.com/MyApplication/bifernoadmin/index.bfr

per quanto riguarda l'uso del protocollo https nella URL (invece del semplice http) si veda: Sezione 4, «Configurazione e note sulla sicurezza» più avanti.

Si noti che nella cartella MyApplication non esiste nessuna cartella bifernoadmin (che si trova invece in BifernoHome), eppure la url viene ritrovata correttamente! Il trucco consiste nel fatto che Biferno automaticamente intercetta tutte le url che contengono la parola bifernoadmin e le redirige su: [BifernoHome]/bifernoadmin/index.bfr. Se così non fosse, sarebbe necessario replicare la cartella bifernoadmin in tutte le applicazioni, con un conseguente spreco di spazio su disco e una maggiore difficoltà nel mantenimento del codice. Da questo intuiamo anche che la parola bifernoadmin è una parola riservata e non deve mai essere usata per nominare i nostri script (o cartelle contenenti i nostri script).

bifernoadmin è costituito da quattro strumenti fondamentali:

Più avanti esamineremo i dettagli di tutti questi strumenti.

L'accesso a bifernoadmin deve essere consentito solo allo sviluppatore (o all'amministratore) dell'applicazione per evitare intrusioni e possibili danni. Un utente male intenzionato potrebbe eseguire un reload dell'applicazione in un momento non desiderato o (peggio) modificare i file del nostro sito usando Edit. Dunque è importante soffermarci un momento sui meccanismi di protezione che il servizio mette in atto, e sulle possibili impostazioni che ne influenzano il comportamento

Per ottenere una protezione adeguata bifernoadmin agisce su tre livelli diversi:

4.1. Controllo del protocollo di comunicazione

Prima ancora di verificare l'identità dell'utente, bifernoadmin confronta il protocollo che si sta usando per richiedere l'accesso con la lista dei protocolli accettati. I protocolli accettati sono elencati nella variabile applicazione ADMIN_PROTOCOL definita nel Biferno.config.bfr dell'applicazione, come in:

ADMIN_PROTOCOL = "https"

che stabilisce come unico protocollo accettato l'HTTPS (HTTP sicuro). In particolare l'utilizzo del protocollo HTTPS prevede la trasmissione dei dati in modalità criptata ed è dunque più sicuro del semplice HTTP. Se si è definito questo protocollo e si cerca di accedere a bifernoadmin tramite semplice HTTP, si ottiene la seguente schermata:

Figura 1.1. Protocollo non accettato

Se si definisce ADMIN_PROTOCOL nel seguente modo:

ADMIN_PROTOCOL = "https, http"

oppure

ADMIN_PROTOCOL = "*"

si ottiene l'accesso anche in semplice HTTP (o in qualunque protocollo nel secondo caso). Questo però mette a rischio la sicurezza del sito in quanto i dati vengono trasmessi in chiaro.

L'uso dell'HTTPS richiede lavoro aggiuntivo, in particolare richiede l'installazione di un server sicuro, cioè di un server web che supporti il protocollo HTTP over SSL.

Si noti inoltre che bifernoadmin deve essere installato sullo stesso computer dell'applicazione che si vuole amministrare. Questo potrebbe richiedere la coesistenza di due server (per i due protocolli, HTTPS e HTTP) sullo stesso computer, infatti spesso l'HTTPS risulta necessario unicamente per bifernoadmin.

Alla prima installazione Biferno inizializza la variabile ADMIN_PROTOCOL al valore: "https".

4.2. Controllo dell'IP di provenienza dell'accesso

Una volta verificato il protocollo, bifernoadmin controlla che l'indirizzo IP da cui proviene la richiesta sia compatibile con gli IP definiti nella variabile applicazione ADMIN_IP. Tale variabile, come le altre riguardanti bifernoadmin, è definita nel Biferno.config.bfr, come in:

ADMIN_IP = "195.136.128.10"

oppure

ADMIN_IP = "195.136.128.10, 192.128.137.*"

nel secondo esempio abbiamo abilitato tutti gli IP che cominciano per 192.128.137. più il singolo IP 195.136.128.10. Se si cerca di accedere bifernoadmin dall'IP 192.168.10.20 (che non è fra quelli abilitati) si ottiene la seguente schermata:

Figura 1.2. IP non accettato

In questo modo bifernoadmin si assicura di ricevere richieste solo dagli IP abilitati. Si tenga presente, in ogni caso, che alterazioni dell'IP di provenienza sono comunque possibili (anche se non banali) da parte di hacker male intenzionati.

In alcuni casi bisogna tener conto del fatto che l'IP di una certa macchina che si connette a bifernoadmin non è sempre lo stesso. Questo succede nel caso in cui l'IP viene assegnato dinamicamente (per esempio dal proprio ISP) ad ogni nuova connessione ad Internet. Se proprio non si può evitare questa situazione, si può essere costretti a definire una maschera per ADMIN_IP, come nel secondo esempio (eludendo però il controllo IP di bifernoadmin per una intera rete di utenti, il chè può essere pericoloso).

Inoltre, le richieste provenienti da organizzazioni che si connettono ad internet tramite un router vengono ricevute dal server web come se provenissero da un unico indirizzo IP. Abilitando quell'indirizzo IP si abilita in realtà l'intera organizzazione a superare il controllo all'accesso in bifernoadmin.

Biferno, alla prima installazione, inizializza ADMIN_IP al valore "" (stringa vuota) non consentendo così l'accesso da nessuna postazione.

4.3. Controllo della password

L'ultimo controllo che bifernoadmin esegue è quello della password. Se si sono superati i controlli di Protocollo e di IP, si accede alla finestra di login.

Figura 1.3. Finestra di login

La finestra ci richiede la password per entrare. Il servizio ci informa anche che Reference (a differenza degli altri tre strumenti di bifernoadmin) può essere consultato liberamente, senza inserire nessuna password. Si noti però che anche Reference richiederà la password qualora si tenti di modificare la documentazione non limitandosi alla semplice consultazione.

Il servizio ci informa anche che è necessario avere i cookie attivati nel nostro browser per poter accedere a bifernoadmin

La password digitata deve coincidere con quella definita nella variabile ADMIN_PASSWORD, come in:

ADMIN_PASSWORD = "mypassword"

Biferno, alla prima installazione, inizializza ADMIN_PASSWORD al valore "" (stringa vuota) non consentendo così l'accesso a nessuno.

Nota

Per non scrivere in chiaro la password nel file Biferno.config.bfr (il cui contenuto viene mostrato ogni volta che si accede ad Admin) si può scrivere la password stessa in un altro file, per esempio di nome passw.x.bfr (e leggibile solo dall'utente biferno) e poi inserire nel config la linea: ADMIN_PASSWORD = file("passw.x.bfr",,r).Get() Si noti che il file della password finisce con ".x.bfr", suffisso che ne impedisce la richiesta via WEB (si veda la nota "Protezione dei file" all'inizio del Cap.9 "Applicazioni" in "Biferno: Language Guide"). Ancora meglio sarebbe NON scrivere la password in chiaro (inserendo nel file, per esempio, il risultato della HTUUEncode() applicato alla password stessa) e inserire in Biferno.config.bfr la linea: ADMIN_PASSWORD = file("passw.x.bfr",,r).Get().HTUUDecode()

Se la password digitata non è corretta, ci viene mostrato il messaggio «Sorry, invalid password. Please try again.»

Finalmente, dopo aver completato la configurazione ed aver inserito la password corretta ci viene consentito l'accesso alla prima pagina di bifernoadmin.

NOTA IMPORTANTE

Dopo aver modificato le variabili: ADMIN_PROTOCOL, ADMIN_IP e ADMIN_PASSWORD è necessario eseguire un reload dell'applicazione per rendere effettive le modifiche, però, d'altra parte, non si ha ancora accesso a bifernoadmin per eseguire il reload. Il problema si può risolvere in due modi: Se stiamo configurando bifernoadmin per la prima volta saremo costretti ad eseguire un reload totale di Biferno usando un'altra modalità. Su Linux o MacOSX è sufficiente eseguire il comando da terminale (utente root): bifernoctl reload. Su Windows si deve selezionare dal menu «Biferno» dell'applicazione BifernoCtl la voce «Reload Biferno». Su MacOS Classic si deve premere il bottone «reload» della finestra di Biferno integrata nel web server (si consulti il documento «Biferno: Installation and Administration Guide» per i dettagli su questi comandi). Se l'applicazione che vogliamo amministrare è una sottoapplicazione di un'altra già configurata per bifernoadmin sarà sufficiente entrare nel bifernoadmin dell'applicazione superiore ed eseguire il reload di quella. Infatti in questo modo sarà eseguito il reload anche di tutte le applicazioni figlie, e dunque anche della nostra. In particolare si ricordi che tutte le applicazioni sono sottoapplicazioni dell'applicazione main, cioè quella contenuta in BifernoHome, quindi eseguire un reload (o un flush) sulla main equivale ad eseguirlo su tutte le applicazioni.

Una volta autenticati in bifernoadmin, automaticamente vieniamo riconosciuti da Biferno come se il nostro IP fosse fra quelli elencati nella variabile DEVELOPER_IP (si veda "Biferno: Language Guide" per i dettagli sul DEVELOPER_IP).

Riassumendo, il processo di autenticazione di bifernoadmin è pensato per evitare l'intrusione di utenti indesiderati. Tuttavia, grazie alla totale flessibilità delle impostazioni, esso lascia anche all'amministratore la possibilità di allentare la sicurezza per una gestione più comoda (ma meno sicura) degli strumenti di amministrazione.

Una volta autenticati si ha accesso alla sezione Admin. In alto a destra si trova il menu che permette la navigazione nelle differenti sezioni di bifernoadmin. Tale menu è presente in tutte e quattro le sezioni.

In alto a sinistra, in ogni sezione, viene stampata la versione di Biferno, un link al sito Tabasoft.it e il nome dell'applicazione che si sta amministrando.

Nella sezione Admin seguono alcune indicazioni sull'ambiente operativo, tra cui:

Nella pagina di Admin si trova anche una textarea per la gestione del file Biferno.config.bfr dell'applicazione. Sappiamo che il contenuto di questo file è fondamentale per gestire le preferenze della nostra applicazione e il suo codice viene eseguito solo al primo accesso all'applicazione. Nel caso della nostra semplice applicazione il file di config appare come nella seguente figura:

Figura 2.1. Editing del file Biferno.config.bfr

dopo aver eseguito l'editing del file è necessario premere il bottone «Save config and Reload» per rendere effettive le modifiche. Questa operazione salva il file di config e applica un reload all'applicazione per reinizializzarla con le preferenze appena modificate.

Premendo il bottone «Reload» viene eseguito il reload dell'applicazione. Questa operazione è indispensabile qualora si voglia rieseguire il processo di inizializzazione dell'applicazione stessa (cioè l'esecuzione del Biferno.config.bfr). Si noti anche che questa operazione azzera tutto ciò che è legato all'applicazione; per esempio azzera le variabili session degli utenti e svuota la cache dell'applicazione.

In particolare se si è modificato anche il Biferno.config.bfr nella textarea è necessario anche salvare il file premendo il bottone «Save config and Reload».

Tramite il bottone «Flush Cache» è possibile svuotare solamente la cache dell'applicazione. Si noti che questa operazione non ha alcun effetto se la cache non è attiva (cioè se la variabile CACHE dell'applicazione vale false).

Per i concetti di reload e flush si veda anche "Biferno: Language Guide"

	Nota
	Le operazioni di flush e reload vengono automaticamente invocate anche su tutte le sottoapplicazioni, elencate nel campo Children delle informazioni generali (vedi: Sezione 1, «Informazioni generali sull'Applicazione»).

Clickando sul link "Edit" si entra in una pagina con l'elenco dei file presenti nella prima directory dell'applicazione:

Figura 3.1. Edit

	Nota
	Nel caso dell'applicazione main la prima cartella mostrata da bifernoadmin non coincide sempre con quella dell'applicazione. Infatti in molti casi BifernoHome non è compresa nella radice del web server e quindi la sua pubblicazione potrebbe non essere desiderata. In questo caso viene mostrata, come radice dell'applicazione, la radice del web server.

Il menu in alto («Current directory») mostra la directory in cui si sta navigando.

Nella colonna di sinistra si ha invece l'elenco dei files e delle directory presenti nella cartella. Clickando sulla freccia è possibile lanciare lo script e vedere il risultato della sua esecuzione

Clickando sul nome di un file si accede ad una pagina in cui è possibile editare il contenuto del file. In particolare la pagina presenta in alto una serie di bottoni (che vedremo più avanti) e una o più textarea per l'editing del contenuto.

Figura 3.2. Modifica di un file

	Nota
	Se il file è protetto da scrittura un semplice testo non editabile verrà mostrato al posto della textarea.

Il bottone «Save file» permette di registrare su disco le modifiche eseguite.

Se il file in esame è una immagine, questa viene mostrata a video e non è possibile eseguire modifiche sul contenuto del file.

E' anche possibile selezionare un file (senza editarlo) per poter eseguire su di esso alcune operazioni. Per selezionare un file si può premere il bottone circolare accanto al nome del file stesso. In questo caso la textarea per la modifica del file non viene mostrata. La semplica selezione del file può essere utile quando si vogliono eseguire operazioni su file molto grandi evitando così il tempo di caricamento del contenuto nella textarea.

Dopo aver selezionato (o editato) un file, in testa alla pagina vengono mostrate alcune informazioni sul file stesso.

Figura 3.3. Info e operazioni su un file

In particolare viene mostrato il nome del file, la sua dimensione, la data di creazione e la data di ultima modifica (si noti che su Unix la data di creazione non è supportata).

Una serie di bottoni permettono anche di eseguire alcune operazioni sul file:

Trash file: premendo questo bottone viene mostrato all'utente un messaggio per richiedere la conferma dell'operazione («Si vuole veramente spostare il file nel cestino?»). Se l'operazione viene confermata il file viene spostato nella cartella «bfedit_trash» (il cestino). Questa cartella viene creata allo stesso livello del file la prima volta che si esegue un'operazione di questo tipo. Quando si esegue "Trash file" su un file ed esiste già un file con lo stesso nome nel cestino, quest'ultimo viene definitivamente cancellato e il primo lo sostituisce.

Una volta creata la cartella «bfedit_trash» è possibile svuotare il cestino accedendo a tale cartella e premendo il bottone «Empty Trash».

Delete file: con questo bottone si cancella definitivamente il file (prima di eseguire l'operazione viene richiesta comunque una ulteriore conferma).

Move File: questo bottone ci porta ad una pagina in cui possiamo specificare un nuovo path per il file.

Figura 3.4. Spostare un file

Premendo, in questa pagina, il bottone «Move File» il file viene effettivamente spostato nella nuova posizione. Non è possibile muovere file in una cartella di livello superiore a quella dell'applicazione.

E' necessario avere i permessi di scrittura nella cartella di destinazione, altrimenti si riceverà un messaggio di errore.

Rename file: con questa funzione possiamo rinominare il file (una pagina successiva ci richiede il nuovo nome)

Download file: questa funzione permette di scaricare sul proprio disco il contenuto del file.

I primi due bottoni nella parte superiore della pagina permettono di creare un nuovo file e di caricare sul server un file dal nostro computer (upload).

Il bottone «New File» ci permette di creare un file vuoto nella cartella corrente. Una pagina successiva ci richiede il nome del file e, una volta creato, esso può essere editato sfruttando la funzione di modifica descritta in: Sezione 1, «Editing dei file».

Il bottone «Upload file» ci permette di caricare sul server un file presente sulla propria macchina. Una pagina successiva ci richiede di selezionare il file. Il file selezionato viene poi caricato nella directory corrente e può essere a sua volta modificato sfruttando la funzione di modifica descritta in: Sezione 1, «Editing dei file».

Se si clicka su una delle sottocartelle si possono editare i files in essa contenuti. Il menu in alto permette il ritorno alla cartella superiore (si noti che non è possibile, per motivi di sicurezza, visitare le directory al di sopra di quella della nostra applicazione).

Due bottoni nella parte superiore della pagina ci permettono di eseguire operazioni sulle directory.

New directory: permette la creazione di una directory nella cartella corrente (biferno deve avere il permesso di scrittura nella directory)

Figura 3.5. Creazione di una directory

Delete current directory: premendo questo bottone viene cancellata la directory corrente. Questa operazione va a buon fine solo se la directory è vuota. Si noti che su alcuni sistemi le cartelle possono sembrare vuote se esaminate con Edit; in realtà possono ancora contenere file invisibili (per esempio file che iniziano per '.'). Su Unix, per esempio, si possono esaminare tali file usando il comando di terminale: ls -la

Per creare una sottoapplicazione è sufficiente creare una nuova cartella (se non esiste già) e accedere al suo contenuto. In alto apparirà la seguente linea:

Figura 3.6. Form per la creazione di una sottoapplicazione

Dopo aver inserito il nome dell'applicazione e premuto il bottone "Make this folder a new App" verrà mostrata la finestra di login della nuova applicazione. E' dunque necessario reinserire la password (identica a quella dell'applicazione madre) per accedere al bifernoadmin della nuova applicazione. Infatti tutte le variabili della applicazione appena creata (compresa la password) vengono ereditate dalla applicazione madre.

Se invece si accede ad una sottodirectory che contiene già una sottoapplicazione viene mostrata la seguente schermata:

Figura 3.7. Navigazione di una sottoapplicazione

per navigare nella cartella è allora necessario accedere al bifernoadmin della sottoapplicazione, la cui url viene presentata nel messaggio che sostituisce la lista dei files.

Edit consente di personalizzare alcune impostazioni. Premendo il bottone in alto a destra ("Preferences...") si aprono alcune finestre per la definizione delle preferenze. Vediamole di seguito.

E' possibile definire, nella sezione «File filter» come Edit deve mostrare i file in base al suffisso del loro nome.

Figura 3.8. Filtro sui file

Se si fornisce il suffisso *, la lista di Edit mostra tutti i tipi di file, altrimenti solo quelli che hanno un suffisso fra quelli dichiarati. Se si marca il bottone «Show not editable files» i file con suffisso diverso da quelli previsti sono mostrati nella lista ma non sono editabili (altrimenti tali file non vengono mostrati affatto).

Per rendere effettive le modifiche, in questa e nella successiva sezione, è necessario premere il bottone "ok"

Nella sezione «Icons settings» è possibile definire la grandezza delle icone mostrate per ogni file nella lista.

Figura 3.9. Impostazioni per le icone

Se il file è una immagine (di tipo gif o jpeg) si può opzionalmente mostrare la miniatura (thumb) dell'immagine nella lista dei files. In questo caso è possibile definire anche la larghezza e la altezza delle miniature stesse.

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

	Nota
	Solo le classi e funzioni utente di scope application vengono mostrate in Reference, quelle di scope local non vengono mai mostrate (si veda "Biferno: Language Guide" per il concetto di scope delle classi e delle funzioni).

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.

	Nota
	Solo le pagine Man di classi e funzioni aggiunte dall'utente (in C o Biferno) possono essere modificate. Tutte le pagine Man delle classi e funzioni comprese nella distribuzione di partenza di Biferno non possono essere modificate.

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.

	Nota
	Nelle versioni di Biferno precedenti alla 1.1 la dichiarazione di DTD era: <!DOCTYPE bifdoc SYSTEM "../bifdoc.dtd"> . Questa assumeva (erroneamente) che il file di DTD fosse sempre nella directory superiore rispetto a quella del file di documentazione (questo non è sempre vero).

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

L'ultima sezione di bifernoadmin riguarda la cache dell'applicazione. Il meccanismo di cache è spiegato nel Cap. 22 del manuale del linguaggio: "Gestione della Cache". Cache è utile solo se la variabile application CACHE vale true, cioè se la cache è attiva. In questo caso elenca tutti i file in essa contenuti, come nella figura seguente.

Figura 5.1. Cache

In questa schermata vediamo anche il numero totale dei files («Total pages in Cache») e la dimensione totale di tutti i file («Cache total size», espressa in Kilobytes). E' possibile visualizzare anche alcune grandezze legate ai file stessi e ordinarle in maniera ascendente o discendente.

In particolare è possibile visualizzare le seguenti grandezze:

	Nota
	Tutte queste grandezze sono relative all'intervallo di tempo compreso fra l'ultimo reload o flush dell'applicazione e il momento presente, non sono quindi delle reali statistiche ma danno solo un'idea dell'andamento dell'applicazione in un dato momento.

E' possibile anche esaminare il dettaglio di tutte le grandezze per un determinato file clickando sul nome del file. In questo caso ci viene mostrata una finestra con i dati relativi al singolo file.

Figura 5.2. Cache: dati relativi al singolo file

E' possibile eseguire un flush totale della cache premendo il bottone «Flush All». Questa operazione è analoga a quella vista in: Sezione 3, «Reload e Flush Cache».

E' anche possibile scaricare dalla cache uno o più file selezionando i file dal bottone nella colonna di destra e premendo il bottone «Flush Checked»