mirrors/eiffel-org
1
0
Fork 0
mirror of https://github.com/EiffelSoftware/eiffel-org.git synced 2025-12-06 23:02:28 +01:00
Code Issues Packages Projects Releases Wiki Activity

Author:halw

Browse Source 
Date:2009-01-07T21:59:02.000000Z


git-svn-id: https://svn.eiffel.com/eiffel-org/trunk@154 abb3cda0-5349-4a8f-a601-0c33ac3a8c38
This commit is contained in:
halw
2009-01-07 21:59:02 +00:00
parent 8805352e2a
commit 681600436e
5 changed files with 79 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
documentation/current/eiffelstudio/eiffelstudio-guided-tour/compiling-and-executing-system.wiki
View File

@@ -18,7 +18,7 @@ Right now you first have to add the project, so click on <code>Add Project</code
$ISE_EIFFEL\examples\studio\tour\simple.ecf
</code>
remember that <code>$ISE_EIFFEL</code> stands for the location of the Eiffel installation, such as <code>C:\Eiffel63</code> ; ECF files are normally marked by the <code>.ecf</code> file extension).
remember that <code>$ISE_EIFFEL</code> stands for the location of the Eiffel installation, such as <code lang=text>C:\EiffelStudio 6.3</code> ; ECF files are normally marked by the <code>.ecf</code> file extension).
Use the File Explorer to go to the directory <code>$ISE_EIFFEL/examples/studio/tour/</code> and select the appropriate file. You will then be back on the startup dialog.
@@ -29,7 +29,7 @@ Click <code>Open</code> to confirm. This starts compilation of your project.
During Eiffel compilation, a progress bar displays the successive compilation steps, or "degrees". The bulk of our little project is the EiffelBase library, which the EiffelStudio installation procedure has precompiled; so just now there's only a few extra classes to compile, and the process is almost instantaneous on a state-of-the-art computer. Even if you had to compile the EiffelBase classes, EiffelStudio compilation is so fast that you would hardly have the time to read the "degree" messages; you can see them later in compilations of bigger classes and systems.
{{note| ''On an IBM Thinkpad, Pentium III 850 MHz, 256 MB, running Windows 2000 Professional, Eiffel compilation takes about 9 seconds for the entire Guided Tour system including non-precompiled EiffelBase. '' }}
{{note|On an IBM Thinkpad, Pentium III 850 MHz, 256 MB, running Windows 2000 Professional, Eiffel compilation takes about 9 seconds for the entire Guided Tour system including non-precompiled EiffelBase. }}
After Eiffel compilation completes you will see the message
<code>

76
documentation/current/eiffelstudio/eiffelstudio-guided-tour/producing-and-exporting-documentation.wiki
View File

