Version

23.09 (released) ...

Writing Documentation Filters with EFF, the Eiffel Filter Format

The section Producing and Exporting Documentation describes how to generate documentation about a system from within EiffelStudio.

A number of predefined formats are available as filter files in a simple notation called EFF, or Eiffel Filter Format.

This chapter describes EFF and its conventions, enabling you to write filters.

If you have a favorite format that you'd like EiffelStudio to use for producing documentation, you can define your own filter in EFF. Applications include:

Producing a variant of an existing format, to support some "house style" that you have defined, such as a different formatting or fonts.
Producing documentation for a text processing tool that's not among those supported by default.
Producing documentation that purposely omit some parts of Eiffel texts, in line with the ideas applied by the Contract and Flat Contract forms.

Note that in practice the best way to write an EFF filter is usually not from scratch, but by copying an existing filter -- one that seems closest to your needs -- and adapting the copy.

Available Standard Filters

***Filter Files Overview***
Documentation Type	Generated File Extension	Filter File	Remarks
ASCII	txt	ASCII.fil	Plain text, no formatting codes.
Build	?	build.fil	EiffelBuild - possibly outdated, around year 2000
Cayenne	cj	cayenne.fil	Cayenne Software as of Aug. 1998 Sterling Software, Inc. (?)
COM	?	com.fil	Class specifications in the form of an Interface Description Language (IDL) interface for Microsoft's COM component model.
Cool Jex	cj	cool_jex.fil	UML modelling by IBM Rational Software (2008, formerly Telelogic March 2000, formerly Sterling Software )
Eiffel	e	eiffel.fil	Replicates Eiffel source, essentially the same as ASCII; useful if you want EiffelStudio to pretty-print your class texts and replace the originals.
HTML	html	html.fil	Web page simple formatting with tags
HTML	html	html-classic.fil	Web page old version plain no style sheets.
HTML	html	documentation.fil	Web page with style sheet.
HTML	html	html-stylesheet.fil	Web page with style sheet.
Index	index	index.fil	Source file names for inclusion into web pages
MML	mml	MML.fil	Internal format for Adobe FrameMaker.
PostScript	ps	PostScript.fil	Adobe Postscript output, suitable for printing on a Postscript printer, display on a Postscript previewer such as Ghostscript, or distilling to Adobe PDF.
RTF	rtf	RTF.fil	Microsoft's Rich Text Format, used in particular for Windows "Help" files.
TeX 1	tex	TeX1.fil	Donald Knuth's TEX processing format. requires `cmbxti10' font.
TeX 2	tex	TeX2.fil	Donald Knuth's TEX processing format.
Troff	troff	troff.fil	A traditional text-processing format available on Unix systems. Also works for the gtroff variant.
XML	xml	xml.fil	Extensible Markup Language

***Assisting***
Documentation Type		File	Remarks
HTML		default.css	default web page formatting

***Special***
Documentation Type		File	Remarks
EFF Formatting		format.fil-template	Listing of recognized tags

Where to put filters

When you choose to generate documentation, EiffelStudio will ask you to select a filter from a list it obtains by looking up the files of extension .fil in the directory $ISE_EIFFEL/studio/filters

To make a new filter available to yourself and other users of this installation, just add the corresponding file some_name.fil to this directory. Make sure to choose the appropriate name, since this is what the menu of available filters will display.

Output generated

The output will be placed in the directory specified in the "Project>Generate Documentation" dialog of EiffelStudio.

The output type is determined by the suffix construct in the filter file.

Output type 1 - suffix is HTML:

HTML formatted web pages with file extension .HTML
with a copy of the stylesheet default.css copied to the Documentation directory
with a generated menu goto.html placed into the Documentation directory with submenu directories as required
any other supporting files (stylesheets, javascript) must manually be placed in the Documentation directory
the filter must define a major construct, eg class_declaration, cluster_declaration, to contain a complete HTML skeleton of a webpage

Output type 2 - suffix is any other:

if suffix is missing the output will produced with a .TXT file extension
if suffix is defined the output will produced with the given file extension
as needed the filter must define a major construct, eg class_declaration, cluster_declaration, to contain a complete skeleton for the desired output target

Filter basics

An EFF filter follows a very simple structure. As with all other Eiffel-related notations any line or part of a line beginning with two consecutive dashes -- is a comment, except if it immediately follows a percent sign since, as will be seen below, - %- is used to denote an Eiffel comment in the class text. Blank lines are also permitted. Comments and blank lines carry no semantic value.

Except for comments and blank lines, a filter is a sequence of entries, all of the formConstruct | Replacement

where: Construct is one of a set of possible strings, most of which correspond to Eiffel constructs such as Class_declaration or Eiffel keywords such as class ; and Replacement is a string indicating how to format specimens of the Construct that appear in a class text.

For readability, there may be any number of blanks or tabs between the Construct and the vertical bar |, so that you can align all the bars if you wish. On the right of the bar, however, all characters including blanks and tabs are significant, since they are part of the replacement for the Construct.

The asterisk

In the Replacement part, you may use the symbol * (asterisk) to denote the construct specimen itself.

