- 19.12 (released) ...
Appendix: Writing Documentation Filters with EFF, the Eiffel Filter Format
- Where to put filters
- Filter basics
- The asterisk
- Escape characters
- Special characters and strings
This appendix provides reference information, not needed in simple uses of EiffelStudio.
We saw in the section on documentation that you can output documentation about your system in many different formats. A number of predefined formats are available, from Postscript to Microsoft's Rich Text Format, FrameMaker, HTML with and without style sheets, TEX and others. There's nothing special about these formats: they just make their conventions known to EiffelStudio through a filter expressed in a simple notation called EFF, or Eiffel Filter Format. 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.
This appendix describes EFF and its conventions, enabling you to write filters. 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.
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
To make a new filter available to yourself and other users of this installation, just add the corresponding file
fil to this directory. Make sure to choose the appropriate
name, since this is what the menu of available filters will display.
An EFF filter follows a very simple structure. As with all other Eiffel-related notations (such as Eiffel itself and Lace, the control language for Eiffel systems), 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 form
Construct | Replacement
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
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, a convention taken from Eiffel); the feature clause itself; two blank lines.
Similarly, in an HTML format, the entry
External |<B> * </B>
means that the Eiffel keyword
external must appear in the filtered form immediately preceded by
<B>, the HTML code for switching to boldface, and immediately followed by
</B>, the code for reverting to the previous setup. Here you can also write the right-hand side without the asterisks, as
<B>external</B>. If, however, all keywords are to use boldface, it is preferable to write a single entry
Keyword |<B> * </B>
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.
The following general syntactic constructs may appear as the left-hand side,
Construct, of an entry:
Most of these denote Eiffel constructs as they appear in the official language reference, the book Eiffel: The Language . Since the Eiffel construct names
Obsolete are also keywords and EFF, like Eiffel, is case-insensitive, the EFF construct names use the suffix
_clause, for example
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 corresponding appendix in Eiffel: The Language
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 corresponding appendix of Eiffel: The Language .
Escape, to protect special characters of the external tool, as explained below.
Tab, denoting any tab character appearing in the class text.
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
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.
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
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
}, 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.
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
%ndenotes a new line.
%T(recommended form) or
%tdenotes a tab.
%%denotes a percent sign.
%(percent followed by a space) denotes a space. This is equivalent to just a space, but more visible.
c is not one of the characters for which special conventions have been listed,
c denotes the character
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.