Note that this section is really only relevant to the person responsible for installing and maintaining HIPR on your system.
See the introductory section on Making Changes with HIPRscript for an introduction to the role of HIPRscript in generating HIPR.
HIPRscript is a specially designed language for use with HIPR, similar in respects to both HTML and LaTeX. It is designed to allow the HIPRscript author to express the information needed by both hypermedia and hardcopy versions of HIPR in a relatively high-level way and it is readily translatable into both HTML and LaTeX using the supplied translation programs.
Almost 300 HIPRscript source files go together to make HIPR. In general, each HIPRscript source file gives rise to one HTML file and one LaTeX file. Each HTML file corresponds to a `scrollable page' of hypertext, while the LaTeX files are merged together to generate the hardcopy version of HIPR. There are a few exceptions to this rule --- for instance the .loc source files used for entering local information are included into other files.
Another important exception to this rule is the top-level file for the HTML and LaTeX versions. The HTML top-level file is called hipr_top.htm and lives in the html sub-directory. The LaTeX file lives in the tex sub-directory and is called hipr_top.tex. These are very different from one another, and so are not generated from a common HIPRscript source file (i.e. there is no hipr_top.hpr file). You should be careful not to delete these files since they cannot be regenerated, unlike most of the other HTML and LaTeX files.
To convert HIPRscript into HTML and LaTeX, a
Perl program called hiprgen.pl is used. This program can be
found in the progs sub-directory. The effect of the program when
run on a HIPRscript source file is to generate corresponding HTML and
LaTeX files in the appropriate directories.
To run hiprgen.pl you need to have at the very least a recent version of Perl installed on your system. In addition, if you wish to have the program automatically generate equations, figures and thumbnails as described below, then you will have to install additional utilities. The Installation Guide has all the details.
Apart from the hpr, html and tex sub-directories, four other sub-directories are also important to the running of HIPRscript.
The eqns sub-directory contains inline images representing equations for use in HTML documents. These image files are generated automatically by hiprgen.pl from information in the HIPRscript files and are incorporated into the displayed document by the HTML browser.
The figs sub-directory contains the images used for figures in two different formats: GIF for HTML pages, and encapsulated PostScript for inclusion into LaTeX output. As a HIPRscript author you must create the PostScript version of the figure yourself and put it in this directory. hiprgen.pl will then create a matching GIF file automatically if one does not already exist.
The thumbs sub-directory contains `thumbnails' (miniature versions of images that are used for imagelinks). These are normally generated automatically by hiprgen.pl from corresponding full-size images.
The index sub-directory contains information used in generating the HIPR main index. The files in this directory are created automatically my hiprgen.pl and should not be edited by hand.
The exact method of running hiprgen.pl depends upon the computer system you are using. Since it is a Perl program you need to have a Perl interpreter installed somewhere. You must then use this interpreter to run hiprgen.pl. Make sure that the `current' or `working' directory is the src sub-directory when you run it. You must also pass the program a command line argument which is simply the name of the source file to be translated, without the .hpr extension.
For instance, on my UNIX system, in order to translate dilate.hpr into HTML and LaTeX, I type (from within the src sub-directory):
perl ../progs/hiprgen.pl dilate
The program will run and the appropriate HTML and LaTeX files will be generated. If there are any errors, the translator will stop with an error message and no output files are generated. Error messages are detailed in a later section.
It is useful at this point to take a look at the contents of a typical HIPRscript file. For instance the file dilate.hpr starts something like:
\links{}{erode}{morops}
\index{Dilation}{\section{Dilation}}
\title{Morphology - Dilation}
\strong{Common Names:} Dilate, Grow, Expand
\subsection{Brief Description}
Dilation is one of the two basic operators in the area of
\ref{matmorph}{mathematical morphology}, the other being
\ref{erode}{erosion}. It is typically applied to
...
Have a look at the dilation worksheet to see what this becomes (note that if you are using Netscape or Mosaic then you might want to click on the link with the middle mouse button which will display the worksheet in a separate window).
As with both HTML and LaTeX, a HIPRscript source file is an ASCII file containing a mixture of raw text and tags which define how that raw text is to be displayed. Tags in HIPRscript have the following syntax:
The simplest tags take no arguments. For instance the tag: \times produces a multiplication symbol like this: ×.
Slightly more complicated are tags which take a single argument. An example of this is the \em tag which produces emphasized italic text. For instance, the phrase emphasized italic text in the last sentence was produced by the following HIPRscript fragment: \em{emphasized italic text}.
Finally, some tags take multiple arguments. A common example of this is the \ref tag which is used for cross references to other HIPR pages. To create a reference to the worksheet on dilation for example, we could write \ref{dilate}{This is a link to the dilation worksheet} which produces the following: This is a link to the dilation worksheet.
Many tags can be nested inside one another. If we modify the example in the last paragraph to \ref{dilate}{This is a link to the \em{dilation} worksheet}, then we get: This is a link to the dilation worksheet.
Arguments can usually contain newlines without any problems, but you should make sure that there are no newlines between arguments belonging to the same tag. For instance:
\ref{dilate}{This is a link
to the dilation worksheet}
is fine, whereas:
\ref{dilate}
{This is a link to the dilation worksheet}
is not.
One very important point is that like LaTeX and HTML, HIPRscript pays very little attention to the amount of whitespace (spaces, tabs and newlines) that you put in your document. One space between words is treated exactly the same as one hundred spaces --- both will cause just a single space to be displayed between the words.
Single newlines in sentences are also largely ignored. In general HIPRscript will decide for itself where it wants to break lines in order to make them fit onto the page. Note: In actual fact this tricky decision is taken care of by the magic of LaTeX and HTML browsers.
Two or more newlines in succession are treated as significant. They indicate that you want a paragraph break at that point. This will normally cause a vertical space to be inserted between the preceding and following lines on the page.
Normally line-breaks are inserted wherever LaTeX or your HTML browser feels appropriate. This is usually when the current line has as much text as will fit on it already. Sometimes though, we would like to ensure that a line-break does not occur between two words. For instance the phrase `Section 2' would look odd if a line-break appeared between `Section' and `2'. Therefore HIPRscript allows you to specify a `non-breaking space' which will never be broken over two lines. The symbol for this is just `~'. Using this feature, the phrase above would be entered as: Section~2.
As mentioned earlier, tags that don't take any arguments are terminated by any non-alphanumeric character. This can cause a problem if you do want to immediately follow such a tag with an alphanumeric character without putting a space in between. For instance if you want to display `2×2', you cannot write 2\times2 since \times2 is not a recognized tag and will cause an error. And if you write 2\times 2 then what you get is `2× 2', i.e. with an extra unwanted space. The solution is to terminate the tag with a caret. This special character terminates a tag without being printed itself. So 2\times^2 will produce the display you want. If you do want to follow a tag immediately with a caret for some reason, then simply use two of them. The other time you might want to use a caret to terminate a tag is if you want to put a backslash at the end of an argument. Without the caret, the final backslash would escape the closing brace and hence cause HIPRscript to think that you haven't terminated the argument properly. So you would write: ...\\^.
Since the backslash and braces are special characters, there are tags for displaying them normally. \\, \{ and \} will display \, { and } respectively.
It is often useful to be able to write
into HIPRscript files chunks of text that will be completely ignored
by the interpreter. Such a piece of text is known as a comment.
They can be used to explain to anyone reading the source file why you
chose to say certain things or why you chose to express things in
certain ways. This can be useful if someone else wishes to work on the
file after you have finished with it, or if you wish to be reminded
what you were doing last when you come back to it. Comments can also
be used to force the translator to ignore large chunks of your source
file. This is particularly useful for tracking down errors in your
source file. There are two forms of comments in HIPRscript:
Anything on a line following a hash sign # is ignored, including the hash sign itself. If you want a hash sign then use the \# tag.
The special tag \comment{...} simply causes everything in its single argument to be ignored. This is good for commenting out large blocks of text in a single swoop.
Comments can be nested inside one another with no problems.
We now present a complete listing of all the tags that can be used in HIPRscript, together with explanations and hints for their use.
Line comment; the remainder of the current line is ignored.
Non-breaking space; a space that will never be substituted by a line-break.
Backslash: \
Hash sign: #
Produces a small colored blob in the HTML output only. The optional COLOR argument can take the values yellow or red. The default value is yellow.
Forces a line break. Note that in a few situations this will cause a LaTeX error since LaTeX doesn't like being told where to break lines. If this happens use the \html tag to ignore the line break in the LaTeX output.
Starts a new chapter with a title given by HEADING. This is the second largest document division in HIPR.
Block comment --- simply ignores everything within its argument and produces no output.
Degree symbol: °
See the \description tag.
Description list. One of three HIPRscript list types --- this one is used for lists where each list item consists of a brief label (known as the topic) followed by a block of text (known as the discussion). The argument of this tag must consist solely of alternate \dt and \dd tags. The \dt tag comes first and its argument gives the Description Topic. The \dd tag then follows with the Description Discussion as its argument. Any number of pairs of \dt and \dd tags may be inserted.
Example --- the following fragment of HIPRscript:
\description{
\dt{HIPR}
\dd{The Hypermedia Image Processing Reference.}
\dt{HIPRscript}
\dd{The language used to create HIPR.}
}produces the following effect:
- HIPR
The Hypermedia Image Processing Reference.
- HIPRscript
The language used to create HIPR.
Note that the \dd tag's argument can contain any other tags, including additional lists. The \dt tag on the other hand should only contain raw text and appearance changing tags such as \em.
See the \description tag.
Inserts an italicized `e.g.': e.g.
Causes TEXT to be displayed in an italic font.
Enumerated list. One of three HIPRscript list types --- this one is used for ordered lists where each item is to be numbered in consecutive order. HIPRscript will take care of the numbering automatically. The argument of this tag consists of a mixture of text and \item tags. Each \item tag encountered tells HIPRscript that a new list item is starting, complete with a new number.
Example --- the following HIPRscript fragment:
\enumerate{
\item Capture an image.
\item Choose a threshold value.
\item Apply thresholding to produce a binary image.
}produces the following effect:
- Capture an image.
- Choose a threshold value.
- Apply thresholding to produce a binary image.
\enumerate lists can contain most other sorts of tag, including other list tags. Usually a different numbering scheme (e.g. roman numerals or letters) is used for nested \enumerate lists.
Displayed equation. Used for mathematical equations which are to be set apart from the text that describes them. The EQUATION argument describes the equation using LaTeX format. i.e. the code that goes here is exactly what you would type to produce the equation in LaTeX. The GIF_FILE argument is the name of a file (without the .gif suffix) in the eqns sub-directory where an image representing that equation will be stored. It is possible to get HIPRscript to generate the GIF file automatically from the EQUATION argument, but note that this involves many extra complications which are described below in the subsection on Using Figure, Equation and Imageref Tags. The optional SIZE argument can take values of small, large or huge and determines the scaling of the displayed equation. The default is large.
Similar to the \eqnd tag except that it produces an in-line equation and takes no optional SIZE argument.
Inserts an italicized `etc.': etc.
Include a figure at this point in the text. The FIG_FILE argument refers to two similarly named files in the figs sub-directory that contain the image to be included in two different formats, GIF and encapsulated PostScript. The FIG_FILE argument should specify just the stem-name of the files. To this HIPRscript will add .eps for the PostScript file and .gif for the GIF file. It is possible to get HIPRscript to generate the GIF file automatically from the PostScript file, but note that this involves many extra complications which are described below in the subsection on Using Figure, Equation and Imageref Tags. The CAPTION argument gives the text that will go with the figure, and may contain appearance changing tags such as \em and also cross-reference tags such as \ref. The optional SCALE argument gives the scaling of the figure. A size of 1 (the default) means that the image will be included at its `natural' size. A number less than this will reduce the size, larger numbers will increase it. Note that HIPRscript will assign a figure number to your figure automatically.
Used to reference a particular figure in the text. The FIG_FILE argument should match up with the FIG_FILE argument of a \fig tag somewhere in the same HIPRscript file. That will be the figure to which the \figref refers. The visible effect of the tag is to insert the text: `Figure N' where N is the number of the figure concerned.
Places a solid colored horizontal dividing bar across the screen in the HTML output only.
Places a thin horizontal dividing rule across the screen in the HTML output only.
Process the TEXT argument as if it were normal HIPRscript, but only produce HTML output. Nothing appears in the LaTeX output for this tag.
Inserts an italicized `i.e.': i.e.
Refer to an image in the images sub-directory. The IMAGE_FILE argument should give the name of the image file concerned, minus any file suffix such as .gif. The visible effect of this tag depends upon whether you are looking at the HTML or the LaTeX output. In the HTML output, by default it creates a hyperlink to the named image, in the form of a small thumbnail image. The thumbnail image is in fact just a reduced size version of the full image and is found in the thumbs sub-directory. It is possible to get HIPRscript to generate the thumbnail automatically from the full size image, but note that this involves many extra complications which are described below in the subsection on Using Figure, Equation and Imageref Tags. In the LaTeX output, this tag simply prints the IMAGE_FILE argument in typewriter font. The optional argument MODE can be used to alter the appearance of the HTML output slightly (it doesn't affect the LaTeX though). Setting MODE to text means that the imagelink will simply appear as the name of the image file rather than as a thumbnail. Setting MODE to both causes the link to appear both as text and as a thumbnail. Setting MODE to thumbnail produces the default behavior.
Includes the HIPRscript file named by the FILE argument plus a .hpr extension, into the current file. In the HTML output, this inclusion appears as a hyperlink to the named file. The text of the hyperlink is given by the TEXT argument. In the LaTeX output there is no such link --- the named file is included as if its entire contents had been typed into the current file at that point. The TEXT argument is ignored in the LaTeX output.
Includes the HIPRscript file named by the FILE argument plus a .hpr extension, into the current file. This is rather like the \inc tag except that TEXT is printed in both the HTML and the LaTeX output. In the HTML output, TEXT acts as a hyperlink to the included file. In the LaTeX output, TEXT is merely printed immediately before the named file is included.
Acts identically to the \inc tag, except that FILE is treated as a full filename of the file to be linked in, including any path information.
Creates an entry in the HIPR index. ENTRY1, ENTRY2 and so on give the names of topic entries in the index. Each index entry may have up to three levels of nesting in order to specify the entry precisely. An entry with more than one level of nesting is indicated by a ENTRY argument containing one or two | symbols. The | symbols are used as separators between the different levels in the entry.
For instance if we wanted an index entry to appear under the general category of `Edge detectors' and then within that category, under `Canny', then we would have an entry argument that looked like: {Edge detectors|Canny}.
Note that every ENTRY argument in the whole of HIPR must be unique. We can only have one place in HIPR which has the index entry {Edge detectors|Canny} for instance. However, we could have another entry for {Edge detectors|Roberts} for instance.
The TEXT argument indicates which chunk of HIPRscript is to be pointed to by the index entry and can contain almost anything. It should not however contain any \target or \title tags.
A particular place in HIPR can have more than one index entry associated with it. Simply use as many ENTRY arguments as you need.
Like the \inc tag, this tag includes a named file into the current one. This time however, the effect for both HTML and LaTeX is as if the contents of the named file had been inserted directly into the current file in the tag's place. No links are created.
Marks the beginning of a list item in \enumerate and \itemize lists. It gives an error if used anywhere else.
Itemized list. One of three HIPRscript list types --- this one is used for unordered lists where each item is to be marked with a `bullet', but not numbered. The argument of this tag consists of a mixture of text and \item tags. Each \item tag encountered tells HIPRscript that a new list item is starting, and causes a bullet to be printed.
Example --- the following HIPRscript fragment:
\itemize{
\item Available on-line.
\item Extensive cross-referencing.
\item Uses Netscape browser.
}produces the following effect:
- Available on-line.
- Extensive cross-referencing.
- Uses Netscape browser.
\itemize lists can contain most other sorts of tag, including other list tags. Usually different bullet styles are used for nested \itemize lists.
Process the TEXT argument as if it were normal HIPRscript, but only produce LaTeX output. Nothing appears in the HTML output for this tag.
A special tag that produces a nicely formatted version of the LaTeX
tradename. In the hardcopy version it prints as: `
'.
In the hypermedia version it prints simply as: `LaTeX'.
Causes navigation buttons to appear in the HTML version of HIPR. It has no effect on the LaTeX output. LEFT, RIGHT and UP should be the names of other HIPRscript files within HIPR minus the .hpr suffix. The navigation buttons appear at the top of HTML page, and, if the page is more than about a screenful, are duplicated at the bottom. If there is no appropriate link for any of the arguments, then simply use a pair of empty braces for that argument, and no navigation button will be generated for that direction.
For instance the tag:
\links{}{erode}{morops}creates a `right' navigation button leading to the erode.htm worksheet, and an `up' button leading to the morops.htm section.
See the section on Navigation Buttons for more information about navigation buttons.
Minus sign. This is slightly different from a hyphen and should be used instead of a simple `-' when a minus sign is intended. e.g. \minus^7 produces `-7'. It will probably only cause a noticeable difference in the hardcopy output.
Causes a pagebreak. Only affects the LaTeX output.
Starts a new `part' with a title given by the HEADING argument. This is the largest document division in HIPR.
Plus-or-minus symbol: ±
Indents the HIPRscript contained in the TEXT argument from the left margin slightly.
Passes the HTML argument directly into the HTML output with no processing. It differs from the \html tag in that the HTML argument is not treated as HIPRscript to be further processed. Has no effect on the LaTeX output.
Passes the LATEX argument directly into the LaTeX output with no processing. It differs from the \latex tag in that the LATEX argument is not treated as HIPRscript to be further processed. Has no effect on the HTML output.
In the HTML output, this creates a hyperlink using TEXT pointing at the HIPRscript file specified by FILE (minus the .hpr file extension as usual).
Starts a new section with a title given by the HEADING argument. This is the third largest document division in HIPR.
A squared symbol: ²
Causes the HIPRscript within TEXT to be displayed in a bold font.
Starts a new subsection with a title given by the HEADING argument. This is the fourth largest document division in HIPR.
Starts a new subsubsection with a title given by the HEADING argument. This is the fifth largest document division in HIPR, and the smallest.
Used for specifying the data to go into a table created with the \table tag. The text in COL1 goes in the first column, the text in COL2 goes in the second column and so on. There should be the same number of arguments as there are data columns in the table, and the number of characters in each argument should be less than the width of the table columns. See the \table tag for details.
Creates a table at the current place in the document. The last argument contains the actual data that will go into the table. The previous arguments define the column layout of the table. If a COL argument is a number, then that indicates a data column. The number gives the width in characters of that column. Data appears left justified within the column. If the COL argument is a | character, this indicates an internal vertical dividing line. If you use two such arguments in a row, then you will have a double vertical dividing line.
The DATA argument contains the body of the table. It must consist solely of \tab tags (specifying the data to go in each column), and \tabline tags (specifying horizontal lines in the table).
Note that HIPRscript will automatically put lines around the outside of a table and so these do not need to be specified.
As an example, the following fragment of HIPRscript:
\table{6}{|}{|}{8}{8}{8}{
\tab{Type}{Test A}{Test B}{Test C}
\tabline
\tab{1}{Yes}{Yes}{No}
\tab{2}{No}{Yes}{No}
\tab{3}{Yes}{Yes}{Yes}
}
produces the following:
-------------------------------- | Type || Test A Test B Test C | |------++------------------------| | 1 || Yes Yes No | | 2 || No Yes No | | 3 || Yes Yes Yes | --------------------------------
Note that at the time of writing not all browsers support proper tables, and so tables are implemented rather crudely in HTML output. Significantly better looking tables appear in the LaTeX output.
Used between \tab tags within a table to produce a horizontal line across the table. Note that the \table tag itself produces horizontal lines at the top and bottom of the table.
Associates the chunk of HIPRscript in TEXT with LABEL for reference to by a \textref tag. LABEL must be a single word and can only contain alphanumeric characters. TEXT can be any bit of HIPRscript.
Like the \ref tag, this creates a hyperlink around TEXT to the HIPRscript file named in FILE. However, whereas following a \ref tag automatically takes a user to the top of that file, the \textref tag allows you to jump into the middle of a file. The point to be jumped to must be marked with a \target tag and that tag's LABEL argument must match the LABEL argument used here.
Tilde: ~
A multiplication symbol: ×
Most HTML documents are associated with a document title which does not appear on the page itself, but which is often shown separately by the HTML browser. This tag allows you to specify the HTML document title. It has no visible effect on the LaTeX output, although it does create an essential internal LaTeX cross-reference. This tag must be positioned near the top of the HIPRscript file, just after the first document sectioning command in the file.(i.e. after the first \chapter, \section etc. tag in the file). Therefore the only tags that normally appear before a \title tag are a sectioning tag and a \links tag. The \title tage should only be used once in any given file.
Causes the HIPRscript contained in TEXT to be displayed in a typewriter font.
TEXT is displayed in both HTML and LaTeX output exactly as it appears in the HIPRscript file. Unlike normal HIPRscript text, all whitespace is preserved as is. The text is also normally displayed in a fixed space typewriter font.
One of the more useful features of HIPR is its extensive index. As mentioned above, index entries are produced using the \index tag within HIPRscript pages. However, whereas most sections of HIPR are produced by single HIPRscript files, the index is contributed to by almost all the HIPRscript files. Hence a slightly different procedure is used to generate the index.
What actually happens is that every time a HIPRscript file is processed, all the index entry information in that file is written into a corresponding IDX file in the index sub-directory. To generate the index section, what we have to do is scan this sub-directory, collate all the information in all the IDX files there, and then use this information to produce the index pages. In fact, the index section is itself written to the src sub-directory as a HIPRscript file. The scanning and analysis of the IDX files are performed by another Perl program called hiprindx.pl, also found in the progs sub-directory.
Finally the HIPRscript file for the index is processed as normal to produce the required HTML and LaTeX index pages.
Summarizing, the sequence is as follows:
Note that this procedure can be somewhat simplified through the use of a makefile as described later.
Error messages are intended to be fairly self-explanatory. A typical one runs something like:
hiprgen - Error [chngehip(2)]: End of file in argument of \index
which means that an error was found on line 2 of the file chngehip.hpr. In this case the translator is saying that it encountered the end of the file before it had finished reading the argument of an \index tag. The most likely cause of this is a missing end-brace (}).
We present here a list of all the error messages you are likely to encounter when using HIPRscript, together with brief explanations of the likely cause.
It is not legal to have a single backslash at the end of a HIPRscript file or at the end of an argument to a tag that is to be processed as HIPRscript. If you do want a backslash, then you must use \\^. The final ^ is necessary to prevent the closing brace of the argument being escaped by the \.
Couldn't find the HIPRscript file specified on the command line to hiprgen.pl as filename. Make sure that the filename is spelled correctly and that the file does exist and is not read protected. Also make sure that when you run hiprgen.pl the current working directory is src. Finally note that when specifying filename on the command line, you should not add the suffix .hpr.
Couldn't create the HTML output file corresponding to the current HIPRscript file. Make sure that the html sub-directory exists and is writeable. Check also that if the HTML file to be produced already exists, then it should also be writeable, so that it can be overwritten with the new version.
Couldn't create the IDX output file corresponding to the current HIPRscript file. Make sure that the index sub-directory exists and is writeable. Check also that if the IDX file to be produced already exists, then it should also be writeable, so that it can be overwritten with the new version.
Couldn't create the LaTeX output file corresponding to the current HIPRscript file. Make sure that the tex sub-directory exists and is writeable. Check also that if the LaTeX file to be produced already exists, then it should also be writeable, so that it can be overwritten with the new version.
The file specified in an \input tag could not be found. Check that the file exists in the src sub-directory and is readable. Note also that filename should be specified without the hpr suffix.
Couldn't create the temporary file that HIPRscript uses while building up the HTML output. Check that the tex sub-directory is writeable to and that the temporary file does not already exist.
Couldn't create the temporary file that HIPRscript uses while building up the index output. Check that the tex sub-directory is writeable to and that the temporary file does not already exist.
Couldn't create the temporary file that HIPRscript uses while building up the LaTeX output. Check that the tex sub-directory is writeable to and that the temporary file does not already exist.
No terminating brace was found for the named tag before the end of the file was reached. Check to see that each opening brace at the start of an argument has a matching brace at the end of the argument. Also make sure that braces that do not delimit arguments are escaped with a backslash, e.g. \{
The \fig tag's scale parameter must be a number. Note that it can be a floating point number, e.g.: 0.8.
The \dd tag can only be used inside a \description list.
The \dt tag can only be used inside a \description list.
The \item tag should only be used within a \enumerate or \itemize list.
An invalid argument was given to the \blob tag. The only valid arguments are red or yellow. Note that the argument is in fact optional.
The string text was passed as an optional size argument to a \eqnd tag. The only allowed values are small, large and huge.
An \index tag must have at least two arguments --- one for the index entry and one being the bit of HIPRscript to be pointed to by the index entry. There may be more than one index entry argument, however.
The figure name passed as the first argument to a \fig tag must only contain alphanumeric characters.
The second argument to a \textref tag must match a corresponding \target tag's first argument, and hence must only contain alphanumeric characters.
The first argument to a \ref or \textref tag must refer to a HIPRscript file and must only contain alphanumeric characters.
The label specified as the first argument of a \target tag must only contain alphanumeric characters.
An invalid argument was passed to a \imageref tag.
All columns in a table created with a \table tag are of the same width, which is specified in one of the arguments to that tag. Subsequent \tab arguments which give the data to go into each column must not contain data that equal or exceed this width.
When started, hiprgen.pl must be passed a single argument specifying the HIPRscript file to be processed.
A figure created by a \figure must have been previously referenced in the text by a corresponding \figref tag.
In order to keep everything in order, whenever you make a change to a HIPRscript file, you should regenerate the corresponding LaTeX and HTML files as well. However, running hiprgen.pl on each such file, and keeping track of which files you've changed and which you haven't is a tedious and error-prone job. Fortunately there is a better way using a make utility.
Make utilities solve exactly the problem described above of keeping track of large collections of files which depend upon one another, and of regenerating just those files that need to be regenerated in a simple way. They are available for almost all computer systems, and can generally be obtained free from the Internet at the standard software archives for your machine if you don't have one already.
A make utility is used in conjunction with a special text file known as a makefile. This file is conventionally just called makefile and in HIPR you will find a ready prepared one in the src sub-directory suitable for use with UNIX make utilities (and with many MS-DOS implementations as well that automatically convert / to \ in pathnames). If you are not using one of these systems and wish to use the makefile then you will need to edit it slightly in order to set the pathnames to the important sub-directories correctly. Look at the top of the supplied makefile for guidance and consult the documentation on the make utility for your system for details.
You do not need to understand what this file does in order to use it --- just make sure that the current working directory is the src sub-directory, and then run the make program, normally by just typing make. If you have installed everything else correctly then this is all you will need to do. The make program will check to see which HIPRscript files have been modified since the corresponding HTML and LaTeX files were created, and will run hiprgen.pl on just those files.
The makefile will also allow you to generate the index relatively painlessly. Simply run make with the argument `index', e.g. by typing make index.
If you cannot use a make utility then it is of course still possible to regenerate HIPRscript files by hand and this is entirely appropriate for relatively small changes.
The tags \fig, \eqnl, \eqnd and \imageref all involve special files in addition to the standard HTML and LaTeX files that are created from a HIPRscript file. These additional files sometimes need to be supplied by the writer of the HIPRscript file, and in other cases, they can be generated automatically by hiprgen.pl. The following sections describe these additional files and where they come from.
Note that the facilities that enable hiprgen.pl to generate these additional files automatically are amongst the least portable aspects of HIPR. They were used extensively during the development of HIPR and are included as a bonus here for those experienced enough to make use of them. However, we cannot provide any support or advice other than that supplied here. Note that you should not even begin to think about using this feature unless you have a UNIX system. You will also need to obtain several other programs and utilities such as the PBMplus image manipulation utilities and GhostScript. Details are given in the relevant section of the Installation Guide.
Since the automatic generation of additional files for use with figures, equations and \imageref tags is so non-portable, this feature is disabled by default.
With both HTML and LaTeX, the picture that goes into a figure is included into the HTML or LaTeX from an external file in the figs sub-directory. In the case of HTML, this picture must be a GIF image file, whereas in the case of LaTeX, the picture must be stored in encapsulated PostScript (EPS) format. Therefore both GIF and EPS versions of each figure must be available in the figs sub-directory. The two versions are distinguished by their different file extensions: .gif and .eps, but otherwise have identical stemnames (which must match up with the first argument of a corresponding \fig tag.
It is possible to get hiprgen.pl to generate the GIF file automatically from the corresponding EPS file. This requires that you first install the special HIPR utility hfig2gif, as well as the PBMplus library, GhostScript and pstoppm.ps. Then you must edit the hiprgen.pl file, and near the top of the file you should change the line:
$AUTO_FIGURE = 0;
to:
$AUTO_FIGURE = 1;
From this point on, if, during the course of processing a HIPRscript file, a \fig tag is encountered for which there is a corresponding EPS file, but no GIF file, then a corresponding GIF file will be generated from the EPS file. If you subsequently change the EPS file and you want to force hiprgen.pl to regenerate a new matching GIF file, then simply delete the old GIF file.
At the time of writing, HTML provides no support for mathematical equations, unlike LaTeX which does. This situation may be remedied in the future, but for now we have had to use a workaround. Therefore, equations in HTML are included as small in-line images stored as GIF files in the eqns sub-directory. LaTeX does provide support for equations, and so no external files are required for the LaTeX versions of equations.
While these image-equations for use with HTML could be generated by hand, it is possible to get hiprgen.pl to generate the GIF file automatically from the LaTeX equation code contained in the equation tag. This requires that you first install the special HIPR utility heqn2gif, as well as the PBMplus library, GhostScript, pstoppm.ps and LaTeX. Then you must edit the hiprgen.pl file, and near the top of the file you should change the line:
$AUTO_EQUATION = 0;
to:
$AUTO_EQUATION = 1;
From this point on, if, during the course of processing a HIPRscript file, a \eqnl or \eqnd tag is encountered for which there is no corresponding GIF file then one will be generated from the LaTeX description of the equation. If you subsequently change this description and you want to force hiprgen.pl to regenerate a new matching GIF file, then simply delete the old GIF file.
In the HTML output files, \imageref tags cause a hyperlink to an image in the images sub-directory to be created. By default, this imagelink takes the form of a miniature version of the full-size image, known as a thumbnail. This thumbnail must be a GIF file and is stored in the thumbs sub-directory. The files have the slightly unconventional suffix .GIF (i.e. capitalized) in order to avoid confusion with the full-size images. Conventionally, thumbnails are a factor of four smaller than their parent image.
Various image manipulation utilities could be used to generate thumbnails by hand, but it is possible to get hiprgen.pl to generate the thumbnail automatically from the full-size image. This requires that you first install the special HIPR utility himg2thm and the PBMplus library. Then you must edit the hiprgen.pl file, and near the top of the file, you should change the line:
$AUTO_THUMBNAIL = 0;
to:
$AUTO_THUMBNAIL = 1;
From this point on, if, during the course of processing a HIPRscript file, a \imageref tag is encountered for which there is no corresponding thumbnail file, then one will be generated automatically. If you subsequently change the full-size image and you want to force hiprgen.pl to regenerate a new matching thumbnail, then simply delete the old thumbnail file and then re-run hiprgen.pl on any source file containing a reference to that image.
When it comes to producing smaller versions of images, not all images are equal. Some images contain fine detail which the standard reduction process, which uses the PBMplus utility pnmscale, destroys. So, for these images, an alternative reduction utility ppmsample has been provided. Whenever hiprgen.pl has to produce a thumbnail, it looks in a file called FINE.txt which contains a list of images that require special treatment. If the image to be reduced is in that file, then the HIPR utility himg2thm is called with an additional flag (-f) which tells it to use ppmsample if it is available. Details on how to compile and install ppmsample are provided in the himg2thm script.
©2003 R. Fisher, S. Perkins,
A. Walker and E. Wolfart.
