(UNIX Only)
On UNIX, Emacs can be used as an external text editor in Telelogic Tau. By configuring Telelogic Tau to use Emacs for handling text documents, the Organizer can interact with Emacs in the same way as with the other Editors.
Handling of SOMT implementation links is supported.
This chapter contains a user manual to Emacs in Telelogic Tau; the functionality it adds and the new commands.
The implementation works with GNU Emacs version 19.31 or later, and only on UNIX systems. It does not work with any Emacs for Windows.
It is assumed that you are familiar with Emacs terminology and how to use Emacs. Some experience with installing Emacs Lisp packages is also required when setting up the integrated environment.
By setting preferences to use Emacs as text editor in Telelogic Tau, text editing support in Emacs is offered both from the Organizer and editors. Text document handling is implemented in the Lisp package "sdtemacs".
In the Organizer, text documents are identified by the document type "Text Plain" when you add new or existing documents. A new Emacs instance will always be started, even though there may exist one already (started from outside Telelogic Tau).
The Lisp package "sdtlinks" defines the minor mode SDTlinks which supports SOMT implementation links in text documents. This gives the possibility to handle link endpoints and follow the links defined for these endpoints. The support for link handling is optional.
When the SDTlinks mode is active, endpoints are displayed with a typeface differing from the plain text. Type faces for endpoints with and without links are configurable, see Type Faces for Endpoints.
To be able to represent endpoints in text files, the file contents differ from what is seen in the Emacs buffer containing a file with endpoints. The file format for endpoints look like this:
<SDT_LINK_ENDPOINT_BEGIN anchor >text<SDT_LINK_ENDPOINT_END>
where anchor is an integer uniquely identifying the endpoint and text is the endpoint text. If the SDTlinks mode is inactive, this raw file contents is displayed in the Emacs buffer.
|
When the SDTlinks mode is inactive: Do not alter any text representing endpoints (described in Link Handling). Do not duplicate text containing endpoints since this will yield unpredictable results as each endpoint is uniquely identified in a file. |
As a general principle, Undo is not available for the link handling commands.
To be able to use Emacs as an external editor in Telelogic Tau:
sdtemacs.el in a Lisp directory known to Emacs (load-path). By default, the file is installed in $telelogic/include/lisp.sdtemacs.el for increased execution speed.(require 'sdtemacs) ~/.emacs file or in the file default.el in the ../lisp directory of the Emacs distribution.Make sure that the environment variable $telelogicbin is correctly set.
To be able to use link handling functions in Emacs:
sdtlinks.el in a Lisp directory known to Emacs (load-path). By default, the file is installed in $telelogic/include/lisp.sdtlinks.el for increased execution speed.(require 'sdtlinks) ~/.emacs file or in the file default.el in the ../lisp directory of the Emacs distribution.Sdtlinks requires sdtemacs, that is, you must install sdtemacs in order to use sdtlinks.
An example of using both packages:
(setq load-path (cons (substitute-in-file-name "$telelogic/include/lisp") load-path)) (require 'sdtemacs) (require 'sdtlinks)
In the Preference Manager, the following parameters should be set:
| Parameter | Value |
|---|---|
|
SDT* TextEditor |
Emacs |
|
SDT* EmacsCommand |
The command that starts GNU Emacs from a UNIX shell (the default is "emacs"). |
The type face for endpoints without associated links is called sdtlinks-endpoint-face. The default appearance is underlined, blue text.
The type face for endpoints with associated links is called sdtlinks-endpoint-with-links-face. The default appearance is underlined, bold, blue text.
These type faces can be redefined.
An example to make endpoints without associated links appear as bold, red text:
... (make-face 'sdtlinks-endpoint-face) (make-face-bold 'sdtlinks-endpoint-face nil t) (set-face-foreground 'sdtlinks-endpoint-face "red") ... (require 'sdtlinks)
Due to the nature of the execution environment for Emacs, only a finite number of endpoints are manageable in a document. By default, this limit is set to 1000 endpoints, which should be sufficient for most situations. If, however, a larger number is required, this can be achieved by setting the variable sdtemacs-max-no-of-endpoints.
An example to allow 1500 endpoints:
... (setq sdtemacs-max-no-of-endpoints 1500) ... (require 'sdtlinks)
This section lists and describes the Emacs commands and key bindings associated with the integration with Telelogic Tau. Both new commands and the affected ordinary (existing) commands are described.
M-x sdtemacs-connect connects to Telelogic Tau. Automatic connection can be performed when starting Emacs by providing the UNIX command switch post (emacs -post). This is done when Telelogic Tau starts Emacs.
M-x sdtemacs-disconnect disconnects from Telelogic Tau. All buffers taking part in the interaction with Telelogic Tau will be unloaded after asking about saving modified buffers. Exiting Emacs will disconnect from Telelogic Tau.
M-x sdtemacs-show-organizer opens or raises the Organizer Main window.
M-x sdtemacs-show-reference shows an SDT reference in an appropriate editor. This requires that the reference text is selected or that the point is placed inside it.
Disconnects from Telelogic Tau before exiting.
The new buffer is notified to Telelogic Tau and takes part in the interaction with Telelogic Tau.
The loaded buffer is notified to Telelogic Tau and takes part in the interaction with Telelogic Tau.
The buffer is notified as saved to Telelogic Tau.
The buffer is notified as unloaded to Telelogic Tau.
The buffer is notified as modified to Telelogic Tau.
The minor mode SDTlinks, which implements the link handling commands, requires that Emacs is connected to Telelogic Tau, and will try to connect when switched on if this is not the case. All buffers loaded when connected will automatically have this mode active.
M-x sdtlinks-mode toggles the minor mode SDTlinks. This is useful if performing editing operations that cannot be done without unintentionally deleting endpoints, e.g. moving (Cut and Paste) a region of text containing endpoints.
|
When SDTlinks is inactive: Do not alter any text representing endpoints (described in Link Handling). Do not duplicate text containing endpoints since this will yield unpredictable results as each endpoint is uniquely identified in a file. |
M-x sdtlinks-create-endpoint (C-c C-c) creates a new endpoint that will be marked with a special type face in the text (see Type Faces for Endpoints) and notified to Telelogic Tau. This command requires that the region of text to convert to an endpoint is selected, i.e. both mark and point must be set. Endpoints are not allowed to overlap and must consist of at least one character.
M-x sdtlinks-delete-endpoint (C-c C-d) deletes an endpoint. The endpoint text will be converted to plain text and the deletion will be notified to Telelogic Tau. All links associated with the endpoint will be cleared. This command requires that point is placed inside the endpoint text.
M-x sdtlinks-follow-link (C-c C-f) follows one of the links associated with the selected endpoint. This results in displaying the endpoint on the other end of the link in an appropriate editor. If only one link is associated with the endpoint, this link is followed. Otherwise, a choice between the associated links is offered in a popup menu:
Figure 139 Choose link to follow
|
|
Each menu item, representing a link, is of the format:
<Link name>(<Direction>), <Other endpoint>(<Type>), <File>
where:
<Link name> = The name of the link <Direction> = The direction of the link: `in' or `out' <Other endpoint> = The name of the other endpoint of the link <Type> = The type of the other endpoint of the link <File> = The name of the file (including the path) in which the other endpoint resides
This command requires that point is placed inside the text of an endpoint marked as having associated links, see Type Faces for Endpoints.
M-x sdtlinks-show-endpoint-in-link-manager (C-c C-s) opens the Link Manager and shows the selected endpoint. This requires that point is placed inside the endpoint text.
The endpoint is notified as modified to Telelogic Tau. When point is placed directly after the endpoint text, added characters will become part of the endpoint text.
For all endpoints within the region, Delete Endpoint (see Delete Endpoint) is executed.
Endpoints in the copy of the region is represented as plain text.
For all endpoints in the inserted file, Create Endpoint (see Create Endpoint) is executed. Associated links are not handled.
If point is within an endpoint and the file to insert have endpoints, the operation will fail since overlapping endpoints are not allowed.
No undo information is recorded for the link handling commands. Consequently, these commands cannot be undone.