TECOAS: User's Guide

Index

1. Installation
2. Using TECOAS
3. Configuring TECOAS for use with the SOBA Framework
5. Bug reports
6. Disclaimer

Installation

Requirements

• JRE 1.4
The Java Runtime Environment version 1.4 is required. You can get it from Sun if needed.
• SobaLight (Included in the TECOAS distribution)
This is a simplified version of the Framework provided by the SOBA Project. SobaLight itself only requires a working JRE.
TECOAS also work with the SOBA Framework, but this requires more tweaking. Look at Configuring TECOAS for use with the SOBA Framework for details.
• Ghostscript
For TECOAS to work properly, at least one of the session members must have a properly working version of Ghostscript installed.
While the standard version of Ghostscript shall work properly for both Postscript and PDF documents using latin fonts, use with Chinese, Japanese or Korean fonts can be more challenging.
• LaTeX (optional)
LaTeX is also required if want to use the Mathematical Input Method provided by TECOAS.

Using TECOAS

Read also the files README and sobalight.html in the distribution.

Startup

In the following, we assume that the contents of the distribution (tecoas-0.*.zip) have been unpacked in the ${TECOAS_HOME} directory. Configuration You may need to configure TECOAS by editting the tecoasrc file, which resides in ${TECOAS_HOME}. By default, all contents are commented out, and a default behaviour is selected. Most contents can be left unchanged, but you may need to change the setup for gs.

 # Where to find ghostscript #gs=no # no ghostscript (requires server) #gs=gs # Unix or Cygwin (default) #gs=gswin32c # Windows #gs_device=png16m #gs_paper=a4 

The default is to call the gs command. If no ghostscript is available on your system, of if it does not work properly, you must uncomment the line gs=no (but at least one of the participants in a TECOAS session must have a working Ghostscript). If you are using the gswin32 version of Ghostscript, you must uncomment the line gs=gswin32c. Incorrect configuration of this parameter will result in an error message when you open a Postscript or PDF file. You may also override the tecoasrc file by putting a copy of it in your home directory, renamed as .tecoasrc; in that case only .tecoasrc will be read, and the original tecoasrc is ignored.

Execution

($, > indicate shell and console command prompts.) 1. One of the participants starts a SobaLight server. 1. SobaLight execution • Example 1  $ cd ${TECOAS_HOME}$ java -jar sobalight.jar 

• Example 2 (On Windows)

Inside explorer, go to the ${TECOAS_HOME} directory, and double-click on sobalight.bat 2. In the SobaLight console, type the following command.  > start 8383 NOSTATE  Alternatively, one may start the server without starting the GUI.  $ cd ${TECOAS_HOME}$ java -jar sobalight.jar -no-console server.sol 

2. One of the participants starts a TECOAS master.
1. Start SobaLight, as above.
2. In the SobaLight console, type the following commands.

 > connect 8383 > load viewer.sol 

Alternatively, one can edit the master.sol script, and run it directly (on unix).

3. Other participants start as clients.
1. Start SobaLight, as above.
2. In the SobaLight console, type the following command.

 > connect 8383 

Alternatively, one can edit the client.sol script, and run it directly (on unix) or through double-clicking client.bat.

4. If you have a more complex network configuration, and need to forward connections through ssh, this is possible by having all remote participants do:

 $ssh -L8383::8383  Then they must replace "connect <server name> 8383" in the above by "connect localhost 8383". Remark If you want to test TECOAS alone, you can do it by running the standalone.sol script or double-clicking on standalone.bat. Visual components TECOAS is composed of a Viewer component and a Chat component. Viewer When you start TECOAS, the TECOAS logo appears in the Viewer window. First, one of the participants must open a document by selecting [Open File] in the File menu. Postscript and PDF formats are supported. Then all participants may use the following functions. Navigation By pushing the navigation buttons, you may change the page currently displayed in your viewer. You can also directly input a page number in the page field. Annotations With TECOAS, one can add annotations to a shared document. Annotations apply to a region which can be a point, a line, or a rectangle. Here are the steps to add an annotation. 1. Choose an annotation kind by pushing one of the annotation buttons. 2. Select the region by clicking and dragging the mouse. 3. A window appears. Write your comment in it. 4. [OK] adds your annotation to the document. All participants will see it. [Cancel] throws it away. One an annotation has been added, you can  or [Delete]. When somebody is editting an annotation, his name appears in the annotation title. Annotations are automatically saved, and will appear the next time you open the same document. However, any change in a document will cause it to be seen as different by TECOAS. Graffiti You can draw explanations on top of a document. 1. Click the graffiti button. (You enter the graffiti mode) 2. Draw with the mouse. 3. Click again the graffiti button. (You exit the graffiti mode, sending your drawing to all participants) Graffiti are not saved. They will disappear the next time you open the same document. Synchronization Annotations and graffiti are shared between all participants, but you cannot be sure that they are looking at the same page. By pressing the synchronization button, you can force other participant to go to the same page. Participants who are editting an annotation, or who have disabled synchronization, will not be synchronized. Telepointer The telepointer functionality is available to show your pointer to other participants (when it is inside the viewer area). It is mainly useful if other participants can hear your voice, since otherwise you have to move the pointer to write chat messages. Click once the telepointer button to enter telepointer mode, and once again to end telepointer mode. When in telepointer mode, you can see a label with your name following the mouse pointer. Chat The Chat window is composed of two parts. The upper part is a log of past chat messages. The lower part allows you to edit a message before you send it. When you press the [Send] button, you message is sent to all participants. You can also clear the edition window with the [Clear] button, or insert images with the [Insert Image] option of the Chat menu. Another tab named "Messages" is also present in the upper part. It is intended to let you check the behaviour of subprocesses (gs or latex) launched by TECOAS. Mathematical Input Method, and Cut and Paste Both in annotations and in chat messages, you can also input mathematical formulas. 1. Press [Ctrl + \] to enter Math mode. The background becomes blue, and the cursor is between two "$".
