Producing and Exporting Documentation

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.

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: Project --> Generate documentation...

This is the next-to-last entry in the Project menu. The last one, by the way, XMI Export ..., 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 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.
• 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: $ISE_EIFFEL/studio/filters

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. More on customization below .

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:

In this pane you select which parts of your system you want to be included in the documentation. By default, all library and cluster names are checked. You should uncheck any that you do not want included.

Note that each library or cluster name must be checked or unchecked individually. For example, unchecking "base" will not automatically deselect "elks" and "ise" which appear under "base".

For this Tour we'll want to generate everything, including EiffelBase, so make sure that in the end all library and cluster names are checked, as in the figure. Then click Next.

Generating Metatags from Note entries

The next step of the documentation wizard asks you to select Note entries:

Eiffel classes, as you know, may start with an note 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 at 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 note 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 note 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 note tags found anywhere in the system; those that are checked will be retained for metatags. Initially unchecked are three tags ("date", "revision", and "status") conventionally used -- at Eiffel Software 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:

• 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.

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.

Generating

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:.../your_project_directory/Documentation

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. If you are happy to continue without generating the documentation at the moment then click Cancel on the last dialog.

Browsing generated documentation

Let's take a look at the generated documentation. We start with the root of the generated documentation, Documentation/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 to Go, 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:

Click BASE to see details of the EiffelBase library 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 link (diagram) next to the cluster name near the top. Remember that when generating the documentation we elected 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 diagram that has been generated for BASE:

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 you could just click its bubble. But because this diagram includes the whole library and is automatically generated, you'd have to look around a bit for the LIST bubble. Go ahead and do that if you wish, or just type the class name LIST into the Go to field and press return:

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 in Viewing Classes in EiffelStudio: 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.

Customization

As shown above in section Documentation Filters the generation mechanisms can produce a number of output formats. The format definition files have an extension .fil and are stored in the directory $ISE_EIFFEL/studio/filters

Although we suggest staying with the standard, you can easily add or change any definition that doesn't match your own preferences.

The format of the filter files is described in Writing Documentation Filters with EFF .

Note: to adapt the presentation format within the EiffelStudio editors, use Tools --> Preferences.