7 Creating, opening and saving documents

7.1 Creating a new document

A new document can be created using the command ``Create a document'' from the ``Files'' menu in the Thot window. This command displays a form with three parts

• The ``Document directories'' field allows you to choose the Unix directory in which you want to create the document. Just click on the required directory name with the left mouse button. The directory list comes from the THOTDOC configuration parameter and it can be updated by using the Environment menu (see section 7.9). It is also updated when you edit the name of the ``Document name'' field in the same form: the directory part of the name is added to the list if the directory contains Thot documents and is not already present in the list.
• The ``Document type'' list allows you to specify the structure schema which will serve as a model for the new document. That list is built according to information from the .language file (see section 23.3). To create a document with a structure schema which does not appear in the list, type the name of the schema in the input area placed under the list.
• The ``Document name'' area is updated from the choice made in the ``Document directories'' field. It can also be directly edited to enter the full name (including the directory) of a file. If the directory contains Thot documents and does not appear in the list of document directories, it is automatically added. By default, the editor proposes a ``No_name'' document name for any new document.

Once these three parameters have been specified, click on the ``Confirm'' button in the form. If a document with the same name already exists, the editor displays a form which allows you to irm the creation or to come back to the previous form in order to change the name or the directory of the document to be created.

If names are different or if the user irmed the creation request in case of lict, a new document is created and one or several windows appear on the screen (these windows are specified in the .conf file, see section 23.2). You can then edit the document. The structure of that new document is consistent with the minimum defined by its structure schema.

The file that will contain the document is not created immediately. It is created as soon as the document is saved, either automatically or by using an explicit command (see section 7.5).

7.2 Opening an existing document

The Thot editor can work on several documents at the same time. As a result, a new document can be opened while others are already opened. However, the number of windows and the number of documents simultaneously opened are limited (a document can have several windows, see section 9). The maximum number of windows opened by the editor is specified in section 26. If the editor cannot open a document because of the number of windows already opened, it displays the following message: ``Cannot open new window. Close another window''. You then have to close one or several document windows (see section 9.1) before issuing the opening command again.

The ``Files'' menu of the Thot window allows you to open a document which has been previously saved to an Unix file (see section 7.5). The entry ``Open a document'' displays a form with three fields:

• The ``Document directories'' field allows you to choose the Unix directory which contains the document to be opened. Just click with the left mouse button on the required directory name. The list can be updated by using the ``Environment'' menu (see section 7.9). It is also updated when you edit the ``Document name'' area of the same form: the directory part of that name is added to the list if the directory contains Thot documents and is not already present in the list.
• The ``Files'' list enables the required document to be selected by just clicking on its name with the left mouse button. This list displays all Thot documents contained in the directory selected in the previous field. The list is updated when you choose another directory. You can edit the name of the document to be opened in the area located under the list.
• The ``Document name'' area is updated from the choices made in both previous fields. It can also be directly edited, for instance to type the full name (including the directory) of a file which cannot be found in directories of the ``Document directories'' list. In such case, once the document has been opened, the list ``Document directories'' is completed.

When the ``Document name'' area contains the name of the required file (the .PIV extension is not mandatory), click on the ``Confirm'' button to open the document. If an error occurs while opening a document, a message appears in the Thot window.

You can also double-click on an external reference (see section 5.4) to open a document. In this case, the order of document directories in the list is important. It indicates the order in which the editor consults directories when it searches for the document to be opened. In external references, the editor does not store the directory of the referenced document. The user must inform the editor of his working context (all schema, document and image directories) so that documents are correctly loaded while the editor is started. The working context is defined by the configuration parameters described in sections 7.9.1 and 23.1.5.

Whatever the method used for opening the document, when it is loaded, one or several windows appear on the screen (these windows are specified in the .conf file, see section 23.2.2). You can then edit the document. These windows are similar to those displayed when creating a document of the same type.

7.3 Importing a document

The form used for opening a document (see 7.2) allows text files (ASCII or ISO-Latin-1) to be opened by Thot and to be edited as Thot documents.