2. Input there a valid LaTeX formula (in math mode).
For instance: $\pi > 3$
3. [Ctrl + M] converts the formula to its graphical representation.
4. To confirm the conversion, press [Ctrl + M] once more, or cancel the conversion through [Ctrl + G].

Mathematical formulas may be copied and pasted like normal text.

1. The selected area is automatically copied to the TECOAS clipboard.
2. [Ctrl + Y] inserts the current contents of the clipboard.
3. [Ctrl + V] inserts the text version of the contents.

How to quit

By default, you cannot quit TECOAS, as this would shutdown TECOAS for all members. You should rather press the Exit button of the SobaLight console. Note that if there are still some participants in the station, you can reenter it at anytime as a client, and will share all annotations and chat.

Configuring TECOAS for use with the SOBA Framework

Note that the current version of the SOBA Framework may only be installed on Japanese versions of Windows, otherwise you may only use TECOAS SobaLight.

${SOBA}\home\system\config\win32\applications.xml  (The added part is in red)  [...]  Startup We assume that all members have already started the SOBA Frameworks, and share a session. (See the Generic Application Guide at INCPOD for details.) If TECOAS was correctly installed, then it should appear in your Toolbox. One member should start TECOAS, after that you can use exactly as with SobaLight. Advice Frequently Asked Questions • I opened a file, but it doesn't appear in the viewer. Why is it? Your Ghostscript configuration is probably wrong. Try running it from a shell or DOS prompt by typing "gs". If it doesn't work, but you are sure to have Ghostscript on your system, you may have to change the PATH environment variable, or the executable name in tecoasrc. It may also be that your version of ghostscript does not support PDF. You may look at the messages caused by Ghostscript in the Message tab of the Chat area. • I cannot add new annotations. Why is it? You cannot add annotations while editting another annotation. Check that you are editting no annotation. • I don't want other members to be able to change the page I see. What should I do? Unselect the [Allow to be synchronized] option in the File menu. • The posisition of annotations is not kept. Why is it? This is a feature. The part of the document concerned by an annotation is marked by an annotation mark, so the position of the annotation itself is not relevant. • How can I add LaTeX macros? You can add them in the "tex_user_preamble" field of your tecoars Your commands may go on for several lines if you end each line by a backslash. These command will be inserted are the context of the "tex_preamble" field. • (Using the SOBA Framework) TECOAS does not appear in the Toolbox. 1. Check that the context file shared-context-tecoas.xml is in the ${SOBA}\home\system\appli\ directory.
2. Check that the description of TECOAS in ${SOBA}\home\system\config\win32\applications.xml is correct. • (Using the SOBA Framework) I get the error "In session Soba:SessionID.... the shared object [Texsoba:Viewer] could not be created" 1. Check that the description of TECOAS in ${SOBA}\home\system\config\applications.xml is correct.
2. Check that tecoas.jar was really copied under \${SOBA}\apps.

Known bugs

• Some images cannot be copied to the clipboard.

Tips

• You can hide an annotation by clicking its Icon button. It appears again if you click its ican.
A menu appears by right clicking on the icon or the annotation title bar.
• You can copy-paste images and formulas between the chat and annotations.
• If some text is selected when you enter the math mode by [Ctrl + \], this text will be used as latex input. If a formula or a file is selected, its source will appear.
• [Ctrl + \] also reverts from math mode to normal mode.
• [Ctrl + C] copies the selected area to the internal clipboard.
• You can also copy a region emacs-style, by using [Ctrl + space] and [Ctrl + W].
• [Ctrl + Alt + Y] and [Ctrl + V] paste the contents of the system clipboard, i.e. the source for a formula.

Bug reports

Send bug reports to tecoas@kaba.or.jp.