Eiffel Home Page (Web) -- Getting started with Eiffel (local) Eiffel Home PageEiffel Home Page

Previous, Up, NextPrevious sectionUpNext section


           Help reading this manual

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:

EiffelStudio's documentation generation satisfies all these requirements.

Documentation filters

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:

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 .

Generating an HTML record of your project

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 .

Generating Metatags from Indexing entries

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 .

Choosing a level of detail

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:

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.

Specifying cluster views

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.

Here we only have the default view, so just click Next .


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.

Browsing generated documentation

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 :

Browser link

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.

Browser link

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:

Browser link

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:

Browser link

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:

Browser link

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):

Browser link

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:

Browser link

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:

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.

Previous, Up, NextPrevious sectionUpNext section

Eiffel Home Page (Web) -- Getting started with Eiffel (local)