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. Tycho can read HTTP hyperlink references, so you can read documents that reside on non-local filesystems from within Tycho. 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 a manner such 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 delimiters <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 pop-up 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 ">", less-than "<" and backslash "\". Greater-than is coded &gt;, less-than is coded &lt; and backslash is coded &#92. 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 from a remote system via an httpd server, 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.
  • The text that makes up a HTML link should be on one line, as some of the HTML tools such as htmlchek will not process HTML <A HREF="...">...</A> links that are split over multiple lines.

    Formatting Documentation

    The Tycho documentation has a consistent look and feel.

    Capitalization

    Emacs, Macintosh, Tcl, Tk, Itcl, Itk, Iwidgets, Tycho, Unix and Windows should usually be capitalized. For example
    Tycho0.1.1 will not work with Itcl2.0.

    Words such as HTML or SCCS, where one would speak each letter individually should have all the letters capitalized. Words such as Tcl, where one says, "Tickle" should only have the first letter capitalized. Michael McLennan prefers that the software he has written be referred to as:
    [incr Tcl] or Itcl
    [incr Tk] or Itk
    [incr Widgets] or Iwidgets

    In general, it is best to avoid use of capital letters in the middle of a word. Exceptions to this rule are classnames, such as EditTcl and the word "PostScript".

    Fixed Width Fonts

    Filenames, Environment variables, HTML examples, Key bindings, Menu names, Menu choices. Anything that the user is expected to type should be wrapped in <CODE>. . . </CODE>. Please avoid wrapping things in "quotes". If you must use quotes, then use double quotes, not single quotes.
    Usually user input follows its own capitalization rules. For example, the user would type tycho, not Tycho, even though 'Tycho' should always be capitalized. For example:
    The main program in the Tycho system is the tycho script.

    Itcl and Java Classnames are not wrapped in <CODE>. . .</CODE>.

    When quoting material written by others, follow the original font usage and capitalization.

    Display Lists

    Use Display Lists (<DL> . . . </DL>) for describing Tcl proc args and listing key bindings. When discussing a Tcl proc argument that is not a literal name, wrap it in <CODE><I> . . . </I></CODE>
    <dl>
    <dt><CODE>C-x 0</CODE><dd>iconify the window
    </dl>
    

    HTML Template File

    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/edit/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, if applicable.
  • A date when the file was last modified. The date is automatically updated when the file is checked in with SCCS.
  • 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. Unfortunately, Tydoc does not follow this convention.

    Indexing Documents

    A major feature of the Tycho integrated documentation system is its ability to automatically generate and maintain indices. 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 concept 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 this index is also accessible through the Help menu. Notice also that the name attribute can (and 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.

    The BuilderDialog can also be used to create indexes for the Tycho distribution. 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 indices. The Tycho Class Diagram guide has information about generating graphical class diagrams.

    tydoc - The Tycho documentation system

    The tydoc script, located in $TYCHO/util/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/usersGuides/makefile and add the HTML filename.
    2. Edit doc/usersGuides/index.html and add a link to the file.

    In general, a doc/ directory contains the following subdirectories:

  • internals/: documentation for programmers and developers.
  • usersGuides/: documentation for specific widgets and classes.
  • codeDoc/: documentation automatically generated from source files.
  • Itcl/Java Documentation

    External HTML documentation for packages such as Itcl and Java can be downloaded and installed in specific locations so that Tycho can find the documentation.

    Itcl

    The Itcl2.2 includes HTML documentation in itcl2.2/html. If you link $TYCHO/doc/itclhtml to the itcl2.2/html directory, then the links within the docs and in the Tcl and Itcl Internet Resources page will work properly.

    Java

    The Java documentation is available from http://www.javasoft.com. If you link $TYCHO/java/doc/javahtml to the docs/api directory of the Java documentation distribution, then the links within the documentation and Java Internate Resources page should work properly.

    Tycho Home Page


    Copyright © 1996-1998, The Regents of the University of California. All rights reserved.
    Last updated: 05/20/98, comments to: eal@eecs.berkeley.edu