path: root/src/hyper/pages/HTXLinkPage6.ht

\begin{page}{HTXLinkPage6}{How to use your pages with \ \HyperName{}}
\centerline{\fbox{{\tt \thispage}}}\newline
\begin{scroll}

Let us say that you have written a few \HyperName{}
pages and you would like to incorporate them in the system.
Here is what you should do.

Put all your files in some directory and make sure that
they all have the {\bf .ht} extension.

You will need a way of "hooking" into a system--defined
\HyperName{} page. The proper way to do this is to use
the {\tt \\localinfo} macro. The \Language{} system
\HyperName{} page database includes, as it should,
a {\tt RootPage}. This is the page that first comes up
when you start \HyperName{}. This page contains
a line like this.
\beginImportant
\newline
{\tt \\localinfo}
\endImportant

This macro is defined in
\centerline{ {\bf \env{AXIOM}/doc/hypertex/pages/util.ht}}
to be (see \downlink{Macros}{HTXAdvPage3} to learn how to define macros):
\beginImportant
\newline
{\tt \\newcommand\{\\localinfo\}\{\}}
\endImportant
which is an empty definition (the second argument of {\tt \\newcommand}).
The idea then is that you {\it override} this definition of the macro
with your own.
To do that, include a definition like the following in one (possibly the
one that contains your top--level page) of your files. You can
put this definition in its own file if you like.
\beginImportant
\newline
{\tt \\newcommand\{\\localinfo\}\{\\menuwindowlink\{{\it active text}\}} \newline
{\tt \{{\it page name}\} \\tab\{16\}{\it short description}\}}
\endImportant

If you have a look at the initial \HyperName{} page, you will
probably be able to decipher what this does. The macro
{\tt \\menuwindowlink} is defined (again in {\bf util.ht})
and is responsible for putting the little square to the left of the
active area.
Specify a word or two for {\it active text}. That will become the
trigger of the {\tt \\link}. Specify the page name of your top--level page
in {\it page name}. Finally, you can give a comment about the topic
under {\it short description}. That will appear to the right of the
{\it active text}.

The next thing you need to do is to create a {\it local database}
for your files. You will use the {\bf \env{AXIOM}/bin/htadd} program.
This program will create an {\bf ht.db} file that summarises your
definitions and acts as an index. Let us present an example
of its use. Suppose you have two files {\bf user1.ht} and {\bf user2.ht}
in directory {\bf /u/sugar/\HyperName{}}. You should create the {\bf ht.db}
in that same directory. To create the {\bf ht.db} file you issue to
the unix shell:
\beginImportant
\newline
{\tt htadd -f /u/sugar/\HyperName{} /u/sugar/\HyperName{}/user1.ht /u/sugar/\HyperName{}/user2.ht}
\centerline{or ,if you are already in /u/sugar/\HyperName{}}
{\tt htadd -l ./user1.ht ./user2.ht}
\endImportant


The options and conventions for {\bf htadd} will be explained below.
To start \HyperName{} with your own pages, you now need to tell
it where to search for {\bf ht.db} files and \HyperName{} {\bf .ht}
files. To do this, define the shell environment variable
{\bf HTPATH}. The value should be a colon {\tt ':'} separated
list of directory full pathnames.
The order of the directories is respected with earlier entries overriding
later ones. Since we want all the \Language{} pages but need to override the
{\tt \\localinfo} macro, we should use the value
\centerline{{\bf /u/sugar/\HyperName{}:\env{AXIOM}/doc/hypertex/pages}}
The way that you define environment variables depends on the shell
you are using. In the {\bf /bin/csh}, it would be
\newline
{\bf setenv HTPATH /u/sugar/\HyperName{}:\env{AXIOM}{}/doc{}/hypertex{}/pages}



\beginImportant
\begin{paste}{HTXLinkPage6xPaste1}{HTXLinkPage6xPatch1}
\pastebutton{HTXLinkPage6xPaste1}{Options for {\bf htadd}}
\newline
\end{paste}
\endImportant


\beginImportant
\begin{paste}{HTXLinkPage6xPaste2}{HTXLinkPage6xPatch2}
\pastebutton{HTXLinkPage6xPaste2}{Where does \HyperName{} look for files}
\newline
\end{paste}
\endImportant



\end{scroll}
\beginmenu
\menulink{Back to Actions menu}{HTXLinkTopPage}
\endmenu

