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.
tydoc
-
The Tycho documentation system.
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.
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"
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"
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 >
, less-than
is coded <
. 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.
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:
A documentation directory should have the following elements:
makefile
that includes all of the *.html
files in the EXTRA_SRCS
makefile variable.
index.html
file contains a properly formatted index
of all of the html files in the directory.
*.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.
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
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 systemtydoc
script, located in $TYCHO/lib/tydoc
is used to convert itcl source files to html. tydoc
is
documented separately.
EditFoo.itcl
, the the User's Guide
should be doc/usersGuides/EditFooHelp.html
.
If you add a user's guide, follow these steps:
doc/usersGuide/makefile
and add the html filename.
doc/usersGuide/index.html
and add a link to the file.