diff options
Diffstat (limited to 'docs/manual/mod/mod_include.html')
| -rw-r--r-- | docs/manual/mod/mod_include.html | 469 |
1 files changed, 0 insertions, 469 deletions
diff --git a/docs/manual/mod/mod_include.html b/docs/manual/mod/mod_include.html deleted file mode 100644 index b296e77c66..0000000000 --- a/docs/manual/mod/mod_include.html +++ /dev/null @@ -1,469 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_include</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Module mod_include</H1> - -<p>This module provides for server-parsed html documents.</p> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Base -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_include.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> includes_module -</P> - -<h2>Summary</h2> - -<p>This module provides a handler which will process files before they -are sent to the client. The processing is controlled by specially -formated SGML comments, referred to as <em>elements</em>. These -elements allow conditional text, the inclusion other files or -programs, as well as the setting and printing of environment -variables.</p> - -<H2>Directives</H2> -<UL> -<LI><A HREF="#xbithack">XBitHack</A> -</UL> - -<p>See also: <a href="core.html#options">Options</a> -and <a href="mod_mime.html#addhandler">AddHandler</a>.</p> - - -<H2>Enabling Server-Side Includes</H2> - -<p>Server Side Includes are implemented by the <code>INCLUDES</code> -<a href="../filter.html">filter</a>. If documents containing -server-side include directives are given the extension .shtml, the -following directives will make Apache parse them and assign the -resulting document the mime type of <CODE>text/html</CODE>: -</p> - -<blockquote><code> -AddType text/html .shtml<br> -<FilesMatch "\.shtml[.$]"><br> - SetOutputFilter INCLUDES<br> -</FilesMatch> -</code></blockquote> - -<p>The following directive must be given for the directories containing -the shtml files (typically in a <CODE><Directory></CODE> section, -but this directive is also valid .htaccess files if <CODE>AllowOverride -Options</CODE> is set):</p> - -<blockquote><code> -Options +Includes -</code></blockquote> - -<p>Alternatively the <A HREF="#xbithack"><CODE>XBitHack</CODE></A> -directive can be used to parse normal (<CODE>text/html</CODE>) files, -based on file permissions.</p> - -<p>For backwards compatibility, documents with mime type -<CODE>text/x-server-parsed-html</CODE> or -<CODE>text/x-server-parsed-html3</CODE> will also be parsed -(and the resulting output given the mime type <CODE>text/html</CODE>) -as will documents with the handler <code>server-parsed</code>. - -<H2>Basic Elements</H2> - -The document is parsed as an HTML document, with special commands embedded -as SGML comments. A command has the syntax: - -<BLOCKQUOTE><CODE> -<!--#</CODE><EM>element attribute=value attribute=value ...</EM> -<CODE> --> -</CODE></BLOCKQUOTE> - -The value will often be enclosed in double quotes; many commands only allow -a single attribute-value pair. Note that the comment terminator -(<SAMP>--></SAMP>) should be preceded by whitespace to ensure that it -isn't considered part of an SSI token. -<P> -The allowed elements are:<P> - -<DL> - -<DT><STRONG>config</STRONG> -<DD> -This command controls various aspects of the parsing. The valid attributes -are: -<DL> -<DT>errmsg -<DD>The value is a message that is sent back to the client if an error occurs -whilst parsing the document. -<DT>sizefmt -<DD>The value sets the format to be used which displaying the size of a file. -Valid values are <CODE>bytes</CODE> for a count in bytes, or -<CODE>abbrev</CODE> for a count in Kb or Mb as appropriate. -<DT>timefmt -<DD>The value is a string to be used by the <CODE>strftime(3)</CODE> library -routine when printing dates. -</DL> - -<DT><STRONG><a name="echo">echo</a></STRONG> -<DD> -This command prints one of the include variables, defined below. -If the variable is unset, it is printed as <CODE>(none)</CODE>. -Any dates printed are subject to the currently configured <CODE>timefmt</CODE>. - -Attributes: -<DL> -<DT>var -<DD>The value is the name of the variable to print. -<DT>encoding -<DD>Specifies how Apache should encode special characters contained -in the variable before outputting them. If set to "none", no encoding -will be done. If set to "url", then URL encoding (also known as -%-encoding; this is appropriate for use within URLs in links, etc.) -will be performed. At the start of an <CODE>echo</CODE> element, -the default is set to "entity", resulting in entity encoding (which -is appropriate in the context of a block-level HTML element, eg. -a paragraph of text). This can be changed by adding an -<CODE>encoding</CODE> attribute, which will remain in effect until -the next <CODE>encoding</CODE> attribute is encountered or the -element ends, whichever comes first. Note that the -<CODE>encoding</CODE> attribute must <EM>precede</EM> the corresponding -<CODE>var</CODE> attribute to be effective, and that only special -characters as defined in the ISO-8859-1 character encoding will be -encoded. This encoding process may not have the desired result if -a different character encoding is in use. -Apache 1.3.12 and above; previous versions do no encoding. - -</DL> - -<DT><STRONG>exec</STRONG> -<DD> -The exec command executes a given shell command or CGI script. -The IncludesNOEXEC <A HREF="core.html#options">Option</A> disables this command -completely. The valid attributes are: -<DL> -<DT>cgi -<DD> -The value specifies a (%-encoded) URL relative path to the CGI script. -If the path does not begin with a (/), then it is taken to be relative to -the current document. The document referenced by this path is invoked -as a CGI script, even if the server would not normally recognize it as -such. However, the directory containing the script must be enabled for -CGI scripts (with <A HREF="mod_alias.html#scriptalias">ScriptAlias</A> -or the ExecCGI <A HREF="core.html#options">Option</A>).<P> -The CGI script is given the PATH_INFO and query string (QUERY_STRING) of the -original request from the client; these cannot be specified in the URL path. -The include variables will be available to the script in addition to the -standard <A HREF="mod_cgi.html">CGI</A> environment.<P> -If the script returns a Location: header instead of output, then this -will be translated into an HTML anchor.<P> -The <CODE>include virtual</CODE> element should be used in preference to -<CODE>exec cgi</CODE>. -<DT>cmd -<DD>The server will execute the given string using <CODE>/bin/sh</CODE>. -The include variables are available to the command. -</DL> - -<DT><STRONG>fsize</STRONG> -<DD> -This command prints the size of the specified file, subject to the -<CODE>sizefmt</CODE> format specification. Attributes: -<DL> -<DT>file -<DD>The value is a path relative to the directory containing the current -document being parsed. -<DT>virtual -<DD>The value is a (%-encoded) URL-path relative to the current document being -parsed. If it does not begin with a slash (/) then it is taken to be relative -to the current document. -</DL> - -<DT><STRONG>flastmod</STRONG> -<DD> -This command prints the last modification date of the specified file, -subject to the <CODE>timefmt</CODE> format specification. The attributes are -the same as for the <CODE>fsize</CODE> command. - -<DT><STRONG>include</STRONG> -<DD> -This command inserts the text of another document or file into the parsed -file. Any included file is subject to the usual access control. If the -directory containing the parsed file has the -<A HREF="core.html#options">Option</A> -IncludesNOEXEC set, and the including the document would cause a program -to be executed, then it will not be included; this prevents the execution of -CGI scripts. Otherwise CGI scripts are invoked as normal using the complete -URL given in the command, including any query string. -<!--%plaintext <?INDEX CGI scripts, {\tt include} element and> --> -<P> - -An attribute defines the location of the document; the inclusion is done for -each attribute given to the include command. The valid attributes are: -<DL> -<DT>file -<DD>The value is a path relative to the directory containing the current -document being parsed. It cannot contain <CODE>../</CODE>, nor can it be an -absolute path. The <CODE>virtual</CODE> attribute should always be used -in preference to this one. -<DT>virtual -<DD>The value is a (%-encoded) URL relative to the current document being -parsed. The URL cannot contain a scheme or hostname, only a path and -an optional query string. If it does not begin with a slash (/) then it -is taken to be relative to the current document. -</DL> -A URL is constructed from the attribute, and the output the server -would return if the URL were accessed by the client is included in the parsed -output. Thus included files can be nested. - -<DT><STRONG>printenv</STRONG> -<DD>This prints out a listing of all existing variables and their values. - Starting with Apache 1.3.12, special characters are entity encoded (see the - <A HREF="#echo"><CODE>echo</CODE></A> element for details) before being - output. No attributes. -<DD>For example: <CODE><!--#printenv --></CODE> -<DD>Apache 1.2 and above. - -<DT><STRONG>set</STRONG> -<DD>This sets the value of a variable. Attributes: -<DL> -<DT>var -<DD>The name of the variable to set. -<DT>value -<DD>The value to give a variable. -</DL> -For example: - <CODE><!--#set var="category" value="help" --></CODE> -<DD>Apache 1.2 and above. - -</DL> - -<H2>Include Variables</H2> - -In addition to the variables in the standard CGI environment, these are -available for the <CODE>echo</CODE> command, for <CODE>if</CODE> and -<CODE>elif</CODE>, and to any program invoked by the document. - -<DL> -<DT>DATE_GMT -<DD>The current date in Greenwich Mean Time. -<DT>DATE_LOCAL -<DD>The current date in the local time zone. -<DT>DOCUMENT_NAME -<DD>The filename (excluding directories) of the document requested by the -user. -<DT>DOCUMENT_URI -<DD>The (%-decoded) URL path of the document requested by the user. Note that -in the case of nested include files, this is <EM>not</EM> then URL for the -current document. -<DT>LAST_MODIFIED -<DD>The last modification date of the document requested by the user. -</DL> -<P> - -<H2>Variable Substitution</H2> -<P> Variable substitution is done within quoted strings in most cases - where they may reasonably occur as an argument to an SSI directive. - This includes the - <SAMP>config</SAMP>, - <SAMP>exec</SAMP>, - <SAMP>flastmod</SAMP>, - <SAMP>fsize</SAMP>, - <SAMP>include</SAMP>, and - <SAMP>set</SAMP> - directives, as well as the arguments to conditional operators. - You can insert a literal dollar sign into the string using backslash - quoting: - -<PRE> - <!--#if expr="$a = \$test" --> -</PRE> - -<P> If a variable reference needs to be substituted in the middle of a - character sequence that might otherwise be considered a valid - identifier in its own right, it can be disambiguated by enclosing - the reference in braces, <EM>à la</EM> shell substitution: - -<PRE> - <!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" --> -</PRE> - -<P> This will result in the <SAMP>Zed</SAMP> variable being set to - "<SAMP>X_Y</SAMP>" if <SAMP>REMOTE_HOST</SAMP> is - "<SAMP>X</SAMP>" and <SAMP>REQUEST_METHOD</SAMP> is - "<SAMP>Y</SAMP>". - -<P> EXAMPLE: the below example will print "in foo" if the DOCUMENT_URI is -/foo/file.html, "in bar" if it is /bar/file.html and "in neither" -otherwise: -<PRE> - <!--#if expr="\"$DOCUMENT_URI\" = \"/foo/file.html\"" --> - in foo - <!--#elif expr="\"$DOCUMENT_URI\" = \"/bar/file.html\"" --> - in bar - <!--#else --> - in neither - <!--#endif --> -</PRE> - -<H2><A NAME="flowctrl">Flow Control Elements</A></H2> - -These are available in Apache 1.2 and above. The basic flow control -elements are: - -<PRE> - <!--#if expr="<EM>test_condition</EM>" --> - <!--#elif expr="<EM>test_condition</EM>" --> - <!--#else --> - <!--#endif --> -</PRE> - -<P> The <STRONG><CODE>if</CODE></STRONG> element works like an - if statement in a programming language. The test condition - is evaluated and if the result is true, then the text until - the next <STRONG><CODE>elif</CODE></STRONG>, <STRONG><CODE>else</CODE></STRONG>. - or <STRONG><CODE>endif</CODE></STRONG> element is included in the - output stream. - -<P> The <STRONG><CODE>elif</CODE></STRONG> or <STRONG><CODE>else</CODE></STRONG> - statements are be used the put text into the output stream - if the original test_condition was false. These elements - are optional. - -<P> The <STRONG><CODE>endif</CODE></STRONG> element ends the - <STRONG><CODE>if</CODE></STRONG> element and is required. - -<P> <EM>test_condition</EM> is one of the following: - -<DL> - -<DT><EM>string</EM><DD>true if <EM>string</EM> is not empty - -<DT><EM>string1</EM> = <EM>string2</EM> - <BR> - <EM>string1</EM> != <EM>string2</EM> - <BR> - <EM>string1</EM> < <EM>string2</EM> - <BR> - <EM>string1</EM> <= <EM>string2</EM> - <BR> - <EM>string1</EM> > <EM>string2</EM> - <BR> - <EM>string1</EM> >= <EM>string2</EM> - -<DD>Compare string1 with string 2. If string2 has the form <EM>/string/</EM> - then it is compared as a regular expression. - Regular expressions have the same syntax as those found in the - Unix <SAMP>egrep</SAMP> command. - -<DT>( <EM>test_condition</EM> ) - <DD>true if <EM>test_condition</EM> is true -<DT>! <EM>test_condition</EM> - <DD>true if <EM>test_condition</EM> is false -<DT><EM>test_condition1</EM> && <EM>test_condition2</EM> - <DD>true if both <EM>test_condition1</EM> and - <EM>test_condition2</EM> are true -<DT><EM>test_condition1</EM> || <EM>test_condition2</EM> - <DD>true if either <EM>test_condition1</EM> or - <EM>test_condition2</EM> is true -</DL> - -<P> "<EM>=</EM>" and "<EM>!=</EM>" bind more tightly than "<EM>&&</EM>" and - "<EM>||</EM>". - "<EM>!</EM>" binds most tightly. Thus, the following are equivalent: - -<PRE> - <!--#if expr="$a = test1 && $b = test2" --> - <!--#if expr="($a = test1) && ($b = test2)" --> -</PRE> - -<P> Anything that's not recognized as a variable or an operator is - treated as a string. Strings can also be quoted: <EM>'string'</EM>. - Unquoted strings can't contain whitespace (blanks and tabs) - because it is used to separate tokens such as variables. If - multiple strings are found in a row, they are concatenated using - blanks. So, - -<PRE> - <EM>string1 string2</EM> results in <EM>string1 string2</EM> - <EM>'string1 string2'</EM> results in <EM>string1 string2</EM> -</PRE> - -<H2>Using Server Side Includes for ErrorDocuments</H2> - -There is <A HREF="../misc/custom_errordocs.html">a document</A> which -describes how to use the features of mod_include to offer internationalized -customized server error documents. -<P> - -<HR> - -<H2><A NAME="xbithack">XBitHack</A> directive</H2> -<!--%plaintext <?INDEX {\tt XBitHack} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> XBitHack on|off|full<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>XBitHack off</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Options<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_include<P> - -The XBitHack directives controls the parsing of ordinary html documents. -This directive only affects files associated with the MIME type -<CODE>text/html</CODE>. XBitHack can take on the following values: -<DL> -<DT>off -<DD>No special treatment of executable files. -<DT>on -<DD>Any file that has the user-execute bit set will be treated as a -server-parsed html document. -<DT>full -<DD>As for <CODE>on</CODE> but also test the group-execute bit. If it -is set, then set the Last-modified date of the returned file to be the -last modified time of the file. If it is not set, then no last-modified date -is sent. Setting this bit allows clients and proxies to cache the result of -the request. -<P><STRONG>Note:</STRONG> you would not want to use this, for example, when you -<CODE>#include</CODE> a CGI that produces different output on each hit -(or potentially depends on the hit). -</DL> -<P> - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> |