\end{page}
\begin{patch}{HTXLinkPage6xPatch1}
\begin{paste}{HTXLinkPage6xPaste1A}{HTXLinkPage6xPatch1A}
\pastebutton{HTXLinkPage6xPaste1A}{Hide}
\newline
Name:

{\tt htadd - create or modify a \HyperName{} database}
\vspace{}
\newline
Syntax:

{\tt htadd [ -l | -s | -f\ }{\it path}{\tt ] [ -d | -n ]\ }{\it filename ...}
\vspace{}
\newline
Options:\indentrel{4}\newline
{\tt -l}\tab{8}\indentrel{8}
build {\bf ht.db} database in current working directory.
This is the default behaviour if no {\tt -l}, {\tt -s} or {\tt -f}
is specified.

\indentrel{-8}\newline
{\tt -s}\tab{8}\indentrel{8}
build {\bf ht.db} database in {\it system} directory. The
system directory is built as follows. If the {\tt AXIOM}
variable is defined, the {\bf \$AXIOM/doc/hypertex/pages} directory
is used. If {\tt AXIOM} is not defined, the
{\bf /usr/local/axiom/doc/hypertex/pages} directory is used.


\indentrel{-8}\newline
{\tt -f\ }{\it path}\newline\tab{8}\indentrel{8}
build {\bf ht.db} database in specified {\it path}.

\indentrel{-8}\newline
{\tt -d}\tab{8}\indentrel{8}
delete the entries in the specified files from {\bf ht.db}.

\indentrel{-8}\newline
{\tt -n}\tab{8}\indentrel{8}
delete {\bf ht.db} and create a new one using only the files
specified.

If none of {\tt -n} and {\tt -d} is specified, the {\bf ht.db}
is updated with the entries in the file specified.


\indentrel{-8}
\indentrel{-4}
\vspace{}\newline
Filename interpretation :
\indentrel{12}\newline
A full pathname (i.e. anything that has a {\tt '/'} in it)
will be taken do be a completely specified file.
Otherwise, the following interpretation will occur:
If the {\tt HTPATH} variable is defined, the directories
specified in it will be tried in order. If {\tt HTPATH}
is not defined, then, if {\tt AXIOM} is defined, the
{\bf \$AXIOM/doc/hypertex/pages} will be tried, else
the file will be deemed missing and {\bf htadd} will fail.
\indentrel{-12}
\end{paste}
\end{patch}
\begin{patch}{HTXLinkPage6xPatch1A}
\begin{paste}{HTXLinkPage6xPaste1B}{HTXLinkPage6xPatch1}
\pastebutton{HTXLinkPage6xPaste1B}{Options for {\bf htadd}}
\newline
\end{paste}
\end{patch}

\begin{patch}{HTXLinkPage6xPatch2}
\begin{paste}{HTXLinkPage6xPaste2A}{HTXLinkPage6xPatch2A}
\pastebutton{HTXLinkPage6xPaste2A}{Hide}
\indentrel{12}\newline
The \HyperName{} program is
\centerline{{\bf \env{AXIOM}/lib/hypertex}}
If {\tt AXIOM} is defined and {\tt HTPATH} is not
(this is the case when \Language{} starts \HyperName{})
\HyperName{} will look in
\centerline{{\bf \env{AXIOM}/doc/hypertex/pages}}
for the {\bf ht.db} file and all \HyperName{} pages.
If {\tt HTPATH} is defined, it is assumed that
it alone points to the directories to be searched
(the above default will NOT be searched unless
explicitly specified in {\tt HTPATH}).
For each directory in {\tt HTPATH}, the {\bf ht.db}
file, if there, will be read.
Each file listed in {\bf ht.db} will
then be searched for in the complete sequence
of directories in {\tt HTPATH}. Note that
the {\bf ht.db} does not keep full pathnames
 of files.
If a {\it page}, {\it macro} or {\it patch}
(specified in some {\bf ht.db}) happens
to be (in a file) in more than one of the directories
specified in {\tt HTPATH}, \HyperName{}
will print a warning and explain which version
in which file is ignored. Generally, earlier
directories in {\tt HTPATH} are preferred over later
ones.
\indentrel{-12}\newline
\end{paste}
\end{patch}
\begin{patch}{HTXLinkPage6xPatch2A}
\begin{paste}{HTXLinkPage6xPaste2B}{HTXLinkPage6xPatch2}
\pastebutton{HTXLinkPage6xPaste2B}{Where does \HyperName{} look for files}}
\newline
\end{paste}
\end{patch}