Initial population.

1 files changed, 218 insertions, 0 deletions

diff --git a/src/hyper/pages/HTXLinkPage6.ht b/src/hyper/pages/HTXLinkPage6.ht
new file mode 100644
index 00000000..eb9e4b23
--- /dev/null
+++ b/src/hyper/pages/HTXLinkPage6.ht
@@ -0,0 +1,218 @@
+\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}
+