Tycho Integrated Documentation

In Tycho, documentation and design are integrated. Hyperlinks can bind pretty much anything to anything. For formatted text, Tycho uses HTML, the hypertext markup language of the internet. Formatted text can appear in any Tycho widget.

Contents

HTML Conventions

The HTML widget in Tycho is based on the HTML library written by Stephen Uhler of Sun Microsystems, which supports all the features of HTML 2.0. There is currently no support in Tycho for HTTP hyperlink references, so you cannot within Tycho directly read documents on the internet. A sample document illustrates the HTML tags that are supported.

In Tycho, documentation files are kept small. This helps the response time of parser (which is really quite slow) and keeps information modular. Hyperlinks are used extensively throughout. An HTML editor provides support for hyperlinks, including a utility for checking their validity.

HTML Extensions

One key extension to HTML provided by Tycho allows embedding Tcl scripts into a document in such a manner that if the user double clicks on the script, the script will be executed. The HTML source for such a script is surrounded by by the delimitters <tcl> and </tcl>. For example, the HTML source

    <tcl><pre>
    ::tycho::post "hello world"
    </pre></tcl>
appears as follows in a document:
    ::tycho::post "hello world"
Double clicking on this script will execute it if you are viewing the document under Tycho. In the above example, the post command returns the name of the widget it just created. By default, this returned value is displayed in a popup dialog box. This can be annoying if the returned value has no meaning to the reader. To suppress this, use the following syntax:
    <tcl quiet><pre>
    ::tycho::post "hello world"
    </pre></tcl>
which appears as follows in a document:
    ::tycho::post "hello world"
The only difference is that the returned value is displayed in the status bar at the bottom of the window rather than in a dialog box.

When creating embedded tcl scripts, you may find it necessary to use the HTML Code Character Set for things like greater-than '>' and less-than '<'. Greater-than is coded &gt;, less-than is coded &lt;. If you don't code characters that have meaning in HTML, then you might find that the output does not look the way you want it.

In addition, Tycho expands hypertext references that begin with a dollar sign ($). The characters up to the first slash (or up to then end if there are no slashes) are taken to be the name of an environment variable or a Tcl global variable. The value of the variable is substituted. Also, on Unix systems, filenames beginning with a tilde (~) specify files relative to a user's home directory, in the usual Unix fashion.

When writing HTML documentation, it is best if you use relative paths instead of using dollar sign references.

  • HTML viewers other than Tycho do not understand dollar sign references.
  • If the Tycho documentation is accessed via a httpd server, from a remote system then the dollar sign references will not expand properly. At UC Berkeley, we make the latest version of Tycho available from the Ptolemy website, so remote users can preview Tycho. If the documentation contains dollar sign references, then remote users will have broken links. If the documentation uses relative references, then remote users will be able to view the documentation.
  • Formatting Documentation

    The Tycho documentation should follow a consistent look and feel. The HTML editor has a File Template choice under the Special menu. This File Template will fill the current buffer with the contents of $TYCHO/editors/textedit/templates/HTMLTemplate.html The template has the following features:
  • The first line contains SCCS keywords
  • The head includes a title, and sets the background color
  • The footer includes
  • A relative link to doc/index.html. This link should not use $TYCHO so that it can be browsed with a non-tycho html browser.
  • The UC Copyright
  • A date when the file was last modified. The date is automatically updated when the file is checked in.
  • An author.
  • The footer also closes the body and html tags.
  • A documentation directory should have the following elements:
  • A makefile that includes all of the *.html files in the EXTRA_SRCS makefile variable.
  • A index.html file contains a properly formatted index of all of the html files in the directory.
  • In tycho, the *.html extension means that the file was generated by a human, the *.htm extension means that the file was automatically generated from some other source file.

    Indexing Documents

    A major feature of the Tycho integrated documentation system is its ability to automatically generate and maintain indexes. Effective use of this feature requires some discipline in writing the HTML documents in the first place.

    Index entries are constructed from anchors with a name attribute. For example, the source for the previous sentence is

        Index entries are constructed from <a name=anchors>anchors</a>
        with a <a name="name attribute">name attribute</a>.
    
    When an index is created from this document, the value of the name attribute will appear in the index with a pointer to precisely this point in the document. Thus, for example, the Tycho master index has a pointer to the above sentence under both "anchors" and "name attribute". Try it:
        ::tycho::File::openContext $TYCHO/lib/idx/tycho.idx
    
    Notice that the name attribute can (an often should) have spaces in it. It must be surrounded by quotation marks if it has spaces in it.

    Given one or more HTML documents, you can create an index for them using the tychoMkIndex Tcl command (you can invoke this in the console window). This command takes three or more arguments. The first argument is the name of the index, which will appear at the top of the index browser. The second argument is the name of the index file to create. This file should have the extension ".idx" so that it will be recognized as an index file. The rest of the arguments are any number of HTML file names from which the index should be created. Instead of listing many files, you can use glob patterns like "*.html" for the file names. A glob pattern can contain wildcards like "*", which match zero or more characters of any type.

    Once you have created an index and stored it in a file with the extension ".idx", that file will be opened using an index browser.

    The Troubleshooting Guide has hints about problems creating indexes.

    tydoc - The Tycho documentation system

    The tydoc script, located in $TYCHO/lib/tydoc is used to convert itcl source files to html. tydoc is documented separately.

    Adding a User's Guide

    Each editor should have a User's Guide. If the itcl file that contains the editor is named EditFoo.itcl, the the User's Guide should be doc/usersGuides/EditFooHelp.html. If you add a user's guide, follow these steps:
    1. Edit doc/usersGuide/makefile and add the html filename.
    2. Edit doc/usersGuide/index.html and add a link to the file.

    Tycho Home Page


    Copyright © 1996, The Regents of the University of California. All rights reserved.
    Last updated: 96/12/17, comments to: eal@eecs.berkeley.edu