Totally Objects - Readability (Version 5.5 [1.0])

Introduction

Readability from Totally Objects can be used to reformat VisualAge Smalltalk source code in your image according to your preferences to make it more readable when browsing and editing. It does not just change the representation of the source code in the browsers but actually applies the changes to the ENVY database. A second feature allows source code to be 'filed out' to disc in either plain ASCII, Rich Text or HTML. The file out process will not change your Envy database but can be used to produce documentation. The formatting preferences are called 'Profiles' and are kept in your Envy database.

Installation

This product has been packaged as three configuration maps. To import them into your library select 'Browse Configuration Maps' from the 'Tools' menu of the 'System Transcript'. In the 'Configuration Maps Browser' select 'Import...' from the 'Names' menu and select the file readability5-5_1-0-*.dat. You should then select the three configuration maps contained within this file:

To load the configuration maps into your image select each of them in the 'Configuration Maps Browser' select 'Load With Required Maps' from the 'Editions' menu.

Operation

The Readability Menu

All Readability functionality is accessible by the 'Readability' cascade menu which appears in the 'Tools' menu in the System Transcript. A second menu can also be found in 'Tools' menu in the VisualAge Organizer which; this has similar functionalty to the first except that the menu items change depending on the selections in the Organizer.

The Profile Manager

This is used to create and edit your profiles. To open the window select 'Profile Manager' from the 'Readability' menu.

Creating Profiles

Select 'New...' from the 'Profile' menu. You will be asked for the name of the new profile. After pressing 'OK' a new profile will be created with initial settings the same as the previously selected profile.

Editing Profiles

To edit a profile select it in the drop-down list and then just change the settings in the tabbed pages. An explanation of the different categories is given below:

[Blocks]

You can specify if a block should be displayed on a single line if the block only contains a single line. If any variables defined in a block (or in a method) are followed by comments then the variable declaration can span across multiple lines. The closing bracket ']' of a block can appear on a new line (under the opening bracket) or immediatley after the last operation in the block. Blocks that are displayed on more than one line will be indented.

[Selectors]

The colons used in selectors can be followed by a space. If a selector has more than one part (such as #at:put:) then each part can appear on a seperate line. For example,

or,

For binary selectors (such as + and ==) a space can be put before, after or both. To change the spacing for a particular binary selector, select it, right click, and then choose the setting you require. The selector will be moved to the appropriate list.

[Assignments]

You can put spaces before and after the ':=' in an assignment.

[Methods]

If comments appear in your methods between the definition and the body (or declared variables) then a blank line can be inserted. Similarly, a blank line can be inserted before the body which can be indented.

[Text]

(applys only when filing out as Rich Text or HTML)

You can specify the colour and style of components of your source code. For instance, comments can be italic yellow whilst variables can be bold red.

Examples

The bottom half of the window shows how particular methods look with the selected profile (except the 'Text' settings). Further examples can be added by selectin 'New...' from the 'Examples' menu. You will be asked to give the class and then the methods you wish to add.

The System Transcript

When reformatting or filing out source code Readability produces progress information. This information will be displayed in the System Transcript if the 'Put Progress In Transcript' option is checked in the 'Readability' menu.

Reformatting Source

The source code of a whole application, a class or just a single method can be reformatted. The reformatting process will apply the styles specified in a chosen profile and create new editions of the methods in the Envy database. Reformatting tasks are initiated from the 'Reformat Source' cascade menu in the 'Readability' menu.

Reformatting an Application:

Select 'Application...' from the 'Reformat Source' menu.
You will need to enter the name of the application you wish to reformat. If the application has sub-applications you will be asked if you wish to reformat those also. You will then be asked to select the profile you wish to use. If the application is versioned then you will be asked to make it a scratch edition. All methods in the application will then be reformatted.

Reformatting a Class:

Select 'Class...' from the 'Reformat Source' menu.
After entering the name of the class you wish to reformat, you will be asked to select the applications (defiining and extending the class) to include. For instance if a class is defined in App1 and extended in App2, you can choose to reformat only the methods of the class that are in App1, App2 or both. You will then need to select a profile. For each of the applications you have selected that are versioned, you will be asked to make scratch editions. If you choose not to make a particular application a scratch edition then methods of that class will not be reformatted.

Reformatting a Method:

Select 'Method...' from the 'Reformat Source' menu.
You will be asked for the name of the class that contains the method. Then you must specify whether it is a class or instance method. Then you should select the name of the method. After selecting the profile to use your method will be reformatted. If the application containing the method is versioned then you will first need to make it a scratch edition.

Filing Out

The source code of a whole application, a class or just a single method can be filed out. The reformatting process will apply the styles specified in a chosen profile in either ASCII, RTF or HTML. All the source, just the name, or the name and leading comments (useful for creating manuals) of a method can be filed out.

Filing Out an Application:

Select 'Application...' from the 'File Out' menu.
You will need to enter the name of the application you wish to file out. You will then be asked to select the profile you wish to use. Next, you should select the format required and lastly the method groups (see below) that you wish to include. You then ned to specify whether all the source the name, or the name and leading comments of each method should be included. Lastly you will need to give the name of the file to create. The source code will then be filed out with the styles specified in the profile.

Filing Out a Class:

Select 'Class...' from the 'File Out' menu.
This process is identical to filing out an application except that a class name is entered and you will not need to select a method group.

Filing Out a Method:

Select 'Method...' from the 'File Out' menu.
This process is identical to filing out an application except that a method is specified as when reformatting a method, and you will not need to select a method group.

Method Groups

Sometimes when you are filing out applications it is convenient to include only those methods that are in a certain category and only those that are public. To group categories together in such a way you need to create instances of the class ReadabilityCategoriesProfile using any of the methods #name:private:, #name:public: or #name:publicAndPrivate:. The first argument of each is the name for the group and the second is a collection of category names (i.e. a collection of Strings). You will also need to add a class method called #readabilityCategoryGroups to your application's class that answers an OrderedCollection of the ReadabilityCategoriesProfile objects. An example is given below:


Further Information