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:
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.
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.
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.
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.
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 .
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.
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.
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.
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.
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 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.
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.
For the HTML appearance, if you know about Cascading Style Sheets (CSS) for HTML, edit the style sheet
. You will find this file in the generated
directory; alternatively, to ensure the changes are applicable to the generated documentation of all future projects, edit
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.
Copyright Interactive Software Engineering, 2001