No dependencies.

Introduction

The SERi [1] server is heavily based on modules, and when making SER's configuration file seri [2].cfg, easy access to the documentation for these modules is important when working with the configuration language.

A good help during this work is “Module documentation”^{1 [3]}. This online module documentation is auto-generated every night based on the SER Ottendorf documentation source. It makes it always up-to-date and ensures that all modules-documentation is available to users.

It might however be inconvenient to browse through this static pages, so this document outlines the functionality of a search-page for this module documentation, enabling fast access to specific documentation items without the need to browse through many pages.

It could be hosted by iptel.org, e.g. under http://www.iptel.org/views/moduledocs/search. [4]

Overview

The search-page is composed of two elements placed on the one www page. This elements are:

• integrated with column's hearers searching forms panel that has following form fields

• Version of SER – single selection field;

• Module – single selection field;

• Type of entity – the set of four checkboxes;

• name of entity – some text field;

• and returned table;

   

The exemplary screenshot of these components is shown in the figure 1.

[5]

Figure 1. An exemplary view of the returned table with integrated searching form panel (the precise appearance (colors, styles, font types, etc) will depend on the page style and will be controlled by a CSS style sheet)

Note that the content of the table always depends on the selections made in the searching forms panel. This content changes on-the-fly after:

• selecting SER version;

• selecting module's name;

• checking or unchecking entities' types (F, R, P, S checkboxes);

• typing an entity's name (after each typed keyboard-key the records shown in the documentation table will be matched with the text fields' content);

Notes:

• At given point, the returned table may contain maximally 20 records. Indexes presented below the table may be used to paginate.

• Clicking on the columns' headers (version, module, entity's type, entity's name) causes the table sorting (note that after resorting the first page of the table will be displayed).

• Clicking on the “documentation” links redirects user browser to proper documentation pages.

• If users are unable to find information they are looking for by following specified links they can report that requesteed documentation is missing or insufficient. To do this, they have click on the “Report” link in the “Insufficient documentation” column. After that the new text box will appear. A user may write some details or comments (if documentation is missing or only insufficient, what is wrong there, etc) and send it to iptel.org by clicking send button bellow the text box.
  After clicking the “Send” button some message informing the the request was send will be displayed. Reporting a missing documentation will not affect selections made in the searching forms panel. Also the table's content remains unchanged.

The documentation is generated by the Ottendorf “module-docs” (it will be just loaded from the http://www.iptel.org/views/moduledocs [6] documentation directory). The present location of the documentation files need not be changed.

Constraints

The search-module described here is an example of a service that belongs to so-called second generation of Web-based services (Web 2.0). Web 2.0 imposes some constrains on the client's software. Note that a user's browser should have JavaScript enabled. Depending on the “technology” that will by used to construct the search-module it is expected that at least following browsers will be supported for sure:

• Internet Explorer (>5.5, Available Active X);

• Firefox (JavaScript available);

• Opera (JavaScript available);

A complete list of supported browsers will be given in the Technical Specification.

Open issues

Some aspects of the search-page needs to be discussed. These are:

1. “Non-WEB 2.0 alternative”
   At the moment it was not decided if and how the search-module should work with browsers which do not meet the Web 2.0 requirements. It is possible to prepare second – and less interactiv – version of the search-module that would be used by older browsers. However, it requires additional resources.

2. Layout
   The arrangement of elements presented in the Figure 1 is not final. The 'form fields' section on the left, 'returned table' on the right and 'documentation frame' below or other arrangements may be also considered.

3. Pop-up windows
   Instead of loading documents inside the actual page clicking the 'documentation' link could result with opening a new windows. Such solution allows to open few documentation pages simultaneously. Although some users may have locked pop-up windows, for majority a new window per document that does not disappears when new link is clicked may be more comfortable.

4. Special marks
   In order to load a specific fragment of documentation that applies to a specific entity and not a whole module or redirect the browser to specific fragment of that documentation some special marks have to be include to documentation during automatic generation of documentation.

5. Missing documentations
   Not all functions, parameters, rps calls, etc. are documented. Instead of link to documentation some other link (for example “Register missing documentation” could be provided. Clicking that links could result with sending informations on missing documentation to iptel.org's administrators. Although SER programmers precisely know which documentation is missing, but, by following the statistic of these requests iptel.org's people would get reliable information which documentation is 'most wanted'.