IBM
Contents Index Previous Next



Text Files


The Text Editor works with ASCII text files. The text editor can be used to view, edit and print text files. In addition to providing typical text editor functions, the Text Editor provides special support for embedding link endpoints into the text. For more information on links and endpoints, see Implinks and Endpoints.

Note:

The Text Editor is only available if the Organizer is started with the preference SDT*TextEditor set to "SDT".

Endpoint Support

In the Text Editor, endpoints are user-defined, non-overlapping, contiguous ranges of characters, possibly spanning several lines of text, that are made visible to other tools, allowing you to define links between fragments in your text and endpoints in other documents.

Endpoints are displayed in the text editor by underlining the range of characters that are part of the endpoint.

Note that when you define an endpoint, you do not impose any particular restrictions on the text in the endpoint, meaning that you can still edit the text in the endpoint using the normal text editing functions to modify the endpoint's contents. The text editor dynamically notifies other tools the changes you make to your endpoints as you make your changes, to make sure that the view of the endpoints in your file is always current.

Considerations when Using Text Endpoints

The requirement that endpoints must be non-overlapping means that you cannot create an endpoint inside another endpoint. Also, while an endpoint is allowed to span several lines, it is generally best to restrict endpoints to small, well-defined fragments of text on a single line, used as external reference points to the information in your files.

Also note that while the Text Editor visualizes endpoints by simply underlining the text in the endpoints, the endpoints are stored in your actual text files using special keywords before and after the characters in the endpoint. This means that it is not advisable to view or edit text documents with endpoints in a text editor that is not aware of the special significance of these keywords. If you do so, you should be careful so as to not destroy information about the endpoints in the file, as this could cause links attached to these endpoints to break.

Another consequence of how the Text Editor stores the endpoint information is that if you are editing text documents that are intended as input to other tools (such as a C or C++ compiler) you should take care to place endpoints only within commented regions of text. This makes sure that the extra text inserted when storing the endpoints does not conflict with the allowed grammar of the type of file you are editing.

Examples

In the examples below you will find typical placements of text endpoints. These endpoints could then be the basis for creation of links into requirements, analysis, design, and specification documents, to name only a few possibilities.

Example 23

Improperly commented C header with endpoints:

/* Primary protocol packet */
struct Packet { ... };

Properly commented C header with endpoints:

/* Primary protocol packet */
struct Packet { ... };

Example 24

Improperly commented C++ header with endpoints:

class Base {
	 	 	 	 	 	 	 
virtual char *name() const = 0;
	 virtual int size() const = 0;
	 	 	 ...
}

Properly commented C++ header with endpoints:

// class Base
class Base {
	 	 	 	 	 	 	 
virtual char *name() const = 0;  // get name
	 virtual int size() const = 0;    // get size
	 	 	 ...
}


http://www.ibm.com/rational
Contents Index Previous Next