The form ``Open a document'' of the ``Files'' menu only lists Thot documents (filenames ending with .PIV), but another name can be entered either in the input area placed under the list or in the ``Document name'' area. If the file is not a Thot document, when you click on the ``Confirm'' button a form is displayed which lists the possible structure schemas that can receive text files. This list is built from the .language file (see section 23.3). Once you have chosen the document type, the document is opened.

The structure of the imported document is quite simple. It consists of a sequence of paragraphs where a blank line in the input file is interpreted as a break between two paragraphs. If you want to import the file into a document of type File, the lines are copied as they are. The original document is not restructured: it is considered as a sequence of character strings whose content is never interpreted (for instance LaTeX commands are displayed as they are on the screen).

7.4 Closing a document

When you have completed your work on a document, you can close it. To do this, use the ``Document'' menu in the menu bar located at the top of one window of the document to be closed. Then, select the entry ``Close that document''.

• If the document has not been modified since it has been opened, all document windows are closed.
• If the document has been modified, a form is displayed to save the document:
  • ``Done'' closes the form and cancels the closing procedure: nothing else happens.
  • ``Save the document'' saves the document to the file specified when the document was opened or created. The document is then closed.
  • ``Close, don't save'' just closes the document. All changes made since the last saving are lost.

  No other operation can be performed as long as you do not select one of these buttons.

7.5 Saving a document

You can save a document without closing it by using the ``Document'' menu in the menu bar at the top of one window of the document to be saved. You can select one of the following entries:

• ``Save'' immediately saves the document to the file specified when the document was opened or created (see section 7.1).
• ``Save as'' displays a form which allows the document to be saved, moved, copied, renamed or exported. The different operations are presented in sections 7.7 and 7.8. If you just want to save the document, click on the ``Save'' button.

In addition to backup copies made by the user, the Thot editor automatically saves the document as soon as a certain number of characters have been typed and/or a certain number of edit commands have been issued [3]. That number can be chosen by the user with the ``Autosave'' entry from the ``Document'' menu. The form ``Nb char before save'' is then displayed. It may be different for each document. To cancel autosaving, just assign the value 0 to the number of characters before save.

Autosaving produces in the document directory (the one which is displayed in the ``Document directory'' field of the ``Save as'' form) a file with the same name as the document but with the .BAK suffix. This file can be used to restore a document which would have not been explicitly saved because of an unexpected failure in Thot (see section 7.6) or because of an involuntary close of the document without saving it.

7.6 Document files

The close after saving procedure (see section 7.4) and the explicit backup commands (see section 7.5) save the document according to a format specific to Thot, the pivot format. These backups are placed in a file having the name of the document and followed by the .PIV suffix. The .PIV file produced with backup commands does not delete the existing file: the previous .PIV file is renamed .OLD before the .PIV file is created. However, the previous .OLD file is lost. If a backup has been made by mistake, you can restore the previous version of a document by renaming the .OLD file .PIV. Note that only the last version is available.

When the user opens a document (see section 7.2), the editor always loads the .PIV file.

During autosaving (see section 7.5), Thot produces .BAK files. These files contain the same things as the .PIV files which are created simultaneously with the explicit backup command. In case of unexpected failure of the editor, the .BAK file can be renamed .PIV and the document can be opened again: it contains the things saved during the last autosaving.

The .BAK file is automatically deleted by the editor when the user saves the document (``Save'' command or ``Close'' command with backup). The .BAK file is not deleted when the user closes the document wihout saving it.

If the editor detects an error, each opened document is saved before the editor shuts down. As this type of backup occurs in dubious conditions, the .PIV, .OLD, and .BAK files are not deleted and a .SAV file is created: it contains the pivot form of the document at the time of the error. You can restart from the .SAV file after it has been renamed .PIV. However, it would be wise to store the last .BAK or .PIV file in case the .SAV file is incorrect.

It is recommended to ensure that document directories are not encumbered with unnecessary .BAK or .SAV files.

Thot only produces the pivot form of a document in .PIV, .OLD, .BAK and .SAV files; it also creates PostScript files with the ``Print'' command (see section 11) and other types of files with the ``Save as'' command (see section 7.8).