So for example the entry Feature_clause | %N%N*%N%N specifies the following formatting for any Feature_clause: two successive blank lines (expressed as %N, New Line); the feature clause itself; two blank lines.

Similarly, in an HTML format, the entry External | *  means that the Eiffel keyword external must appear in the filtered form immediately preceded by , the HTML code for switching to boldface, and immediately followed by , the code for reverting to the previous setup.

Here you can also write the right-hand side without the asterisks, as external. If, however, all keywords are to use boldface, it is preferable to write a single entry Keyword | *  which, thanks to the asterisk, will govern all construct specimens of the Keyword category. You can still override this specification for an individual keyword by including a specific entry for it.

Constructs

The general syntactic constructs may appear as the left-hand side, Construct, of an entry:

Most EFF constructs denote Eiffel constructs as they appear in the official language reference.

Since certain construct names Feature, Invariant and Obsolete are also Eiffel keywords and EFF, like Eiffel, is case-insensitive, the EFF construct names use the suffix _clause, for example Feature_clause.

The constructs corresponding to syntactic constructs are self-explanatory. The others are:

Class_end, denoting the final end of a class text.
Keyword, denoting any Eiffel keyword among those listed in boldface in the the official language reference.
New_line, denoting any passage to a new line in the class text.
Suffix, used to introduce the file extension for the generated documentation files. If you don't specify this, EiffelStudio will use the filter's name as extension.
Symbol, denoting any of the Eiffel symbols listed in the official language reference.
Escape, to protect special characters of the external tool, as explained below.
Tab, denoting any tab character appearing in the class text.

Keywords

A Construct part may consist of the name of an Eiffel keyword. To see the complete list of possible keywords, look at the template filter, file format.fil-template in the default filter directory $ISE_EIFFEL/studio/filters, which includes all of them with a single asterisk * as the Replacement part.

If entries are present for both the Keyword construct and individual keywords, the individual keyword entries will override the general entry for the keywords listed; the general entry will apply to all other keywords. This makes it possible to have both a general convention for keywords and a special convention for some of them.

Symbol

A Construct part may consist of an Eiffel symbol, such as :=, /= and many others. Again, you may see the complete list by looking at format.fil-template. Note the following conventions:

% * represents an asterisk. For example as a multiplication operator; the % avoids the confusion with the special meaning of the asterisk for EFF. You can find examples of this convention in the EFF filters for troff and gtroff.
Similarly, the Eiffel comment symbol appears as - %-, since just writing - - would introduce a comment in the EFF filter itself.

As with keywords, you may specify a general convention for symbols, defined by an entry for the construct Symbol, and special conventions for certain individual symbols. Specific symbol entries will override the general Symbol convention.

Escape characters

A text processing system or other external tool may attach a special role to characters that may normally appear in Eiffel texts. For example, the braces { and }, used in Eiffel's Export clauses, have a special meaning for TEX. Including them without precaution in TEX input will cause trouble. Similarly, many text processing formats attach a special meaning to the backslash character \ which, although not special for Eiffel, may appear in an Eiffel string.

In such cases the filter must " escape " the special character, that is to say, protect it by other characters. For example troff and other text processing tools treat two successive backslash characters \\ as denoting a single backslash in the text to be output. The first backslash is the escape character, protecting the second one.

The Escape construct addresses such cases. The first character that follows Escape (after one or more blanks or tabs) is the character to be escaped. The string after the vertical bar is the replacement for that character.

Here for example is an escape entry for the backslash in tools that need to escape it through another backslash:

Special characters and strings

EFF uses Eiffel-like conventions, based on the percent sign, for control characters appearing in Replacement parts of entries. Two of these conventions have just been noted: % * to represent an asterisk and %- to represent a dash that does not introduce an Eiffel comment. In addition:

%| denotes a vertical bar. (This is necessary since EFF uses | by itself in each entry to separate the Construct from the corresponding Replacement.)
%N (recommended form) or %n denotes a new line.
%T (recommended form) or %t denotes a tab.
%% denotes a percent sign.
% (percent followed by a space) denotes a space. This is equivalent to just a space, but more visible.

If c is not one of the characters for which special conventions have been listed, % c denotes the character c itself.

A multi-line entry uses the Eiffel convention for string continuations: % at the end of a line to signal that there is a continuation; a continuation line begins with zero or more spaces and tabs followed by a % ; the characters after the % are the continuation of the string.

Sample page encoding

We show sample code taken from existing filter files to demonstrate the basic structure of the skeleton needed for visual presentation.

Note in both examples the position of the *place holder that will contain the expanded page body for the referenced construct.

webpages

To replace the default.css copied into your Documentation directory write your own stylesheet based on it and save under a different name. Important: chose a different name or EiffelStudio will overwrite it. Add any scripting files to the Documentation directory if required. Font choice is of course also a user option. Note the generated goto.html file (not a standalone webpage) that contains the navigation thru the generated webpages and is expected to be included by the page skeleton. Replace and add any required inclusion links into the HEAD section of the webpage.

