Chapter 4. Reference
Prev   Next

Chapter 4. Reference

Table of Contents

1. Online Documentation
2. Creating New Online Documentation for Classes and Functions.
3. Structure of the Documentation File
4. Documentation file and validation

1. Online Documentation

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.

Figure 4.1. An Example of Online Documentation (folder class)

An Example of Online Documentation (folder class)

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 application scope are displayed in “Reference”. User classes and functions with local scope are never shown (see “Biferno: Language Guide” for the concept of class and function scope).

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.

2. Creating New Online Documentation for Classes and Functions.

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:

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.

3. Structure of the Documentation File

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 user

    A link to the Walk method of the folder class can be specified as: 

    <link linkend="method.folder.Walk">folder.Walk</link>

    A link to the folder class can be specified as: 

    <link linkend="class.folder">class folder</link>

    A link to the Eval function 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 linkend tag, 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 BfrMan folder (if it does not exist) in the location of the .bfr where the class (or function) is declared. Copy the documentation folder in the BfrMan folder.

  • If the documentation is for a predefined class or function, copy the documentation folder in the Man2 folder in the BifernoHome folder.

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.

4. Documentation file and validation

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: <!DOCTYPE bifdoc SYSTEM "../bifdoc.dtd"> and assumed that the dtd file was always located in the document parent directory (this is not always true).

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

Prev   Next
Chapter 3. Edit Home Chapter 5. Cache