Eiffel Home Page (Web) -- Getting started with Eiffel (local)
Software development is, most of the time, cooperative work. You must tell the rest of the team what you're up to, and find out what they can offer you. Bring in distributed development -- increasingly common these days, with some people working at headquarters, others at home, others traveling, an offshore team half a world away … -- and the problem becomes even more critical.
EiffelStudio provides unique facilities to make such distributed development possible in a safe, effective, harmonious way. Some of the key criteria are:
You must be able to export the information easily to the World-Wide Web, the most general and widely available interaction mechanism.
The documentation must be
faithful
to the software. Because of the ever-changing nature of software, this goal is impossible to satisfy unless the documentation is
extracted
from the software -- as opposed to the traditional approach, still perpetuated by many CASE tools, of treating the two as separate.
The task of updating the documentation after a software change must be straightforward and automatic.
It's not enough to support HTML; many other formats are useful too.
Users must have the ability to adapt the mechanism to support
new
formats.
For existing formats, they must have a way to tune the output easily to any specific style standards, company policies, local variants.
EiffelStudio's documentation generation satisfies all these requirements.
Let's see how documentation works by starting to generate it for our Guided Tour system -- which really means for EiffelBase, since that's what it mostly consists of. The HTML result is available as part of the present documentation (we'll tell you where in just a minute), so you don't have to regenerate it unless you want to. Indeed we'll show you when to click Cancel if you are happy with the pre-generated version. But let's get started anyway to understand the principles and possibilities.
Click the following menu entry, used to generate documentation:
This is the next-to-last entry in the Project menu. The last one, by the way, Export XMI … , is directly relevant too: it will make it possible to export information in the standard XML representation for UML, for consumption by third-party products such as Rational's Rose. But for the moment we choose the Documentation entry to start the Eiffel Documentation Wizard.
The Wizard starts with a list of available output formats, also called filters :
The filter names correspond to major documentation formats which EiffelStudio supports by default. Among the most important, listed here in rough order of appearance in the list:
ASCII
: plain text, no formatting codes.
eiffel
: essentially the same as ASCII; useful if you want EiffelStudio to pretty-print your class texts and replace the originals, as explained below.
MML
: internal format for Adobe FrameMaker.
Postscript
: to generate Adobe Postscript output, suitable for printing on a Postscript printer, display on a Postscript previewer such as Ghostscript, or distilling to Adobe PDF.
COM
: to generate class specifications in the form of an Interface Description Language (IDL) interface for Microsoft's COM component model.
RTF
: Microsoft's Rich Text Format, used in particular for Windows "Help" files.
TeX1
,
TeX2
: two variants for Donald Knuth's TEX processing format.
COM
: to generate class specifications in the form of an Interface Description Language (IDL) interface for Microsoft's COM component model.
troff
: if you already know what this is, congratulations (or condolences), you've been around the industry for a while. This is a traditional text-processing format available on Unix systems. Also works for the
gtroff
variant.
html-classic
: HTML, no style sheets. The next variant,
with
style sheets, is strongly recommended unless your colleagues will be reading your documentation with Mosaic 1, vintage 1993, or Netscape 2, Vintage 1995.
html-stylesheet
: HTML with style sheets. This is particularly attractive for Web publishing not only because the output makes full use of style sheet capabilities (fonts, colors, layout, formatting) but also because it becomes trivial to change the look-and-feel to support any style you or your users like, even
after
generation, simply by editing the style sheet file.
Not only do these predefined filters provide support for a number of important industry formats; better yet, if you want another format not represented on the list, or would like to adapt an existing format to your own style preferences, it's easy to define a new filter. The list that EiffelStudio displays comes from the files with a . fil extension that it finds in a subdirectory of the installation:
To define a new filter, simply add a file to this directory. Filters are expressed in a simple notation called EFF ( Eiffel Filter Format ), general enough to support a wide variety of tools for text processing, project management, Web publishing etc. The best way to define a new filter is usually to start from an existing one and adapt it. You will find the specification of EFF at the end of this manual, in "APPENDIX: WRITING DOCUMENTATION FILTERS WITH EFF, THE EIFFEL FILTER FORMAT", 19, page 144 .
Let's select the most obviously attractive of the predefined filters: HTML with stylesheets. Click the line html-stylesheet in the list to make it active, then click Next at the bottom of the Documentation Wizard window. The next window appears:
This is to let you decide which clusters of your system the documentation will include. Initially all clusters -- down to the level of nested subclusters, for example base.structures.list -- appear in the Include list on the right; but you might want to exclude some standard libraries or other clusters from the documentation.
To move a cluster from the right column to the left one, click it to select it, and click the left arrow button; for the reverse, use the right arrow.
You can play with moving a couple of clusters back and forth, but for this Tour we'll want to generate everything, including EiffelBase, so make sure that in the end all clusters appear in the right column, as on the last figure. Then click Next .
The next step of the documentation wizard asks you to select indexing entries:
Eiffel classes, as you know, may start with an Indexing entry that enables class authors to include documentary information in any category they like. It is standard (and part of the official style guidelines) to include a the very least an entry of the form description: Descriptive text in every class. The earlier displays of class LIST showed that entry, which read " Sequential lists, without commitment to a particular representation ".
You may have noted that the purpose of Eiffel's Indexing clauses is, conceptually, similar to that of metatags in HTML. Metatags carry information which Web page visitors do not normally see in the browser; this information is available, however, to search engines and other tools that explore and classify Web pages. So it seems quite appropriate to generate metatags from Indexing entries.
The dialog illustrated in the last figure lets you select the entries you wish to transform into metatags. It appears only if you have selected an HTML filter. It lists all the Indexing tags found anywhere in the system; those on the right will be retained for metatags. Initially the Exclude list on the left contains three tags conventionally used -- at ISE and other Eiffel sites -- for interfacing with configuration management tools, and hence of internal interest only.
There is no need to change the default selection, so just click Next .
The next step of the Documentation Wizard lets you specify what kinds of documents you want to generate:
This is a very important facility since it gives you control over how much you want to publish about the properties of the software:
You may want to publish
everything
, source included, for example on your Intranet for a group of developers working closely together on the same classes, or on the Internet for open-source software.
You may want to publish only the
interfaces
(Contract or Flat-Contract views). This is not necessarily to protect proprietary information; even if you don't care about showing your source code, it is usually too detailed for client programmers, especially in the case of libraries. If various teams work on separate parts of a project, what each releases to the other should usually be the specification, not the implementation.
You may of course want to publish
both
the text and the interface, and let the recipients use the version that best suits their needs for each use.
You may want to publish the
diagrams
, showing the structure in graphical form. Note the warning -- which we are about to ignore -- telling us this may take a while.
The class list, cluster list, cluster hierarchy view, cluster chart (following the conventions of BON) are also optional.
The dialog shown on the last figure lets you specify the exact combination you wish. The figure indicates the default options.
This time, if we generate anything, we'll generate everything. Please check all the boxes (the generation won't occur until the last step) and click Next to move to the next dialog of the Documentation Wizard.
The next dialog only appears when you have asked to generate diagrams:
Although we didn't use this possibility yet, the Diagram view lets you define different subviews of any cluster. One view might show inheritance only, the other client links only; one might include all classes, the other hide some library classes. The last dialog shown will allow you, for any cluster, to select a subview other than the default for the generated diagram.
The last dialog simply asks you where you want to generate the result:
By default, as shown, EiffelStudio will produce the documentation in a subdirectory -- created for the occasion, if it doesn't exist yet -- of the project directory:
You may, however, select any other location you like. In the case of HTML generation, as here, EiffelStudio takes great care to use only relative hyperlinks so that you can move the Documentation directory around, for use either on a file system or on your Web site, with the guarantee that the hyperlinks will work -- as long as you move the entire directory together.
To continue the Guided Tour, you do not need to complete the generation now unless you want to. The generated HTML is available in a subdirectory index-09A of the directory where you are reading this document (if electronically from the ISE Eiffel delivery), and also in the corresponding directory on the Eiffel site, at http://www.eiffel.com/doc/manuals/intro/environment/index-09A/.
The name index-09A for the needs of this manual. The default name is, as noted, Documentation.
If you are happy with looking up one of these pre-generated directories rather than producing your own, click Cancel on the last dialog.
If you prefer to produce your own, click "Finish". For our example system the process takes 7 minutes on the Thinkpad configuration mentioned earlier, and generates a 48 megabyte documentation directory.
Let's take a peek at the generated documentation. If you are reading this electronically in HTML or PDF you can see the generated documentation in the index-09A subdirectory of the documentation. Since you can browse the HTML files of that subdirectory at your leisure we'll just take a quick look to get familiar with the basics. Next to every figure you'll find a link labeled Browser link enabling you to see the corresponding page directly in your browser. The link will open in a new browser page.
Make sure you have a browser with full support for style sheets, such as Internet Explorer 4 or later, Netscape 4 or later.
We start with the root of the generated documentation, index-09A/index.html :
This root page shows overall information about the system. The top set of links, repeated at the bottom, enables you to browse the system from its list of classes, its list of clusters, or the cluster hierarchy; note the box labeled Go to , which provides a built-in search engine, enabling you to type any class list and go directly to the corresponding page. Let's look at the class list: click the box Classes at the top left.
This shows the beginning of the list of classes, alphabetically sorted. You could click any class to get the corresponding information, but wait; we'll look at individual classes in a moment. Instead, click Cluster hierarchy to see the overall organization of the system into clusters:
Note the convention for denoting nested clusters: BASE , BASE.STRUCTURES , BASE.STRUCTURES.LIST . Click BASE.STRUCTURES.LIST to see details of the List cluster of EiffelBase where (under EiffelStudio) we had found the class LIST used as example in the preceding sections:
This indicates the relations of the cluster to others in the hierarchy, and its list of classes. Again you could click any class name but instead note the mention (diagram) next to the cluster name near the top. Remember that when generating the documentation we elected ( "Choosing a level of detail", page 45) to generate everything, diagrams included. Hadn't we checked the corresponding check box, the (diagram) link wouldn't be there. Click it now to get the generated diagrams:
The output is a diagram showing graphically the classes of the cluster and their inheritance relations. All EiffelStudio-generated HTML diagrams use the PNG graphics format ( Portable Network Graphics ), supported by all recent browsers.
The class bubbles in a diagram are all hyperlinks. To see the HTML documentation for our old friend the class LIST -- which you could also obtain by clicking its name on one of the preceding diagrams, or typing it in the Go to field -- just click its bubble (left on the figure, third from the top):
The display shows key information on the class, in a form called the "Chart format" listing the ancestors and then the features, divided into Queries (shown in part on the figure) and Commands . Note that all class names and feature names are hyperlinks, which would lead you to the appropriate place in a class text.
The top row of hyperlinks now includes class formats corresponding to those we discovered under EiffelStudio ( "CLASS VIEWS", 7, page 30 ): Relations (covering ancestors, descendants, clients, suppliers,), full Text , Contracts , Flat contracts . Click Flat contracts to see the full interface of the class:
We'll stop this brief review here but you may continue browsing through the HTML pages if you like. Note how closely the appearance of the class texts, flat forms, contract forms, diagrams and other forms of documentation matches the corresponding formats under EiffelStudio.
Although we suggest staying with the standard, you can easily change any convention that doesn't match your own preferences:
For the EiffelStudio appearance, use
Tools
-->
Preferences
.
For the HTML appearance, if you know about Cascading Style Sheets (CSS) for HTML, edit the style sheet
default.css
. You will find this file in the generated
documentation
directory; alternatively, to ensure the changes are applicable to the generated documentation of all future projects, edit
defaults.css
in the directory
after backing it up. For more profound changes in the structure of the generated HTML, you may also backup and edit the Eiffel Filter Format file
html-stylesheet.fil
in the same directory. EFF is described in an appendix (
19, page 144
).
The documentation generation mechanisms, using HTML or other formats, let you publish your designs, at the level of detail you desire, on an Intranet, the Internet, or as part of documents you release. They are an important part of the power of ISE Eiffel for quality software development.
Eiffel Home Page (Web) -- Getting started with Eiffel (local)
Copyright Interactive Software Engineering, 2001