@@ -16,47 +16,47 @@ 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 <code> Cancel </code> if you are happy with the pre-generated version. But let's get started anyway to understand the principles and possibilities.
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 <code>Cancel</code> 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:
<code lang="text">
Project --> Generate documentation...
</code>
This is the next-to-last entry in the <code> Project </code> menu. The last one, by the way, <code> XMI Export </code> <span>...</span>, 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 <code> Documentation </code> entry to start the Eiffel Documentation Wizard.
This is the next-to-last entry in the <code>Project</code> menu. The last one, by the way, <code lang=text>XMI Export</code> <span>...</span>, 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 <code>Documentation</code> entry to start the Eiffel Documentation Wizard.
The Wizard starts with a list of available output formats, also called <span>filters</span>:
[[Image:index-37]]
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:
* <code> ASCII </code> : plain text, no formatting codes.
* <code> eiffel </code> : essentially the same as ASCII; useful if you want EiffelStudio to pretty-print your class texts and replace the originals, as explained below.
* <code> MML </code> : internal format for Adobe FrameMaker.
* <code> Postscript </code> : 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.
* <code> COM </code> : to generate class specifications in the form of an Interface Description Language (IDL) interface for Microsoft's COM component model.
* <code> RTF </code> : Microsoft's Rich Text Format, used in particular for Windows "Help" files.
* <code> TeX1 </code>, <code> TeX2 </code> : two variants for Donald Knuth's TEX processing format.
* <code> troff </code> : 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 <span>gtroff</span> variant.
* <code> html-classic </code> : HTML, no style sheets. The next variant, <span>with</span> style sheets, is strongly recommended unless your colleagues will be reading your documentation with Mosaic 1, vintage 1993, or Netscape 2, Vintage 1995.
* <code> html-stylesheet </code> : 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 <span>after</span> generation, simply by editing the style sheet file.
* <code lang=text>ASCII</code> : plain text, no formatting codes.
* <code>eiffel</code> : essentially the same as ASCII; useful if you want EiffelStudio to pretty-print your class texts and replace the originals, as explained below.
* <code>MML</code> : internal format for Adobe FrameMaker.
* <code>Postscript</code> : 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.
* <code>COM</code> : to generate class specifications in the form of an Interface Description Language (IDL) interface for Microsoft's COM component model.
* <code>RTF</code> : Microsoft's Rich Text Format, used in particular for Windows "Help" files.
* <code>TeX1</code>, <code>TeX2</code> : two variants for Donald Knuth's TEX processing format.
* <code>troff</code> : 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 <span>gtroff</span> variant.
* <code>html-classic</code> : HTML, no style sheets. The next variant, <span>with</span> style sheets, is strongly recommended unless your colleagues will be reading your documentation with Mosaic 1, vintage 1993, or Netscape 2, Vintage 1995.
* <code>html-stylesheet</code> : 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 <span>after</span> 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 <span>another</span> 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 <span>.</span> <code> fil </code> extension that it finds in a subdirectory of the installation:
Not only do these predefined filters provide support for a number of important industry formats; better yet, if you want <span>another</span> 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 <code>.fil</code> extension that it finds in a subdirectory of the installation:
<code>$ISE_EIFFEL/studio/filters</code>
To define a new filter, simply add a file to this directory. Filters are expressed in a simple notation called EFF ( <span>Eiffel Filter Format</span> ), 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, [[19 APPENDIX: WRITING DOCUMENTATION FILTERS WITH EFF, THE EIFFEL FILTER FORMAT|here]] .
==Generating an HTML record of your project==
Let's select the most obviously attractive of the predefined filters: HTML with stylesheets. Click the line <code> html-stylesheet </code> in the list to make it active, then click <code> Next </code> at the bottom of the Documentation Wizard window. The next window appears:
Let's select the most obviously attractive of the predefined filters: HTML with stylesheets. Click the line <code>html-stylesheet</code> in the list to make it active, then click <code>Next</code> at the bottom of the Documentation Wizard window. The next window appears:
[[Image:index-38]]
This is to let you decide which clusters of your system the documentation will include. Initially all clusters/libraries appear in the <code> Include </code> list on the right; but you might want to exclude some standard libraries or other clusters from the documentation.
This is to let you decide which clusters of your system the documentation will include. Initially all clusters/libraries appear in the <code>Include</code> 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 <code> Next </code>.
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 <code>Next</code>.
==Generating Metatags from Indexing entries==
@@ -64,13 +64,13 @@ The next step of the documentation wizard asks you to select indexing entries:
[[Image:index-39]]
Eiffel classes, as you know, may start with an <code> Indexing </code> 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 <code> description: </code> <code> Descriptive text </code> in every class. The earlier displays of class <code> LIST </code> showed that entry, which read " <code> Sequential lists, without commitment to a particular representation </code>".
Eiffel classes, as you know, may start with an <code>Indexing</code> 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 <code>description:</code> <code>Descriptive text</code> in every class. The earlier displays of class <code>LIST</code> showed that entry, which read " <code>Sequential lists, without commitment to a particular representation</code>".
You may have noted that the purpose of Eiffel's <code> Indexing </code> 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 <code> Indexing </code> entries.
You may have noted that the purpose of Eiffel's <code>Indexing</code> 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 <code>Indexing</code> 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 <code> Indexing </code> tags found anywhere in the system; those on the right will be retained for metatags. Initially the <code> Exclude </code> list on the left contains three tags conventionally used -- at Eiffel Software and other Eiffel sites -- for interfacing with configuration management tools, and hence of internal interest only.
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 <code>Indexing</code> tags found anywhere in the system; those on the right will be retained for metatags. Initially the <code>Exclude</code> list on the left contains three tags 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 <code> Next </code>.
There is no need to change the default selection, so just click <code>Next</code>.
==Choosing a level of detail==
@@ -87,7 +87,7 @@ This is a very important facility since it gives you control over how much you w
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 <code> Next </code> to move to the next dialog of the Documentation Wizard.
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 <code>Next</code> to move to the next dialog of the Documentation Wizard.
==Specifying cluster views==
@@ -97,7 +97,7 @@ 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 <code> Next </code>.
Here we only have the default view, so just click <code>Next</code>.
==Generating==
@@ -107,57 +107,55 @@ 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:
<code>
Project_directory /Documentation
</code>
.../your_project_directory/Documentation</code>
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 <code> Documentation </code> 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.
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 <code>Documentation</code> 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 <code> Cancel </code> on the last dialog.
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 <code>Cancel</code> on the last dialog.
{{note| ''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 82 megabyte documentation directory.'' }}
{{note|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 82 megabyte documentation directory. }}
==Browsing generated documentation==
Let's take a look at the generated documentation. We start with the root of the generated documentation, <code> Documentation/index.html </code> :
Let's take a look at the generated documentation. We start with the root of the generated documentation, <code>Documentation/index.html</code> :
[[Image:index-43]]
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 <code> to Go </code>, 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 <code> Classes </code> at the top left.
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 <code>to Go</code>, 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 <code>Classes</code> at the top left.
[[Image:index-44]]
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 <code> Cluster hierarchy </code> to see the overall organization of the system into clusters:
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 <code>Cluster hierarchy</code> to see the overall organization of the system into clusters:
[[Image:index-45]]
Click <code> BASE </code> to see details of the EiffelBase library where (under EiffelStudio) we had found the class <code> LIST </code> used as example in the preceding sections:
Click <code>BASE</code> to see details of the EiffelBase library where (under EiffelStudio) we had found the class <code>LIST</code> used as example in the preceding sections:
[[Image:index-46]]
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 <code> (diagram) </code> 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 <code> (diagram) </code> link wouldn't be there. Click it now to get the generated diagrams:
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 <code>(diagram)</code> 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 <code>(diagram)</code> link wouldn't be there. Click it now to get the generated diagrams:
[[Image:index-47]]
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 ( <span>Portable Network Graphics</span> ), 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 <code> LIST </code> -- which you could also obtain by clicking its name on one of the preceding diagrams, or typing it in the <code> Go to </code> field -- just click its bubble:
The class bubbles in a diagram are all hyperlinks. To see the HTML documentation for our old friend the class <code>LIST</code> -- which you could also obtain by clicking its name on one of the preceding diagrams, or typing it in the <code>Go to</code> field -- just click its bubble:
[[Image:index-48]]
The display shows key information on the class, in a form called the "Chart format" listing the ancestors and then the features, divided into <code> Queries </code> (shown in part on the figure) and <code> Commands </code>. Note that all class names and feature names are hyperlinks, which would lead you to the appropriate place in a class text.
The display shows key information on the class, in a form called the "Chart format" listing the ancestors and then the features, divided into <code>Queries</code> (shown in part on the figure) and <code>Commands</code>. 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 ( [[7 CLASS VIEWS|"CLASS VIEWS"]] ): <code> Relations </code> (covering ancestors, descendants, clients, suppliers, ), full <code> Text </code>, <code> Contracts </code>, <code> Flat contracts </code>. Click <code> Flat contracts </code> to see the full interface of the class:
The top row of hyperlinks now includes class formats corresponding to those we discovered under EiffelStudio ( [[7 CLASS VIEWS|"CLASS VIEWS"]] ): <code>Relations</code> (covering ancestors, descendants, clients, suppliers, ), full <code>Text</code>, <code>Contracts</code>, <code>Flat contracts</code>. Click <code>Flat contracts</code> to see the full interface of the class:
[[Image:index-49]]
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 <code> Tools </code> <code> --> </code> <code> Preferences </code>.
* For the HTML appearance, if you know about Cascading Style Sheets (CSS) for HTML, edit the style sheet <code> default.css </code>. 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 <code> defaults.css </code> 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 <code> html-stylesheet.fil </code> in the same directory. EFF is described in [[19 APPENDIX: WRITING DOCUMENTATION FILTERS WITH EFF, THE EIFFEL FILTER FORMAT| Chapter 19, "Appendix"]] .
* For the EiffelStudio appearance, use <code lang=text>Tools --> Preferences</code>.
* For the HTML appearance, if you know about Cascading Style Sheets (CSS) for HTML, edit the style sheet <code>default.css</code>. 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 <code>defaults.css</code> 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 <code>html-stylesheet.fil</code> in the same directory. EFF is described in [[19 APPENDIX: WRITING DOCUMENTATION FILTERS WITH EFF, THE EIFFEL FILTER FORMAT| Chapter 19, "Appendix"]] .
<code>
$ISE_EIFFEL/studio/filters
</code>
$ISE_EIFFEL/studio/filters</code>
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 EiffelStudio for quality software development.

