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. 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.
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"
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"
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 >
,
less-than is coded <
and backslash 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.
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.
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".
<CODE>. . . </CODE>
. Please avoid wrapping
things in "quotes". If you must use quotes, then use double quotes,
not single quotes.
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.
<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>
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:
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.
Unfortunately, Tydoc does not follow this convention.
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
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 systemtydoc
script, located in $TYCHO/util/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/usersGuides/makefile
and add the HTML filename.
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.
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.
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.