1\begin{page}{HTXLinkPage6}{How to use your pages with \ \HyperName{}} 2\centerline{\fbox{{\tt \thispage}}}\newline 3\begin{scroll} 4 5Let us say that you have written a few \HyperName{} 6pages and you would like to incorporate them in the system. 7Here is what you should do. 8 9Put all your files in some directory and make sure that 10they all have the {\bf .ht} extension. 11 12You will need a way of "hooking" into a system--defined 13\HyperName{} page. The proper way to do this is to use 14the {\tt \\localinfo} macro. The \Language{} system 15\HyperName{} page database includes, as it should, 16a {\tt RootPage}. This is the page that first comes up 17when you start \HyperName{}. This page contains 18a line like this. 19\beginImportant 20\newline 21{\tt \\localinfo} 22\endImportant 23 24This macro is defined in 25\centerline{ {\bf \env{FRICAS}/share/hypertex/pages/util.ht}} 26to be (see \downlink{Macros}{HTXAdvPage3} to learn how to define macros): 27\beginImportant 28\newline 29{\tt \\newcommand\{\\localinfo\}\{\}} 30\endImportant 31which is an empty definition (the second argument of {\tt \\newcommand}). 32The idea then is that you {\it override} this definition of the macro 33with your own. 34To do that, include a definition like the following in one (possibly the 35one that contains your top--level page) of your files. You can 36put this definition in its own file if you like. 37\beginImportant 38\newline 39{\tt \\newcommand\{\\localinfo\}\{\\menuwindowlink\{{\it active text}\}} \newline 40{\tt \{{\it page name}\} \\tab\{16\}{\it short description}\}} 41\endImportant 42 43If you have a look at the initial \HyperName{} page, you will 44probably be able to decipher what this does. The macro 45{\tt \\menuwindowlink} is defined (again in {\bf util.ht}) 46and is responsible for putting the little square to the left of the 47active area. 48Specify a word or two for {\it active text}. That will become the 49trigger of the {\tt \\link}. Specify the page name of your top--level page 50in {\it page name}. Finally, you can give a comment about the topic 51under {\it short description}. That will appear to the right of the 52{\it active text}. 53 54The next thing you need to do is to create a {\it local database} 55for your files. You will use the {\bf \env{FRICAS}/bin/htadd} program. 56This program will create an {\bf ht.db} file that summarises your 57definitions and acts as an index. Let us present an example 58of its use. Suppose you have two files {\bf user1.ht} and {\bf user2.ht} 59in directory {\bf /u/sugar/\HyperName{}}. You should create the {\bf ht.db} 60in that same directory. To create the {\bf ht.db} file you issue to 61the unix shell: 62\beginImportant 63\newline 64{\tt htadd -f /u/sugar/\HyperName{} /u/sugar/\HyperName{}/user1.ht /u/sugar/\HyperName{}/user2.ht} 65\centerline{or ,if you are already in /u/sugar/\HyperName{}} 66{\tt htadd -l ./user1.ht ./user2.ht} 67\endImportant 68 69 70The options and conventions for {\bf htadd} will be explained below. 71To start \HyperName{} with your own pages, you now need to tell 72it where to search for {\bf ht.db} files and \HyperName{} {\bf .ht} 73files. To do this, define the shell environment variable 74{\bf HTPATH}. The value should be a colon {\tt ':'} separated 75list of directory full pathnames. 76The order of the directories is respected with earlier entries overriding 77later ones. Since we want all the \Language{} pages but need to override the 78{\tt \\localinfo} macro, we should use the value 79\centerline{{\bf /u/sugar/\HyperName{}:\env{FRICAS}/share/hypertex/pages}} 80The way that you define environment variables depends on the shell 81you are using. In the {\bf /bin/csh}, it would be 82\newline 83{\bf setenv HTPATH /u/sugar/\HyperName{}:\env{FRICAS}{}/doc{}/hypertex{}/pages} 84 85 86 87\beginImportant 88\begin{paste}{HTXLinkPage6xPaste1}{HTXLinkPage6xPatch1} 89\pastebutton{HTXLinkPage6xPaste1}{Options for {\bf htadd}} 90\newline 91\end{paste} 92\endImportant 93 94 95\beginImportant 96\begin{paste}{HTXLinkPage6xPaste2}{HTXLinkPage6xPatch2} 97\pastebutton{HTXLinkPage6xPaste2}{Where does \HyperName{} look for files} 98\newline 99\end{paste} 100\endImportant 101 102 103 104\end{scroll} 105\beginmenu 106\menulink{Back to Actions menu}{HTXLinkTopPage} 107\endmenu 108 109\end{page} 110\begin{patch}{HTXLinkPage6xPatch1} 111\begin{paste}{HTXLinkPage6xPaste1A}{HTXLinkPage6xPatch1A} 112\pastebutton{HTXLinkPage6xPaste1A}{Hide} 113\newline 114Name: 115 116{\tt htadd - create or modify a \HyperName{} database} 117\vspace{} 118\newline 119Syntax: 120 121{\tt htadd [ -l | -s | -f\ }{\it path}{\tt ] [ -d | -n ]\ }{\it filename ...} 122\vspace{} 123\newline 124Options:\indentrel{4}\newline 125{\tt -l}\tab{8}\indentrel{8} 126build {\bf ht.db} database in current working directory. 127This is the default behaviour if no {\tt -l}, {\tt -s} or {\tt -f} 128is specified. 129 130\indentrel{-8}\newline 131{\tt -s}\tab{8}\indentrel{8} 132build {\bf ht.db} database in {\it system} directory. The 133system directory is built as follows. If the {\tt FRICAS} 134variable is defined, the {\bf \$FRICAS/share/hypertex/pages} directory 135is used. If {\tt FRICAS} is not defined, the 136{\bf /usr/local/fricas/share/hypertex/pages} directory is used. 137 138 139\indentrel{-8}\newline 140{\tt -f\ }{\it path}\newline\tab{8}\indentrel{8} 141build {\bf ht.db} database in specified {\it path}. 142 143\indentrel{-8}\newline 144{\tt -d}\tab{8}\indentrel{8} 145delete the entries in the specified files from {\bf ht.db}. 146 147\indentrel{-8}\newline 148{\tt -n}\tab{8}\indentrel{8} 149delete {\bf ht.db} and create a new one using only the files 150specified. 151 152If none of {\tt -n} and {\tt -d} is specified, the {\bf ht.db} 153is updated with the entries in the file specified. 154 155 156\indentrel{-8} 157\indentrel{-4} 158\vspace{}\newline 159Filename interpretation : 160\indentrel{12}\newline 161A full pathname (i.e. anything that has a {\tt '/'} in it) 162will be taken do be a completely specified file. 163Otherwise, the following interpretation will occur: 164If the {\tt HTPATH} variable is defined, the directories 165specified in it will be tried in order. If {\tt HTPATH} 166is not defined, then, if {\tt FRICAS} is defined, the 167{\bf \$FRICAS/share/hypertex/pages} will be tried, else 168the file will be deemed missing and {\bf htadd} will fail. 169\indentrel{-12} 170\end{paste} 171\end{patch} 172\begin{patch}{HTXLinkPage6xPatch1A} 173\begin{paste}{HTXLinkPage6xPaste1B}{HTXLinkPage6xPatch1} 174\pastebutton{HTXLinkPage6xPaste1B}{Options for {\bf htadd}} 175\newline 176\end{paste} 177\end{patch} 178 179\begin{patch}{HTXLinkPage6xPatch2} 180\begin{paste}{HTXLinkPage6xPaste2A}{HTXLinkPage6xPatch2A} 181\pastebutton{HTXLinkPage6xPaste2A}{Hide} 182\indentrel{12}\newline 183The \HyperName{} program is 184\centerline{{\bf \env{FRICAS}/lib/hypertex}} 185If {\tt FRICAS} is defined and {\tt HTPATH} is not 186(this is the case when \Language{} starts \HyperName{}) 187\HyperName{} will look in 188\centerline{{\bf \env{FRICAS}/share/hypertex/pages}} 189for the {\bf ht.db} file and all \HyperName{} pages. 190If {\tt HTPATH} is defined, it is assumed that 191it alone points to the directories to be searched 192(the above default will NOT be searched unless 193explicitly specified in {\tt HTPATH}). 194For each directory in {\tt HTPATH}, the {\bf ht.db} 195file, if there, will be read. 196Each file listed in {\bf ht.db} will 197then be searched for in the complete sequence 198of directories in {\tt HTPATH}. Note that 199the {\bf ht.db} does not keep full pathnames 200 of files. 201If a {\it page}, {\it macro} or {\it patch} 202(specified in some {\bf ht.db}) happens 203to be (in a file) in more than one of the directories 204specified in {\tt HTPATH}, \HyperName{} 205will print a warning and explain which version 206in which file is ignored. Generally, earlier 207directories in {\tt HTPATH} are preferred over later 208ones. 209\indentrel{-12}\newline 210\end{paste} 211\end{patch} 212\begin{patch}{HTXLinkPage6xPatch2A} 213\begin{paste}{HTXLinkPage6xPaste2B}{HTXLinkPage6xPatch2} 214\pastebutton{HTXLinkPage6xPaste2B}{Where does \HyperName{} look for files}} 215\newline 216\end{paste} 217\end{patch} 218