16
documentation/current/eiffelstudio/eiffelstudio-guided-tour/starting-browse.wiki
View File

@@ -18,11 +18,11 @@ Let's see how this works. First, take a look at the EiffelStudio window:
<div> [[Image:index-8]] </div>
{{note| ''If some parts are too small, just resize the window to arrive at something like what's on the figure. When it first comes up, EiffelStudio initially uses a fairly small window, because it's designed to run on a 800x600 display, although of course a bigger display is recommended. But as soon as you have resized it, EiffelStudio will come up, in the next session, with the size you've set.'' }}
{{note|If some parts are too small, just resize the window to arrive at something like what's on the figure. When it first comes up, EiffelStudio initially uses a fairly small window, because it's designed to run on a 800x600 display, although of course a bigger display is recommended. But as soon as you have resized it, EiffelStudio will come up, in the next session, with the size you've set.}}
You can see five panes, marked on the figure: <code>Features</code>, <code>Class</code>, <code>Properties</code>, <code>Clusters</code>, <code>Context</code>. There will be others, such as <code>Search</code>, and you can remove any of them, except <code>Class</code>, at any time to make room for the others.
You can see five panes, marked on the figure: <code>Features</code>, <code lang=text>Class</code>, <code>Properties</code>, <code>Clusters</code>, <code>Context</code>. There will be others, such as <code>Search</code>, and you can remove any of them, except <code lang=text>Class</code>, at any time to make room for the others.
So far we have talked about " <span>the</span> EiffelStudio window", but in fact that's not correct. What you see is <span>one</span> " '''Development Window'''", of which you can have as many as you wish. Some people prefer to use a single development tool, avoiding screen clutter; others don't think twice about having lots of windows, taking the "desktop metaphor" to its full conclusion (some non-computer desktops are quite cluttered). There are many ways to start a new Development Window; for example if you look at the entries in the <code>File</code> menu at the top left -- don't select any of these entries yet, just look -- you'll see, among others, <code>New window</code>, which would create a new Development Window.
So far we have talked about "the EiffelStudio window", but in fact that's not correct. What you see is one "'''Development Window'''", of which you can have as many as you wish. Some people prefer to use a single development tool, avoiding screen clutter; others don't think twice about having lots of windows, taking the "desktop metaphor" to its full conclusion (some non-computer desktops are quite cluttered). There are many ways to start a new Development Window; for example if you look at the entries in the <code>File</code> menu at the top left -- don't select any of these entries yet, just look -- you'll see, among others, <code>New window</code>, which would create a new Development Window.
Whether you have one Development Window or many, each may have as its '''target''' an element of the system: system, cluster, class (the most common case), feature, run-time object. This simply means that the tool displays information about that element.
@@ -40,7 +40,7 @@ The Development Window is now targeted to class <code>ARRAY</code>. Each of the
* Features Tree, top-left: a tree view of all the features of the class, grouped by the feature categories ( <code>Initialization</code>, <code>Access</code>, <span>...</span> ) as they appear in the class.
* Editing Tool, top-right: the source text of the class, editable. For the moment the pane is too small to display much of interest -- it only shows the very first few lines -- but we'll enlarge it when we need to modify class texts. (Not <code>ARRAY</code>, though, as it's not the kind of class you want to change during your first session with EiffelStudio, so just wait a bit.)
* Cluster Tree, bottom-left: a tree view of the clusters of the system.
* Context Tool, bottom right: a bag full of neat tricks. At the moment it just shows some general information about the system (where it resides, the name of its root class <code>TESTROOT</code> ), but more generally it's there to give you all kinds of interesting views of the system, through the various tabs at the bottom: <code>Output</code>, <code>Diagram</code>, <code>Class</code>, <code>Feature</code>, <code>Metric</code>, <code>External Output</code>, <code>C Output</code>, <code>Errors</code>, <code>Warnings</code>.
* Context Tool, bottom right: a bag full of neat tricks. At the moment it just shows some general information about the system (where it resides, the name of its root class <code>TESTROOT</code> ), but more generally it's there to give you all kinds of interesting views of the system, through the various tabs at the bottom: <code>Output</code>, <code>Diagram</code>, <code lang=text>Class</code>, <code lang=text>Feature</code>, <code>Metric</code>, <code lang=text>External Output</code>, <code>C Output</code>, <code>Errors</code>, <code>Warnings</code>.
==A peek at diagram==
@@ -52,7 +52,7 @@ This displays a class diagram in the Context Tool:
[[Image:index-12]]
{{note| ''If nothing appears in the Context Tool when you click the Diagram Tab, that's because the Context Tool and the Class View are not linked. Linking the two tools together will ensure that whenever a change is made in one tool the other will update to reflect that change. To link the tools select the menu entry '' <code>View</code> <code>--></code> <code>Link context tool</code> ''; this will display the diagram as shown. We'll see the explanation for this behavior in '' [[10 RETARGETING THROUGH PICK-AND-DROP| ''Isolating the context, pg 68'' ]] }}
{{note|If nothing appears in the Context Tool when you click the Diagram Tab, that's because the Context Tool and the Class View are not linked. Linking the two tools together will ensure that whenever a change is made in one tool the other will update to reflect that change. To link the tools select the menu entry <code>View -> Link context tool</code> ; this will display the diagram as shown. We'll see the explanation for this behavior in [[10 RETARGETING THROUGH PICK-AND-DROP|Isolating the context, pg 68]] }}
The diagram is cropped to the available area; to get the whole picture, resize the window from the bottom-right corner. You can now see the inheritance structure:
@@ -78,7 +78,7 @@ The most extensive of these EiffelBase libraries is <code>structures</code>, whi
[[Image:index-17]]
{{note| ''If you initially don't see as many details as shown on this figure, you may get them by resizing the window, moving the vertical pane boundary, and possibly scrolling.'' }}
{{note|If you initially don't see as many details as shown on this figure, you may get them by resizing the window, moving the vertical pane boundary, and possibly scrolling.}}
The EiffelBase Data Structure library and its subclusters are described in the book <span> [http://www.eiffel.com/doc/ Reusable Software] </span>. Let's go to one of the most frequently used subclusters, <code>list</code>, containing implementations of list structures. Click the <code>+</code> next to <code>list</code>. This time, since list is a terminal cluster, it's not subclusters you'll see, but '''classes''', identified by small ellipses:
@@ -110,7 +110,7 @@ As a fourth way to retarget -- there are more, and after this one we'll stop cou
[[Image:index-21]]
If you click this arrow -- the little black triangle -- you will see a menu of all your recent targets. Doing this now will only show the two classes visited so far, <code>STRING</code> and <code>LIST</code>, but later on there will be more entries. By default EiffelStudio remembers 10 classes; this is one of the settings you can change later if you wish, through the menu <code>Tools</code> <code>--></code> <code>Preferences</code>. (There's no point in doing this now.)
If you click this arrow -- the little black triangle -- you will see a menu of all your recent targets. Doing this now will only show the two classes visited so far, <code>STRING</code> and <code>LIST</code>, but later on there will be more entries. By default EiffelStudio remembers 10 classes; this is one of the settings you can change later if you wish, through the menu <code lang=text>Tools-->Preferences</code>. (There's no point in doing this now.)
==Adding to Favorites==
@@ -136,5 +136,5 @@ Here, for example, the editor lists <code>CHAIN</code>, as a parent of <code>LIS
The place where we found the class <code>CHAIN</code> in the original tool (the one targeted to <code>LIST</code> ) was the bubble representing the class in the Diagram View. But that's just one possibility. A general principle of EiffelStudio is '''semantic consistency''' : when you want to work with a development object -- a class, a feature, a cluster -- you can grab it wherever it appears in the interface, and in whatever format it is displayed: you might have spotted it be in the Diagram View, in the text of a class in the Editing Tool, in the Cluster or Feature Tree, or in any of the class documentation formats that we will soon see; and the form under which you found it may be text -- the name of the class in a text document -- or some graphical representation, such as a class bubble in a diagram. These variants don't matter: if the class or other development object catches your fancy, you can do whatever operations make sense for it, such as Control-right-click to start a new development object targeted to it, or any of the other operations we'll see next.
While you are at it, try a couple of other ways to create a new Development Window. Go to <code>File</code> <code>--></code> <code>New window</code> ; this creates a new tool, untargeted. The title bar says " <code>Empty development tool #1</code> ". You can get the same effect by clicking the Create New Window icon, leftmost on the top row of buttons, just below " <code>File</code>". The corresponding keyboard accelerator is CTRL- <code>N</code>.
While you are at it, try a couple of other ways to create a new Development Window. Go to <code lang=text>File-->New window</code> ; this creates a new tool, untargeted. The title bar says "<code lang=text>Empty development tool #1</code>". You can get the same effect by clicking the Create New Window icon, leftmost on the top row of buttons, just below " <code>File</code>". The corresponding keyboard accelerator is CTRL-<code>N</code>.

2
documentation/current/eiffelstudio/eiffelstudio-guided-tour/starting-eiffelstudio-and-opening-project.wiki
View File

@@ -13,7 +13,7 @@ On Windows, you can launch EiffelStudio from the Start Menu under
where <span>Version</span> is the version number, e.g. 6.0. Alternatively, you can double-click the icon that the installation procedure will have added to your desktop (if you have selected that option during installation).
If this is the first time you are using EiffelStudio, you may get a dialog asking for an unlock code or inviting you to register the product. See <span> [[Software Installation for EiffelStudio 6.2|your platform installation instructions]] </span> for registration information.
If this is the first time you are using EiffelStudio, you may get a dialog asking for an unlock code or inviting you to register the product. See <span> [[Software Installation for EiffelStudio|your platform installation instructions]] </span> for registration information.
==Launching EiffelStudio under Unix or OpenVMS==

62
documentation/current/eiffelstudio/eiffelstudio-guided-tour/viewing-classes.wiki
View File

@@ -4,15 +4,15 @@
[[Property:uuid|78136af1-5d7a-f3d2-9619-17f4c0541f1e]]
We haven't even looked at a class text yet, but it's important anyway to see how EiffelStudio provides you with numerous, complementary <span>views</span> of your software. The Context Tool is the primary place to look for such views.
We'll need just one Development Window for the moment, the one that was targeted to <code> LIST </code>. You can get rid of the others by closing their windows (through the top right cross mark on Windows and the equivalent in other window managers), or through <code> File </code> <code> --> </code> <code> Close </code> -- but don't select "Exit" which would take you out of EiffelStudio altogether!
We'll need just one Development Window for the moment, the one that was targeted to <code>LIST</code>. You can get rid of the others by closing their windows (through the top right cross mark on Windows and the equivalent in other window managers), or through <code lang=text>File --> Close</code> -- but don't select "Exit" which would take you out of EiffelStudio altogether!
{{note| ''If you don't see a tool targeted to '' <code> LIST </code> '', just retarget one, as you know how to do this now, for example by typing the name followed by Enter in the Class Field at the top left.'' }}
{{note| If you don't see a tool targeted to <code>LIST</code> , just retarget one, as you know how to do this now, for example by typing the name followed by Enter in the Class Field at the top left. }}
First let's give ourselves more space. Right now we don't need the Cluster Tree, Feature Tree and Properties panes. Get rid of them by clicking the close buttons on the top right corner of the panes.
You can get these panes back later by clicking the buttons in the toolbar or by going to the View, Tools Menu.
{{note| ''Another way to hide a pane is to click on the button in the toolbar or by unselecting them in the View, Tools Menu.'' }}
{{note|Another way to hide a pane is to click on the button in the toolbar or by unselecting them in the View, Tools Menu. }}
Two panes remain, showing the Editing Tool and the Context Tool.
@@ -24,70 +24,70 @@ Make sure the Context Tool pane is large enough; you can resize the window and,
The first tab we'll look at is the Class Tab. You'll find it at the bottom of the Context Tool.
This gives you access to many forms of information about the current class -- the target of the Development Window. A set of buttons at the top of the Context Tool enables you to display a number of '''views''' of the class. The currently highlighted button indicates the default view: <code> Ancestors </code>. You can see the others' names by moving the cursor over the various view icons, '''without clicking''', and reading the tooltips.
This gives you access to many forms of information about the current class -- the target of the Development Window. A set of buttons at the top of the Context Tool enables you to display a number of '''views''' of the class. The currently highlighted button indicates the default view: <code>Ancestors</code>. You can see the others' names by moving the cursor over the various view icons, '''without clicking''', and reading the tooltips.
The view currently displayed, <code> Ancestors </code>, shows the inheritance structure that leads to the current target, <code> LIST </code> :
The view currently displayed, <code>Ancestors</code>, shows the inheritance structure that leads to the current target, <code>LIST</code> :
[[Image:index-29]]
This shows that <code> LIST </code> is an heir of <code> CHAIN </code> which itself, as an example of multiple inheritance, is an heir of <code> CURSOR_STRUCTURE </code>, <code> INDEXABLE </code>, and -- twice, as an example of <span>repeated</span> inheritance -- <code> SEQUENCE </code>. If, because of direct or indirect repeated inheritance, a class appears more than once, the display doesn't repeat its ancestry the second and subsequent times; the omitted repetition appears as just three dots, '''...''', as illustrated here for the second occurrences of <code> BAG </code>, <code> ACTIVE </code> and others.
This shows that <code>LIST</code> is an heir of <code>CHAIN</code> which itself, as an example of multiple inheritance, is an heir of <code>CURSOR_STRUCTURE</code>, <code>INDEXABLE</code>, and -- twice, as an example of <span>repeated</span> inheritance -- <code>SEQUENCE</code>. If, because of direct or indirect repeated inheritance, a class appears more than once, the display doesn't repeat its ancestry the second and subsequent times; the omitted repetition appears as just three dots, '''...''', as illustrated here for the second occurrences of <code>BAG</code>, <code>ACTIVE</code> and others.
As you may have guessed, all the class names that appear on this display, by default in blue, can function as hyperlinks: you can use any one of them to retarget the Development Window to the corresponding class. This will be another major retargeting mechanism. But let's not pursue it for the moment and instead continue looking at the documentation views.
Next to <code> Ancestors </code> button is <code> Descendants, </code>which will give you the descendants of a class in a similar format:
Next to <code>Ancestors</code> button is <code>Descendants,</code> which will give you the descendants of a class in a similar format:
[[Image:index-30]]
The progeny of <code> LIST </code>, as you can see, is just as impressive as its ancestry.
The progeny of <code>LIST</code>, as you can see, is just as impressive as its ancestry.
Let's now look at the other formats, starting from the left. The first button, <code> Clickable </code>, gives the class text. It's essentially the same information as appears in the top Editing Tool (whose pane was reduced to its bare minimum in the last few pictures, showing only the first three lines or so), but with some differences:
* The top Text view is editable. In fact it's EiffelStudio's primary tool for entering software texts. The bottom <code> Clickable </code> view is just a view; you can't change it.
* The Text view retains the formatting of the class text the way it was typed in; the <code> Clickable </code> view is automatically formatted -- "pretty-printed" -- according to the standard Eiffel layout rules.
* The <code> Clickable </code> view does not include comments inside routine implementations ( <code> do </code> and <code> once </code> clauses), although it does retain features' header comments.
* As part of the pretty-printing, the <code> Clickable </code> view uses colors and fonts to distinguish keywords, identifiers, comments and other syntactical elements. You can change the fonts and colors, like many other elements of the interface, through <code> Tools </code> <code> --> </code> <code> Preferences </code>. (Now is not the time.)
Let's now look at the other formats, starting from the left. The first button, <code>Clickable</code>, gives the class text. It's essentially the same information as appears in the top Editing Tool (whose pane was reduced to its bare minimum in the last few pictures, showing only the first three lines or so), but with some differences:
* The top Text view is editable. In fact it's EiffelStudio's primary tool for entering software texts. The bottom <code>Clickable</code> view is just a view; you can't change it.
* The Text view retains the formatting of the class text the way it was typed in; the <code>Clickable</code> view is automatically formatted -- "pretty-printed" -- according to the standard Eiffel layout rules.
* The <code>Clickable</code> view does not include comments inside routine implementations ( <code>do</code> and <code>once</code> clauses), although it does retain features' header comments.
* As part of the pretty-printing, the <code>Clickable</code> view uses colors and fonts to distinguish keywords, identifiers, comments and other syntactical elements. You can change the fonts and colors, like many other elements of the interface, through <code lang=text>Tools --> Preferences</code>. (Now is not the time.)
This view is called "clickable" because, as we'll see later, every syntactical element on it is a hyperlink, which you can use for browsing.
After <code> Clickable </code> comes the <code> Flat </code> view button. The layout of the result is similar. The flat form of a class is the reconstructed class text including not only what's declared in the class itself but also everything that it inherits from its ancestors, direct or indirect. This applies to the flat form's features, which include ancestor features, but also to contracts: the flat form's invariant includes all clauses from ancestors' invariants, and the preconditions are expanded to take <code> require else </code> and <code> ensure then </code> clauses into consideration. (The <span> [[An Eiffel Tutorial|Eiffel Tutorial]] </span> explains these notions in detail.)
After <code>Clickable</code> comes the <code>Flat</code> view button. The layout of the result is similar. The flat form of a class is the reconstructed class text including not only what's declared in the class itself but also everything that it inherits from its ancestors, direct or indirect. This applies to the flat form's features, which include ancestor features, but also to contracts: the flat form's invariant includes all clauses from ancestors' invariants, and the preconditions are expanded to take <code>require else</code> and <code>ensure then</code> clauses into consideration. (The <span> [[An Eiffel Tutorial|Eiffel Tutorial]] </span> explains these notions in detail.)
As a result, the <code> Flat </code> view shows the class text as it might have come out had inheritance (what a horrible thought even to contemplate!) <span>not</span> been available to write it.
As a result, the <code>Flat</code> view shows the class text as it might have come out had inheritance (what a horrible thought even to contemplate!) <span>not</span> been available to write it.
The first two features appearing in the above display, <code> cursor </code> and <code> first </code>, are indeed inherited from ancestors, rather than declared in <code> LIST </code> itself. Note how EiffelStudio, when producing the flat form, adds a line of the form
The first two features appearing in the above display, <code>cursor</code> and <code>first</code>, are indeed inherited from ancestors, rather than declared in <code>LIST</code> itself. Note how EiffelStudio, when producing the flat form, adds a line of the form
<code>
-- (From CLASS_OF_ORIGIN)
</code>
to the header comments of inherited routines, to document where they come from.
The flat form is an important notion of object technology, making it possible to understand a class by itself, regardless of the possibly rich inheritance structure that led to it. Looking at the Flat view of <code> LIST </code>, you may note how few of its properties come from the class itself; most of the interesting work has been done in ancestors, and <code> LIST </code> just adds a few details.
The flat form is an important notion of object technology, making it possible to understand a class by itself, regardless of the possibly rich inheritance structure that led to it. Looking at the Flat view of <code>LIST</code>, you may note how few of its properties come from the class itself; most of the interesting work has been done in ancestors, and <code>LIST</code> just adds a few details.
{{note| ''If at any time you want to search for a certain pattern in the views displayed, click the '' <code> Search </code> '' button at the top of the window, or type CTRL-'' <code> F </code>. ''A self-explanatory Search Tool will come up, with various options such as '' <span> ''Match case'' </span> '' and '' <span> ''Whole word'' </span> }}
{{note|If at any time you want to search for a certain pattern in the views displayed, click the <code>Search</code> button at the top of the window, or type <code>CTRL-F</code>. A self-explanatory Search Tool will come up, with various options such as ''Match case'' and ''Whole word'' }}
Next come two essential documentation views: <code> Contract </code> and <code> Flat Contract </code>. Based on Eiffel's principles of Design by Contract, they document the interface properties of a class. Unlike the previous two, they do not show actual Eiffel texts, but information useful for client classes.
Next come two essential documentation views: <code>Contract</code> and <code>Flat Contract</code>. Based on Eiffel's principles of Design by Contract, they document the interface properties of a class. Unlike the previous two, they do not show actual Eiffel texts, but information useful for client classes.
The contract form (also known as the '''short form''' of a class) is the class text deprived of any internal detail to retain interface information only. It discards any feature that's not exported (available to all clients); for the retained features, it discards the implementation -- <code> do </code> or <code> once </code> clause -- but retains the header (feature name, arguments, results), the header comment, and the contracts (precondition, postcondition, invariant) minus any contract clause that refers to a non-exported feature and hence would be useless to clients.
The contract form (also known as the '''short form''' of a class) is the class text deprived of any internal detail to retain interface information only. It discards any feature that's not exported (available to all clients); for the retained features, it discards the implementation -- <code>do</code> or <code>once</code> clause -- but retains the header (feature name, arguments, results), the header comment, and the contracts (precondition, postcondition, invariant) minus any contract clause that refers to a non-exported feature and hence would be useless to clients.
As you will know, particularly if you have read the book <span> [http://eiffel.com/doc/oosc/ Object-Oriented Software Construction] </span> , the contract form is the preferred way of documenting software elements, especially reusable components, as it provides clients with just the right level of abstraction: precise enough thanks to the type signature and the contracts; clear enough thanks to the header comments; and general enough since it omits implementation details that are irrelevant to client programmers (and might lead them to write client code that won't work any more if the implementation changes).
As you will know, particularly if you have read the book <span> [http://eiffel.com/doc/oosc/ Object-Oriented Software Construction] </span>, the contract form is the preferred way of documenting software elements, especially reusable components, as it provides clients with just the right level of abstraction: precise enough thanks to the type signature and the contracts; clear enough thanks to the header comments; and general enough since it omits implementation details that are irrelevant to client programmers (and might lead them to write client code that won't work any more if the implementation changes).
In practice you will often want to use, instead of the <code> Contract </code> view, the next one, <code> Flat Contract </code>, also known as "flat-short form" and "interface form", which applies the same rules to the flat form rather than to the original class. This means it shows information on all the features of the class, immediate (defined in the class itself) as well as inherited, whereas the short form, non-flat, only considers immediate features. The <code> Flat Contract </code> view provides the complete interface information for the class. Try it now on class <code> LIST </code>.
In practice you will often want to use, instead of the <code>Contract</code> view, the next one, <code>Flat Contract</code>, also known as "flat-short form" and "interface form", which applies the same rules to the flat form rather than to the original class. This means it shows information on all the features of the class, immediate (defined in the class itself) as well as inherited, whereas the short form, non-flat, only considers immediate features. The <code>Flat Contract</code> view provides the complete interface information for the class. Try it now on class <code>LIST</code>.
The next two buttons are for the <code> Ancestors </code> and <code> Descendants </code> views, which we have already seen, showing classes connected with the target through one of the two inter-class relations, inheritance. After them come <code> Clients </code> and <code> Suppliers </code>, to list the classes connected through the other relation, client. Clicking the <code> Clients </code> button shows the (empty) list of clients of <code> LIST </code>.
The next two buttons are for the <code>Ancestors</code> and <code>Descendants</code> views, which we have already seen, showing classes connected with the target through one of the two inter-class relations, inheritance. After them come <code>Clients</code> and <code>Suppliers</code>, to list the classes connected through the other relation, client. Clicking the <code>Clients</code> button shows the (empty) list of clients of <code>LIST</code>.
No class of this system directly uses <code> LIST </code> as client, although some use its descendant <code> ARRAYED_LIST </code>. Now click the next button to see the <code> Suppliers </code> of <code> LIST </code>.
No class of this system directly uses <code>LIST</code> as client, although some use its descendant <code>ARRAYED_LIST</code>. Now click the next button to see the <code>Suppliers</code> of <code>LIST</code>.
The only two classes that <code> LIST </code> needs for its own algorithms are basic types from the Kernel Library, <code> BOOLEAN </code> and <code> INTEGER_32 </code>. In Eiffel, as you may remember, all types are defined by classes, even those describing such elementary values as integers and booleans.
The only two classes that <code>LIST</code> needs for its own algorithms are basic types from the Kernel Library, <code>BOOLEAN</code> and <code>INTEGER_32</code>. In Eiffel, as you may remember, all types are defined by classes, even those describing such elementary values as integers and booleans.
==Feature information in the Class View==
Let's resist the natural urge to go see now what the classes <code> INTEGER_32 </code> and <code> BOOLEAN </code> look like, and instead continue our survey of views. The remaining views will all display information about the '''features''' of the class. The first of them, <code> Attributes </code>, lists the attributes. It's not very interesting for <code> LIST </code>, a deferred class with only one attribute -- you can check this for yourself by clicking the <code> Attributes </code> button -- so let's look at the next one. Click the <code> Routines </code> button now to display information about the routines of class <code> LIST </code> :
Let's resist the natural urge to go see now what the classes <code>INTEGER_32</code> and <code>BOOLEAN</code> look like, and instead continue our survey of views. The remaining views will all display information about the '''features''' of the class. The first of them, <code>Attributes</code>, lists the attributes. It's not very interesting for <code>LIST</code>, a deferred class with only one attribute -- you can check this for yourself by clicking the <code>Attributes</code> button -- so let's look at the next one. Click the <code>Routines</code> button now to display information about the routines of class <code>LIST</code> :
[[Image:index-36]]
The sections of this display group routines according to the ancestors of <code> LIST </code> -- including <code> LIST </code> itself -- that first introduced them; for example (second and third sections) <code> extendible </code> originally comes from <code> COLLECTION </code> and <code> extend </code> from <code> BAG </code>. Much of the benefit of this display comes from its support for browsing: all the colored elements, representing classes and features, will be "clickable" hyperlinks.
The sections of this display group routines according to the ancestors of <code>LIST</code> -- including <code>LIST</code> itself -- that first introduced them; for example (second and third sections) <code>extendible</code> originally comes from <code>COLLECTION</code> and <code>extend</code> from <code>BAG</code>. Much of the benefit of this display comes from its support for browsing: all the colored elements, representing classes and features, will be "clickable" hyperlinks.
The remaining Class View buttons all display information in the same format. Each selects a specific subset of the target class's features. The last two selected attributes and routines. You can now try any of the others by clicking the corresponding button:
* <code> Deferred </code> features: abstract features which don't have an implementation in the current class, only in eventual descendants. Try this for <code> LIST </code> ; you'll see that this deferred class indeed has a number of deferred features.
* <code> Once and constants </code> : constant attributes, "once functions" which provide shared objects (close to the "singleton" pattern), and once procedures which provide a convenient initialization mechanism. <code> LIST </code> has 'Operating_environment' and 'Io' inherited from the parent class ANY.
* <code> External </code> features, implemented as calls to routines, macros or other elements implemented in other languages. <code> LIST </code> hasn't any.
* <code> Exported </code> features: those available to all clients. <code> LIST </code> has quite a few.
* <code>Deferred</code> features: abstract features which don't have an implementation in the current class, only in eventual descendants. Try this for <code>LIST</code> ; you'll see that this deferred class indeed has a number of deferred features.
* <code>Once</code> and constants: constant attributes, "once functions" which provide shared objects (close to the "singleton" pattern), and once procedures which provide a convenient initialization mechanism. <code>LIST</code> has 'Operating_environment' and 'Io' inherited from the parent class ANY.
* <code>External</code> features, implemented as calls to routines, macros or other elements implemented in other languages. <code>LIST</code> hasn't any.
* <code>Exported</code> features: those available to all clients. <code>LIST</code> has quite a few.