Anchor Text

Clickable references in the HTML text have the usual form:

<a href="something">highlighted text</a>

Here, ``something'' can be a help database keyword or an ordinary URL.

One can use named anchors in help keywords. This means that the `#' symbol is holy, and should not be used in help keywords. The named anchors can appear in the !!HTML part of the help database entries in the usual HTML way, e.g.

!!KEYWORD
somekeyword
...
!!HTML
    ...
    <a name="refname">some text</a>

Then, referencing forms like ``!help somekeyword#refname'' and <a href="somekeyword#refname">blather</a> will bring up the ``somekeyword'' topic, but with ``some text'' at the top of the help window, rather than the start of the document.

There is an additional capability: `$' expansion. Words found in anchor text that begin with a dollar sign (`$') character may be replaced by either a path related to the program, the value of a variable saved in the program, or the value of an environment variable. The character that immediately follows the word can not be alphanumeric.

This replacement is handled by a callback to the application, but both Xic (and its derivatives) and WRspice support the following keywords and behavior.

$PROGROOT
This word is replaced by the full path to the program installation directory, for example
``/usr/local/xictools/xic''.

$HELP
This word is replaced by $PROGROOT/help, meaning the same directory as $PROGROOT suffixed with /help.

$EXAMPLES
This word is replaced by $PROGROOT/examples, as above.

$DOCS
This word is replaced by $PROGROOT/docs, as above.

$SCRIPTS
This word is replaced by $PROGROOT/scripts, as above.

If there is no match to these words, the word, without the dollar sign, is checked against the variable database. If a variable is set with the same name, the string value of the variable replaces the word. If there is no match, but the word without the dollar sign matches the name of an environment variable, the value of the environment variable will replace the word. If there is no match, there is no substitution. Substitutions are evaluated recursively.

If the first character of an anchor URL is `~', the path is tilde expanded. This is done after `$' substitution. Tildes denote a user's home directory: ``~/mydir'' might expand to ``/home/yourhome/mydir'', and ``~joe/joesdir'' might expand to ``/home/joe/joesdir'', etc.

In Xic, one can open input files from anchor text in the HTML viewer. The type of file is recognized by the suffix. These are:

CGX	.cgx (.gz may follow)
GDSII	.gds, .str, .strm, .stream (.gz may follow)
OASIS	.oas
CIF	.cif
Xic	.xic

The anchor text to open a cell can actually have the following syntax. It can consist of up to three space-separated words.

[sourcetype] sourcename [cellname]

The optional sourcetype can be one of the following literal tokens.

@XIC
The sourcename is the name of a native cell existing either in memory or in the search path for cell files, or the name may contain a path to the file. The cellname word is not used.

@CHD
The sourcename will provide the database name of a cell hierarchy digest. The cellname if used provides the name of a cell to open. If not given, the CHD's default cell will be opened.

@LIB
The sourcename is a path to an Xic library file, and the cellname is the name of a reference or cell in the library.

@OA
The sourcename is the name of an OpenAccess library, and the cellname, which is required, is the name of a cell in the library.

If no sourcetype is given, the file type is determined by the file extension, as listed above. The optional cellname can specify the name of a cell to open.

In addition, if the sourcename has a .scr suffix, it is taken to be a script file, and is executed. Thus, one can execute Xic scripts by clicking on an anchor. The referenced script is expected to be found somewhere in the script path, or be defined in the technology file, if a rooted file path is not provided.

Examples:
One can actually load a layout from another machine.

Click <a href="http://somewhere/lib/cell.gds">here</a> to view the design.

A second argument can specify the cell to open. The quoting is required in this case.

Click <a href="/usr/joe/library/joeslayout.gds joescell">here</a> to view Joe's cell.

Unless the native cell happens to have a .xic file name extension, one should use the magic word.

Click <a href="@XIC mynativecell">here</a> to view my native cell.

If the OpenAccess plug-in is loaded, one can access cells from OpenAccess libraries.

Click <a href="@OA oalibrary oacell">here</a> to view my OpenAccess cell.

Finally, to execute a script when the user clicks on the link:

Click <a href="myscript.scr">here</a> to execute myscript.

The script myscript.scr must exist somewhere in the script path, or be defined in the technology file. When the user clicks on ``here'', this script will be executed.

In WRspice, a similar capability exists. One can source files from anchor text in the HTML viewer, if the anchor text consists of a file name with a .cir extension. Thus, if one has a circuit file named mycircuit.cir, and the HTML text in the help window contains a reference like

<a html="mycircuit.cir">click here</a>

then clicking on the ``click here'' tag will source mycircuit.cir into WRspice. Similarly, anchor references to files with a .raw extension will be loaded into WRspice as a rawfile, i.e., a plot data file, when the anchor is clicked.