The editor can also associate other types of files with each document: a .DIC file containing the spelling dictionary specific to the document (see section 21), a .EXT file describing the incoming external references of the document and a .REF document presenting the changes to be made on the outgoing external references. These files are managed by the editor and must not be directly modified, renamed, moved or deleted with Unix commands.

7.7 Copying, renaming and moving documents

You can copy, change the name of documents and move them by using the ``Save as'' command from the ``Document'' menu. This command displays a form: keep the Thot format and change the document name or the document directory or both and select either of two entries in the ``Save'' submenu:

• The ``Document directories'' field allows you to choose the Unix directory in which the document must be saved. Just click on the required directory name with the left mouse button. The list of directories can be updated by calling the ``Environment'' menu (see section 7.9). It is also updated when you edit the name of the ``Document name'' field of the same form: the directory part of the name is added to the list if the directory contains Thot documents and is not already present in the list.
• The ``Document name'' area is updated from the choice made in the ``Document directories'' field. It can also be directly edited to enter the full name (including the directory) of a file. If the directory contains Thot documents and does not appear in the list of document directories, it is automatically added. Initially, the editor proposes the current name of the loaded document.
• The ``Save'' submenu allows you to:
  • ``Copy'': the old file remains unchanged and the document is saved in its current state to the required file.
  • ``Rename'': the old file is deleted and the document is saved in its current state to the required file.

In both cases, hypertext links which relate the document to other documents are updated. That is why Thot document files must not be handled with the Unix file management commands (cp, mv, rm, etc.), but only through the editor commands. Document recovery made from .OLD, .BAK and .SAV files (see section 7.6) constitutes the only exception to the rule.

7.8 Exporting documents

The format in which Thot stores documents (pivot format indicated by the .PIV suffix) is not suited to all applications likely to handle a document. That is why a Thot document can be saved to a file in another form. This operation is performed in the same way as an ordinary backup: use the ``Save as'' command (see sections 7.5 et 7.7) and select the required backup format.

Backup formats offered by the form depend on the document type. New backup formats can be added by writing translation schemas (see section 24.3) and by declaring these schemas in the .language file (see section 23.3). LaTeX, HTML (the World Wide Web format), Word, etc, are examples of formats.

7.9 Document and schema directories

When the editor needs to access a document, an image (see section 17) or a schema, it searches the corresponding file within a set of directories that can be managed by the user. Two directory sets exist: one for documents and one for schemas (structure schemas, see sections 1 and 24.1, presentation schemas, see sections 8 and 24.2 and translation schemas, see sections 7.8 and 24.3). Images can be inserted in both sets.

7.9.1 Environment parameters

Both schema and document directories sets can be defined while launching the editor by using the THOTDOC and THOTSCH configuration parameters (see section 23). The value of these parameters must be a list of directories separated by characters ` : '. The way in which directories are ordered in the list is important: the editor starts the search in the first directory, then in the second if the required file has not been found, and so on.

Here is a example of parameter declaration for Thot application:

[thot]
  THOTDOC=/opera/doc:/users/dupont/documents
  THOTSCH=/opera/schemas:/users/dupont/perso_schemas
 

The parameters THOTDOC and THOTSCH are not mandatory: if they are not defined by the user, by default each of them contains only one directory: the current directory when Thot is launched for documents and the standard schema directory.

7.9.2 Environment menu

The ``Environment'' menu (menu bar in Thot window) includes two forms with which both directory sets can be modified. The two forms work on the same principle: they provide, in the order in which they are used by the editor, the list of document and schema directories. These lists can be changed if the convention of one directory per line is respected (the ` : ' character used in THOTDOC and THOTSCH configuration parameters must not be used here; it is replaced by a line break).

The ``Document directories'' and ``Schema directories'' forms are used to add or to remove directories in the two lists of directories or to change the order in which the editor carries out the search within directories.

Modifications in a directory set is echoed in the resource file. Thus the editor configuration is preserved between editing sessions.

[Section 8] [Table of contents]