class_declaration |% %<!DOCTYPE html>%N% %<html>%N% %<head>%N% %<meta name="generator" content="$generator$">%N% %$html_meta$% %<meta name="viewport" content="width=device-width%, initial-scale=1.0">%N% %<link href="https://fonts.googleapis.com/css?family=PT+Sans" rel="stylesheet">%N% %<title>$title$</title>%N% %<link rel="stylesheet" href="$root$default.css" type="text/css">%N% %<script type="text/javascript" src="$root$goto.html"></script>%N% %</head>%N% %<body>%N% %<pre>*</pre>%N% %Generated by % %<a href="http://www.eiffel.com">ISE EiffelStudio</a>%N% %</body>%N% %</html>%N

for printing

Here a sample coding for RTF formatted output, to be run thru some comaptible word processor for pretty printing.

Cluster_declaration, Class_declaration |% %{\rtf1\ansi\ansicpg1252\deflang1033{\fonttbl{\f0\fscript\fcharset0 Courier;}}% %{\colortbl ;\red0\green0\blue0;\red255\green255\blue255;\red128\green0\blue0;% %\red0\green0\blue255;\red0\green128\blue0;\red0\green0\blue128;}%N% %{\cf3\f0\fs16 {\tab}{\tab}{\tab}%-%- Automatic generation produced by ISE Eiffel %-%-%N% %{\line}%N% %{*}%N% %{\line}%N% %{\cf3 {\tab}{\tab}{\tab}%-%- Generated by ISE Eiffel %-%-}%N% %{\line}%N% %{\cf3{\tab}{\tab}{\tab}%-%- For more details: http://www.eiffel.com %-%-}%N% %}}%N

The EFF Template File

The following is a replica of the EFF template file as distributed with EiffelStudio v20.11.

Location: $ISE_EIFFEL/studio/filters/format.fil-template Timestamp: $Date: 2013-04-18 20:30:43 +0000 (Thu, 18 Apr 2013) $ $Revision: 92456 $

Generator provided Items

Several extra items may be used and accessed through: $item$.

In every construct, the following items are defined:$generator$ "ISE EiffelStudio version x.x.x" $html_meta$ HTML specific. Entire indexing clause defined as meta data. Example: "<META NAME="keywords" CONTENT="eiffel, O-O">". $class$ Classname in uppercase. If currently processed file does not represent an Eiffel class, is empty. $title$ Title for current document. Example: "EV_ANY Text". $root$ Relative base directory of generated documentation. Example: "../../../../"

Properties

suffix |html Used to specify suffix used for this format. Examples: html, txt, ps, e, etc. file_separator |/ Specify when format requires a specific file separator. For HTML, specify '/'. If this symbol is omitted, the separator specific for the platform is used.

Basic Text

basic |* Basic text

Hyperlinking items

menu_bar |* Contains the different menu items. menu_item |* Any of the global menu items, "Classes", "Clusters", etc. If not specified, no text is processed, since without hyperlinking menu items are useless. Symbol: $file$ class_menu_item |* A link to one of the specified class formats. If not specified, no text is processed. Symbol: $file$ menu_item_disabled |* The current format. class_menu_item_disabled |* The current format. cluster_name |* Symbol: $file$. tooltip |* Text contained within this construct requests a tooltip. Symbol: $tooltip$. HTML Example: * origin_comment |* Text describing the written class of a feature. Example: -- from ANY

Major syntactical constructs

Eiffel syntax items

features |* Eiffel feature reference. Symbols: $feature$ actual feature name of feature in class where it is written. $file$ link to class where feature is written. HTML example: <A HREF="$file$#$feature$">*</A> keyword |* Processed when a keyword is encountered but it is not explicitly specified. keyword_features |* Operator keyword or "Precursor" If not specified, "keyword" is processed. $file$ and $feature$ are defined, like for "features". symbol |* Processed when a symbol is encountered but it is not explicitly specified. symbol_features |* Operator symbol. If not specified, "symbol" is processed. $file$ and $feature$ are defined, like for "features". reserved_word |* `Result' or `Current'. comment |* Example. comment_url |* A URL in a comment. If not specified, "comment" is processed. Symbol $file$ contains the URL. string |* Eiffel literal string. string_url |* A URL inside an Eiffel string. If not specified, "string" is processed. Symbol $file$ contains the URL. quoted |* character |* number |* local_symbol |* assertion_tag |* indexing_tag |* generic |* Formal generic class.

Whitespace processing

tab |* HTML Example: "&nbsp%;&nbsp%;&nbsp%;&nbsp%;". new_line |* HTML Example: " ". multiple_spaces |* In case a sequence of spaces are encountered, this symbol is used for all subsequent spaces. HTML Example: "&nbsp%;".

Eiffel keywords

Eiffel symbols

:= |* : |* %, |* -> |* %-- |* $ |* . |* .. |* " |* = |* ! |* > |* >= |* << |* [ |* { |* ( |* < |* <= |* ' |* >> |* ] |* } |* ) |* ?= |* ; |* ~ |* Operators: + |* - |* %* |* / |* // |* \\ |* ^ |* /= |*

Obsolete filter constructs

!! |* creation |* cluster_declaration |* cluster_header |*

Back to Tutorials

Permanent link

cached: 04/18/2024 10:46:45.000 PM