Administering Biferno via the Web
Copyright © 2003 Tabasoft S.a.s.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled Appendix 1, GNU Free Documentation License.
Table of Contents
List of Figures
- 1.1. Access protocol refused.
- 1.2. IP refused.
- 1.3. login window.
- 2.1. Editing the
Biferno.config.bfrfile - 3.1. Edit
- 3.2. Modifying a File
- 3.3. File Info and Operations
- 3.4. Moving a File
- 3.5. Creating a New Directory
- 3.6. Creation Form for a New Subapplication
- 3.7. Navigating a Subapplication
- 3.8. File Filer
- 3.9. Icons Settings
- 4.1. An Example of Online Documentation (folder class)
- 4.2. The Biferno Documentation DTD
- 5.1. Cache
- 5.2. Cache: Data Relative to a Single File
Table of Contents
bifernoadmin is a Web-based service that allows the remote administration and management of a Biferno application. The bifernoadmin interface can be accessed from any Web browser. Bifernoadmin itself is an application entirely written in the Biferno language.
The concept of application in Biferno is described in "Biferno: Language Guide". We assume that the reader is in general terms familiar with the general design principles of the Biferno system and of Biferno applications as described in the document above, which can be downloaded from the www.biferno.it site.
bifernoadmin is part of the standard installation of the Biferno
software, but can not be accessed until it is configured as described in
Section 4, “Configuration and Security Notes”. The bifernoadmin application is located in a
folder called bifernoadmin. This folder contains all
scripts implementing the functionality of the service.
The bifernoadmin folder can be found in the
BifernoHome folder of the machine where Biferno has
been installed.
![[Note]](stylesheet-images/note.png) | What is BifernoHome? |
|---|---|
On all operating systems the path of the
|
bifernoadmin for a particular application can be accessed by accessing
the URL of the folder containing that application followed by the string
bifernoadmin/index.bfr.
The following URL will allow to administer the application contained in
the MyApplication folder in the
www.mysite.com site:
https://www.mysite.com/MyApplication/bifernoadmin/index.bfr
The index.bfr string can be omitted if the
DirectoryIndex directive has been set correctly for the
Web server by specifying a filename of index.bfr as one
of the alternatives that the Web server should use when a URL specifies only
a directory.
The use of the HTTPS protocol instead of
HTTP is covered in Section 4, “Configuration and Security Notes”.
Notice that there is no bifernoadmin folder in the
MyApplication folder. Instead, the
bifernoadmin folder is in
BifernoHome. The trick here is that Biferno
automatically intercepts all URLs containing the
bifernoadmin string and redirects them to
[BifernoHome]/bifernoadmin/index.bfr. This mechanism
allows avoiding to replicate the bifernoadmin folder in
every application, which would be a waste of disk space and, more
importantly, a code maintenance nightmare.
For this reason the bifernoadmin string is a
Biferno reserved word and cannot be used to name our scripts or folders
containing our scripts.
bifernoadmin provides four fundamental tools:
Admin (see Chapter 2, Admin) allows to modify the application preferences and to execute a flush (cache flushing) or reload (reinitialization) of the application itself (see "Biferno: Language Guide" for an explanation of the flush and reload operations.
Edit (see Chapter 3, Edit) is used to read and modify application files allowing to add and correct the scripts that implement the application.
Reference (see Chapter 4, Reference) provides online documentation for all Biferno classes and functions, and allows to write documentation for user classes and functions.
Cache (see Chapter 5, Cache) supports cache management, allows to delete individual files from the application cache and to browse through the latest file access statistics.
All these tools are described in detail in the rest of this document.
Access to bifernoadmin should be reserved to the application developer or the system administrator to avoid intrusion and possible damage. A malicious user could e.g. execute a reload of the application at an inappropriate moment or, in the worst scenario, modify files on our site using the editing functionality. Security should be a concern, and this section dwells on the protection mechanisms that the bifernoadmin offers, and on the various settings that influence the security policy of bifernoadmin.
To ensure adequate protection bifernoadmin works on three separate levels.
Even before verifying the user identity, bifernoadmin compares the
protocol used by the request with the list of allowed protocols. Allowed
protocols are listed in the ADMIN_PROTOCOL application
variable defined in the Biferno.config.bfr file for
the application at hand, as in:
ADMIN_PROTOCOL = "https"
With the above value for ADMIN_PROTOCOL, the only
allowed protocol is HTTPS (Secure HTTP, an
implementation of HTTP over SSL, the Secure Socket Layer). In the HTTPS
protocol data is encrypted before transmission between a browser and a Web
server, which makes it more difficult to intercept or alter data in transit.
HTTPS is more secure than plain HTTP.
If the application configuration is such that HTTPS is the only protocol allowed and an attempt to connect to bifernoadmin via plain HTTP is made, the following screen is displayed:
If ADMIN_PROTOCOL is defined as:
ADMIN_PROTOCOL = "https, http"
or
ADMIN_PROTOCOL = "*"
access via plain HTTP (or via any protocol in the last case) is allowed. Notice that this is a security risk, because data (including password) are transmitted in clear.
The use of HTTPS requires some additional work on the system administration side for the configuration of a secure Web server (i.e. a Web server supporting HTTPS).
Notice that bifernoadmin must be installed on the same machine as the application to be managed. This may require the presence of both an HTTP and an HTTPS server on the same machine if the HTTPS protocol is used only for application management via bifernoadmin.
When first installed, Biferno initializes the
ADMIN_PROTOCOL variable to the
"https" value.
Once it has been established that an access attempt is using an allowed
protocol, bifernoadmin verifies that the IP address originating the request
is within the IP range defined in the ADMIN_IP application
variable. This variable, defined in Biferno.config.bfr
as all variables controlling bifernoadmin configuration, should be set to
an IP address, as in:
ADMIN_IP = "195.136.128.10"
or and IP address range, as in:
ADMIN_IP = "195.136.128.10, 192.128.137.*"
The second example allows access originating from all IP addresses where the first three octets are 192, 128, and 137 respectively, plus the single IP address 195.136.128.10. If an access attempt is made from the unauthorized IP 192.168.10.20, the following error screen is displayed:
Using this mechanism, bifernoadmin will accept only connection requests originating from authorized IP. This will work as long as the IP source address in incoming IP packets is not maliciously altered, which is not trivial but could possibly be done by a malicious attacker using host impersonation techniques.
In some cases one must take into account that the IP address of a
machine that needs to connect to bifernoadmin for application management
purposes may change over time. This happens e.g. when the machine connects
to the Internet via an ISP that dynamically assigns the machine a new IP
address at every connection. If it is really necessary to access
bifernoadmin from a machine that can not be assigned a static IP address,
one may have to define an IP range for ADMIN_IP as the
second example above. This allows an entire subnet to connect to
bifernoadmin, which is a security risk.
Finally, notice that connection requests from within a network that is connected to the Internet via a router that uses NAT (Network Address Translation) will appear to the Web server as originating from the router's IP. Enabling access from the router's IP is equivalent to enable access from the entire network "hidden" behind the router and allows any machine behind the router to bypass the IP source check done by bifernoadmin.
When first installed, Biferno initializes the ADMIN_IP
variable to the "" (empty string), which
does not allow access from any IP.
The last check performed by bifernoadmin is the password check. If the protocol and source IP checks have been passed, the login window is displayed.
Password input is requested to proceed, and a link is provided to the Biferno Reference service, which is the only bifernoadmin service that has is not password-restricted and is available for all users (nevertheless Reference will request input of the bifernoadmin password to allow modification of the documentation).
The service also reminds us that is is necessary to enable cookies in our browser to access bifernoadmin.
The requested password is the one defined in the
ADMIN_PASSWORD variable, e.g.:
ADMIN_PASSWORD = "mypassword"
When first installed, Biferno initializes the
ADMIN_PASSWORD variable to the
"" (empty string) value, which does not
allow access to anybody.
| Note |
|---|---|
From a security point of view, it is a good idea to avoid writing the password
in clear text in the
ADMIN_PASSWORD = file("passw.x.bfr",,r).Get()
Notice the
Even better is to base-64 encode the password in the password file (e.g. by
writing in the password file the result of the
ADMIN_PASSWORD = file("passw.x.bfr",,r).Get().HTUUDecode()
|
If we digit the wrong password, the “Sorry, invalid password. Please try again.” message is displayed.
Finally, after eventually modifying ADMIN_PASSWORD and
providing the correct password, we can access the first bifernoadmin
page.
![[Important]](stylesheet-images/important.png) | Important Note |
|---|---|
After modifying either the There are two ways to go around this:
|
Once authenticated in bifernoadmin, we are automatically seen by
Biferno as if our IP address would be among those defined by the
DEVELOPER_IP variable (see "Biferno: Language Guide" for details on
DEVELOPER_IP).
In summary, the bifernoadmin authentication process has the goal of preventing intruders from accessing the remote application management facilities provided by the bifernoadmin application. It is up to the system administrator to choose the appropriate trade-off between enforced level of security and ease-of-use in compliance with the site security policy.
Table of Contents
Once authenticated, the administrator has access to the Admin section. In the upper right corner we find the menu that allows navigation through the different sections of bifernoadmin. This menu is visible in all sections.
In the upper left corner and in each section, we find the Biferno version, a link to the Tabasoft.it site and the name of the application we are managing.
The Admin section provides some information on the operating environment:
System: The system on which Biferno is running, e.g.
Unix: 6.6 Darwin Kernel Version 6.6: Thu May 1 21:48:54 PDT 2003; Power Macintosh powerpcVersion: The version of Biferno running on this computer, e.g.
1.0. Clicking on "check updates" allows to check for newer versions downloadable from Tabasoft web site.WebServer: The Web server we are using, e.g.
Apache/1.3.27 (Darwin)BifernoHome: The path to the
BifernoHomefolder, e.g.file://Users/BifernoHome/Base Path: The application base path, i.e. the folder that contains the application, e.g
file://Library/WebServer/Documents/MyApplication/Web Path: The base URL to reach the application, e.g.
http://www.mysite.com/MyApplication/Up Since: The date of the most recent startup of Biferno, e.g.
14-05-2003 11:23:31Children: The subapplication of the application we are managing (see "Biferno: Language Guide" for the subapplication concept), e.g.
MySubApp1, MySubApp2
In the Admin page we find a
textarea to manage the
Biferno.config.bfr file for the application. This file
is used to manage application preferences and its code is loaded the only
first time the application is accessed. In the case of our simple
application the configuration file looks like this:
After editing the file remember to click the “Save config and Reload” button to make your modifications effective. This operation saves the new content of the configuration file and executes an application reload to reinitialize the application with the new preferences.
Clicking the “Reload” button executes a reload of the
application. This operation is necessary when one wants to execute again the
application initialization process, i.e. the loading and executing of the
Biferno.config.bfr file. Notice that an application
reload initializes all elements of an application, including session and
user variables, and flushing the application cache.
Every time the Biferno.config.bfr file is modified
in the textarea, it is necessary to save the file clicking on the
“Save config and Reload” button (it is not enough to click on
the “Reload” button, because our modifications have not been
saved to disk).
The “Flush Cache” button allows to flush only the
application cache. Notice that this operation has no effect if the cache has
been disabled by setting the CACHE application variable to
false.
The Biferno reload and flush operations are discussed in "Biferno: Language Guide".
| Note |
|---|---|
The flush and reload operation of an application implies an automatic flush and reload of all subapplications listed in the Children field in the application information page (see Section 1, “Application Information”). |
Table of Contents
Clicking on the "Edit" link takes us to a page showing the files located in the top-level directory of the application:
| Note |
|---|---|
In the case of the main application, the first folder displayed by
bifernoadmin my not coincide with the top-level application folder. The
reason is that the top-level application folder for the main application is
|
The menu on the top (“Current directory”) shows the directory we are navigating.
The left column displays a listing of the files and directories in the folder. Clicking on the arrow next to a script filename will launch the script and display the result of its execution.
Clicking on a file name brings up a page that allows to edit the file content. The page has a textarea to edit the file and a number of buttons that will be described in the following.
| Note |
|---|---|
If the file is write-protected, a simple non-editable text is shown instead of the textarea. |
The “Save file” button allows to save changes to disk.
If the file is an image, the image is displayed and no editing operations can be performed.
In addition to editing, a file can also be selected for further processing. To select a file, click on the round button next to the file name. This does not display the textarea for editing the file content. The plain selection of a file can be useful for very large files to avoid the delay due to the loading of a large file into the textarea.
After selecting or editing a file, the top of the page will contain some information on the file itself.
The name of the file is displayed, along with its size, creation date and date of the last modification (notice that the file creation date is not supported on Unix).
A row of buttons allows to perform the following operations on the file:
- Trash file
Clicking on this button displays a message requesting confirmation from the user (“Do you really want to move this file to trash?”). If the operation is confirmed, the file is moved to the “bfedit_trash” folder, i.e. the trash. This folder is created in the same location as the file the first time this kind of operation is executed. If you trash a file, and a file with the same name was already in the trash, the latter will definitively lost and replaced by the new file.
Once the “bfedit_trash” folder is created, the trash can be emptied by accessing the trash folder and clicking on the “Empty Trash” button.
- Delete file
This button requests a confirmation and, if the confirmation is positive, immediately deletes the file from disk.
- Move File
This button displays a page where we can specify a new location for the file.
When the “Move File” button is clicked on this page, the file is moved to the new location. Files can not be moved to a directory that is above the folder of the application they belong to.
It is necessary to have write permissions for the destination folder, or an error will be returned.
- Rename File
This button displays a page that allows to change the name of the file.
- Download File
This button allows to save a copy of the content of the file to disk on the machine where the browser is running.
The first two buttons in the upper part of the page (see Figure 3.1, “Edit”) allow to create a new file and upload a file from our machine onto the server.
The “New File” button allows to create a new (empty) file in the current folder. The new file, once created, can be edited using the editing procedure described in Section 1, “File Editing”.
The “Upload file” button allows to upload a file from our machine onto the server. Once selected, the file is uploaded on the server in the current directory and can be modified using the editing procedure described in Section 1, “File Editing”.
The files contained in a subdirectory can be reached and then edited by clicking on the subdirectory icon. The menu at the top allows to return to the parent directory. For security reasons, bifernoadmin will not allow browsing directories located above the folder of our application.
Two buttons in the upper portion of the page implement operations on directories:
- New directory
This button allows to create a directory in the current folder (write permissions for the
bifernouser for the current directory are necessary).- Delete current directory
This button deletes the current directory only if the current directory is empty. Notice that on some platforms a directory will seem empty when examined with Edit even if it contains hidden files (e.g. files starting with a period (
'.'under Unix). Hidden files under Unix can be displayed using the ls -la command from a terminal window.
To create a subapplication it is sufficient to create a new folder (if it does not exist already) and to access its content. The top portion of the window will show the following line:
After inserting the name of the application and pressing the “Make this folder a new App” button, the login window of the new application will be displayed. At this point, supply the same password of the parent application to manage the new subapplication using bifernoadmin. The password of the parent application will work because the new applications inherits all variables defined in the parent application, including the password.
The following screen is displayed when accessing a subdirectory that already contains a subapplication:
To navigate the folder, access the bifernoadmin interface for the subapplication by clicking on the link provided where the file listing would normally appear.
Edit allows the personalization of several preferences. Clicking the “Preferences…” button in the top right corner opens the editing preferences window.
The “File filter” tab allows to specify how Edit should filter files to display based on their suffix.
The * star character tells
Edit to display all files on disk, while a list of
suffixes tells Edit to display only files with a listed
suffix. If the “Show not editable files” button is checked,
files with a suffix which does not appear in the list, which are normally
not displayed, will be displayed by Edit, but cannot be
edited.
To make the modifications effective, click on the “Ok” button.
The “Icons settings” tab allows to specify the size of the icon displayed for each file in the listing.
If the file is an image in gif or
jpeg format the thumbnail for the image can be optionally
shown in the file listing along with the image. With this option, the width
and height of the thumbnails can be also specified.
Table of Contents
The reference section displays the online reference guide for Biferno and for user-defined classes and functions. The “Reference On Line” available on www.biferno.it is a simplified version of the bifernoadmin Reference section.
The left column lists all predefined classes (under “Predefined Classes”), followed by user-defined classes (under “Application Classes”), i.e. classes implemented in the Biferno language and loaded in the current application. Clicking on the “Functions” link (at the bottom of the class listing) a page is displayed with the list of all predefined functions (“Predefined Functions”) followed by user-defined functions (“Application Functions”).
| Note |
|---|---|
Only user classes and functions with
|
Clicking on the name of a class the documentation of the class is displayed. In the right portion of the window four columns are shown containing:
The class methods
The class properties
The constants defined by the class
The errors defined by the class (if any)
The first page also documents the meaning and goal of the class and its constructor. For the class the following documentation fields are displayed:
- Purpose
The goal and functionality of the class.
- Notes
Any kind of additional information.
- See Also
Related information, in particular other class documentation that may help the reader.
- Implementation
The kind of implementation. As of the time of this writing, a class (or method, property, etc.) can be written in C, as all predefined methods are, or in Biferno, as application methods.
Following the class information above, the class constructor documentation is displayed. The following documentation fields are shown for the class constructor:
- Purpose
The rationale for the constructor.
- Description
A generic description for the constructor.
- Parameters
The list of constructor parameters and their description.
- Returns
A description of the return value of the constructor.
- Errors
The errors that the constructor may cause.
- Notes
Any kind of additional information.
- See Also
Related information, in particular other methods that may help the reader.
- Implementation
The kind of implementation. (see above).
Finally, the prototype of the constructor itself is shown.
Clicking on a method, property, constant or error the relative documentation is accessed. The following documentation fields are shown on every page (the following discussion on methods applies as well to the case of properties, constants and errors unless specifically stated otherwise):
- Purpose
The rationale for the method.
- Description
A generic description for the method.
- Parameters
The list of method parameters and their description (this field is not present for properties, constants and errors).
- Returns
A description of the return value of the method.
- Errors
The errors that the method may cause.
- Notes
Any kind of additional information.
- See Also
Related information, in particular other methods that may help the reader.
- Implementation
The kind of implementation. (see above).
The documentations of functions is similar to the documentation of methods for individual classes.
Each documentation page contains a link (“Update Man Page”) that allows to modify the documentation itself. Accessing this password-protected page the content of all documentation fields can be modified.
| Note |
|---|---|
Only man pages of classes and functions added (in C or Biferno) by the user can be modified. All man pages of classes and functions comprises in the Biferno distribution cannot be modified |
The bottom portion of the page displays a preview of the modified documentation page as it will appear to users.
The text of the documentation should be input in the appropriate fields observing the following rules:
No HTML tags are allowed in the text.
Several XML tags are allowed in the text (see Section 3, “Structure of the Documentation File”).
Characters with accents can be inserted.
After filling the input text fields, press the “Modify Man Page” button to send data to “Reference”, which will combine them in a single documentation file. This file constitutes the fundamental structure for the reference guide and is opened by Biferno when the documentation of a given method, function, property, constant, error or class is requested.
Each documentation file documents one of the following Biferno documentation units:
A class method
A class property
A class constant
A class error
A function
A class and its constructor
If one writes his own class (or method, etc.), this file has to be distributed along with the implementation of the class to allow users to browse the online documentation of one's “Reference”service.
The documentation file is stored in XML format, but no XML skills are required for the user to edit the file because the internal structure is hidden by Biferno. The following paragraph explains the structure of the documentation file to allow expert users to have additional control on the formatting of documentation fields.
The documentation file created by Biferno (Biferno man page) is an XML text file that complies to a DTD (Document Type Definition) defined by Biferno. For the interested reader, the current version of the DTD is shown in Figure 4.2, “The Biferno Documentation DTD”.
The user editing the documentation does not need to worry about the tags defined by the DTD, because Biferno automatically builds the XML file using the text inserted by the user in the documentation fields on the bifernoadmin page.
The following XML tags can be used within documentation fields to have more control on the structure of the documentation itself:
tag par: To define paragraphs, e.g.:
<par>this is a new paragraph</par>The entire text for a documentation field has to be enclosed in a
<par></par>pair. In practice, the user does not need to input this outer tag pair because “Reference” will automatically add a<par>tag before and a</par>tag after the text of a documentation field if those are not present.tag code: To define a code block to be displayed outside of the main text, e.g.:
<code>a = 5</code>The code will be displayed in a separate text block.
tag inlinecode: To define inline code, i.e. code to be displayed within the main text, as in:
<inlinecode>a = 5</inlinecode>The code will not be displayed in a separate text block, but rather be shown inline.
tag link: To define a link to other documentation elements or to an Internet resource. The syntax is:
<link linkend="[type].[class].[name]">[text of link]</link>where:
[type]= method | property | constant | error | class | function[class]= name of the class, or “function” if we are referencing a function[name]= name of the property (or method, etc.) that we want to link to (optional for a link to a class)[text of link]= the link text to be made visible to the userA link to the
Walkmethod of thefolderclass can be specified as:<link linkend="method.folder.Walk">folder.Walk</link>A link to the
folderclass can be specified as:<link linkend="class.folder">class folder</link>A link to the
Evalfunction can be specified as:<link linkend="function.Eval">function Eval</link>Finally, to insert a link to an Internet site (e.g. www.tabasoft.it) we can write:
<link linkend="http://www.tabasoft.it">a link to www.tabasoft.it</link>In this case the complete URL must be used within the
linkendtag, including the "http://" string.
Other tags allowed by the DTD should not be inserted manually because this may break the assembling of the XML file that is automatically executed by “Reference”.
The XML source generated by “Reference” can be displayed clicking the “Show Man File” link. Additionally, the “Show Man XML” link will display the XML file as processed by the browser software we are using. This can be useful if our browser supports XML validation to verify the validity of the tags we have inserted in the text.
It is in principle possible for an expert user to directly write or edit the XML source using a text editor starting from the structure of the Biferno DTD:
Figure 4.2. The Biferno Documentation DTD
<?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)>
Once editing is completed, the file should be copied in a folder with
the same name as the class to which the method, property, constant or error
belongs. For a function, the folder should be called
function. For the documentation of a class, the folder
should have the same name as the class. The folder should then be copied in
one of the following two locations:
If the documentation is for an application class (or function), create the
BfrManfolder (if it does not exist) in the location of the.bfrwhere the class (or function) is declared. Copy the documentation folder in theBfrManfolder.If the documentation is for a predefined class or function, copy the documentation folder in the
Man2folder in theBifernoHomefolder.
If in doubt on the correct location, use “Reference” to generate a test documentation and verify where the XML file has been stored on disk.
This is an example of a documentation file (the method IsDate of string class):
<?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>
The second line is the DTD declaration. The DTD file is on line (tabasoft web site).
Reference executes xml validation every time a page is modified (button "Modify Man Page" of section "Update Man Page") and only if the Biferno extension xml_bfr is available. Although, if a user is not connected to the web he can continue to modify pages, as he ignores the warning notes ("no DTD found!"). He will check the validity of their pages saving them again later, with a valid web connection.
| Note |
|---|---|
This is fixed from Biferno version 1.1. Before the declaration was:
|
The following files are also included by the DTD:
iso-lat1.ent
iso-lat2.ent
iso-num.ent
iso-pub.ent
but this should be transparent to users since they are located in the same folder: http://www.tabasoft.it/biferno/bfdocdtd
Table of Contents
The last bifernoadmin section deals with the application cache. The
Biferno cache mechanism is explained in "Biferno: Language Guide".
“Cache” is useful only if the CACHE application
variable is set to true, i.e. if the cache is active.
When this is the case, “Cache” lists all files contained in the
application cache, as in the following figure.
This screen shows the total number of files (“Total pages in Cache”) and the total size of all files in cache (“Cache total size”, expresses in Kilobytes). There is also some more information on the files in cache that can be displayed and sorted in ascending or descending order. The following data can be visualized:
Current Users: The number of users that are currently running the script
Hits: How many times the script has been run
Last Access: The date of the last execution of the script
Last (ms): The execution time (in milliseconds) required by the script for its last run
Max (ms): The maximum execution time (in milliseconds) required by the script
Min (ms): The minimum execution time (in milliseconds) required by the script
Average (ms): The average execution time (in milliseconds) required by the script
Total (ms): The total execution time (in milliseconds) required by all executions of the script
| Note |
|---|---|
All the above measures are relative to the time interval between the last reload or flush of the application and the time of the query. Rather than as statistics, they should be regarded as a snapshot of the recent behavior of the application. |
Detailed information on the measures for a given file can be displayed by clicking on the file name. This brings up a window with data relative to that file only.
The entire cache can be flushed clicking on the “Flush All” button. This operation is similar to the one described in Section 3, “Cache Reload and Flush”.
Individual files can be flushed from the cache by checking the button in the “Flush” column (see Figure 5.1, “Cache”) and clicking on the “Flush Checked” button.
GNU Free Documentation License Version 1.2, November 2002 Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 0. PREAMBLE The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. 1. APPLICABILITY AND DEFINITIONS This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law. A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none. The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words. A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque". Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only. The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition. The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License. 2. VERBATIM COPYING You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. 3. COPYING IN QUANTITY If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. 4. MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement. C. State on the Title page the name of the publisher of the Modified Version, as the publisher. D. Preserve all the copyright notices of the Document. E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. H. Include an unaltered copy of this License. I. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. K. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. M. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version. N. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section. O. Preserve any Warranty Disclaimers. If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. 5. COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements". 6. COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. 7. AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate. 8. TRANSLATION Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail. If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title. 9. TERMINATION You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 10. FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/. Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.