Source code: ref/file.htp



<BLOCK syntax>
<file execute="command-line" (output="filename" | redirect) [noerror]>
<file include="includefilename" [parameters ...]>
<file name>
<file [ name="filename" ] size[ = (byte|kbyte|mbyte|gbyte) ] [precision=n]>
<file [ name="filename" ] time[ ="format" ]>
<file [ name="filename" ] date[ ="format" ]>
<file search="searchpath">
<file template="templatefilename">
</BLOCK>

<BLOCK synopsis>

<STRONG>FILE</STRONG> has several optional parameters of differing purpose.
The output file's name, the current date and time, and the contents of
another file may be included.  Another file's time, date, or size may be
added to the output file as well.
<P>
As with all HTML, these tags do not have to be on their own line, so the
following is perfectly acceptable:

<htpcode>
    <EM>File "<FILE NAME>" last updated <FILE TIME>, <FILE DATE></EM>
</htpcode>

<P>
<h3><a name="name">NAME</a>, TIME, SIZE</h3>
<P>
To include information about another file, such as an archive file or
graphic image, specify its name with the NAME attribute followed by the
type of information to be displayed:

<htpcode>
    File image.gif <FILE NAME="image.gif" SIZE=KBYTE> kilobytes
    Last modified <FILE NAME="image.gif" TIME>, <FILE NAME="image.gif" DATE>
</htpcode>

<P>
For file size information, the value BYTE, KBYTE, etc. dictates how the
information is displayed.  In anything other than byte format, the information
is displayed in floating-point notation.  The amount of precision (the number
of digits to the right of the decimal point) can be set with the optional
PRECISION attribute.  The default precision is zero (0), which means no
fractional portion is displayed.
<P>
At the request of many people, the TIME and DATE attributes will now accept
formatting characters that are passed directly into the ANSI C library
function.  This allows for the time and date to be displayed in virtually
any format.  Users not wishing to mess around with this should stick to the
default format, which is used if no formatting value is specified (i.e.,
just using <FILE TIME>).
<P>
Consult any C programmer's guide discussing the standard C library function
strftime() for information on how to build a format string.  If unsure, ask
an experienced C programmer for help, or consider just sticking to the
default formatting.
<P>
<h3><a name="include">INCLUDE</a></h3>
<P>
INCLUDE files are pre-processed as any other file.  The resulting text is
incorporated into the HTML output as if the file had been copied into the
source at the same location as the FILE markup tag.
<P>
htp will automatically convert slashes and backslashes to match the operating
system's directory separator.
<P>
Additional parameters can be set in the FILE INCLUDE tag, which are
interpreted as macros that are "passed" to the included file.  The macros
are available only to the include file (and any macros or included files it
holds).  After the file is completely included, the macros are no longer
available.  So:

<htpcode>
    <FILE INCLUDE="include.hti" name="Jim Nelson" email="jnelson@crl.com">
    This tag will fail: <USE name>
</htpcode>

<P>
Macros named "name" and "email" are set, and available inside the included
file.  They are not available, however, past the tag (which is why the
second statement will fail.)
<P>
<h3><a name="template">TEMPLATE</a></h3>
<P>
A template file is nothing more than a default include file, one that is
included once the input text has been completely processed.  So, an input
file can define many "standard" macros, which are then expanded by a
template file to form a consistent page layout.
<P>
The template file can be set many times, but only the last filename specified
will be processed by htp.  If multiple template files need to be included,
specify one template file, and from that file use FILE INCLUDE to branch off.
<P>
Template files are most useful when placed inside an htp
<A HREF="default.html">default file</A>.
<P>
<h3><a name="search">SEARCH</a></h3>
<P>
A search path can be specified, which is searched if an include file cannot
be found.  This is handy to keep a set of "common" include files that many
documents in many directories may need to access.  More than one directory
can be specified in the search path, if they are separated by a semi-colon.
Spaces should not precede or trail the search path string.
<P>
When htp starts, the search path is clear.  FILE SEARCH would be a handy
command to use in an <A HREF="default.html">htp defaults file</A>.
<P>
<h3><a name="execute">EXECUTE</a></h3>
<P>
When FILE EXECUTE is used, htp will launch a program (as specified by the
EXECUTE attribute) and include its output as if a FILE INCLUDE was performed
on the file.  Either the OUTPUT or REDIRECT attribute must also be included.
<P>
OUTPUT specifies the file the command will produce.  This is used if the
program is either hard-coded to produce output to a particular file, or
relies on one of its command-line arguments to determine where to place
the output.  The output file is deleted after its results have been
imported into the output file.
<P>
If the program produces output straight to standard output (as most
UNIX and some DOS programs do), then the REDIRECT attribute can be
used.  In this case htp will take care of the redirection.  Depending
on the OS features it will either append a '&gt;' and the name of a
temporary file or it will use pipe mechanism to directly redirect
without temporary files.
<P>
htp will halt processing with an error if the executable exits with an
error code of anything but zero (0).  Some programs, however, do not specify
an error code when exiting, so the exit code is undetermined.  If htp should
ignore the error code, specify the NOERROR attribute.

</BLOCK>