Add a missing word

[privoxy.git] / doc / source / user-manual.sgml

diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml
index 9e04b1a..ee40787 100644 (file)
--- a/doc/source/user-manual.sgml
+++ b/doc/source/user-manual.sgml
@@ -36,7 +36,7 @@
                 This file belongs into
                 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
 
                 This file belongs into
                 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
 

- $Id: user-manual.sgml,v 2.176 2013/11/24 14:27:09 fabiankeil Exp $
+ $Id: user-manual.sgml,v 2.180 2014/05/05 09:48:36 fabiankeil Exp $

 
  Copyright (C) 2001-2013 Privoxy Developers http://www.privoxy.org/
  See LICENSE.
 
  Copyright (C) 2001-2013 Privoxy Developers http://www.privoxy.org/
  See LICENSE.


@@ -62,7 +62,7 @@
  </subscript>
 </pubdate>
 
  </subscript>
 </pubdate>
 

-<pubdate>$Id: user-manual.sgml,v 2.176 2013/11/24 14:27:09 fabiankeil Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 2.180 2014/05/05 09:48:36 fabiankeil Exp $</pubdate>

 
 <!--
 
 
 <!--
 


@@ -1985,23 +1985,23 @@ for details.
 
 <para>
  Generally, an URL pattern has the form
 
 <para>
  Generally, an URL pattern has the form

- <literal>&lt;domain&gt;&lt;port&gt;/&lt;path&gt;</literal>, where the
- <literal>&lt;domain&gt;</literal>, the <literal>&lt;port&gt;</literal>
+ <literal>&lt;host&gt;&lt;port&gt;/&lt;path&gt;</literal>, where the
+ <literal>&lt;host&gt;</literal>, the <literal>&lt;port&gt;</literal>

  and the <literal>&lt;path&gt;</literal> are optional. (This is why the special
  <literal>/</literal> pattern matches all URLs). Note that the protocol
  portion of the URL pattern (e.g. <literal>http://</literal>) should
  <emphasis>not</emphasis> be included in the pattern. This is assumed already!
 </para>
 <para>
  and the <literal>&lt;path&gt;</literal> are optional. (This is why the special
  <literal>/</literal> pattern matches all URLs). Note that the protocol
  portion of the URL pattern (e.g. <literal>http://</literal>) should
  <emphasis>not</emphasis> be included in the pattern. This is assumed already!
 </para>
 <para>

- The pattern matching syntax is different for the domain and path parts of
- the URL. The domain part uses a simple globbing type matching technique,
+ The pattern matching syntax is different for the host and path parts of
+ the URL. The host part uses a simple globbing type matching technique,

  while the path part uses more flexible
  <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
   Expressions</quote></ulink> (POSIX 1003.2).
 </para>
 <para>
  The port part of a pattern is a decimal port number preceded by a colon
  while the path part uses more flexible
  <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
   Expressions</quote></ulink> (POSIX 1003.2).
 </para>
 <para>
  The port part of a pattern is a decimal port number preceded by a colon

- (<literal>:</literal>). If the domain part contains a numerical IPv6 address,
+ (<literal>:</literal>). If the host part contains a numerical IPv6 address,

  it has to be put into angle brackets
  (<literal>&lt;</literal>, <literal>&gt;</literal>).
 </para>
  it has to be put into angle brackets
  (<literal>&lt;</literal>, <literal>&gt;</literal>).
 </para>


@@ -2011,7 +2011,7 @@ for details.
   <term><literal>www.example.com/</literal></term>
   <listitem>
    <para>
   <term><literal>www.example.com/</literal></term>
   <listitem>
    <para>

-    is a domain-only pattern and will match any request to <literal>www.example.com</literal>,
+    is a host-only pattern and will match any request to <literal>www.example.com</literal>,

     regardless of which document on that server is requested. So ALL pages in
     this domain would be covered by the scope of this action. Note that a
     simple <literal>example.com</literal> is different and would NOT match.
     regardless of which document on that server is requested. So ALL pages in
     this domain would be covered by the scope of this action. Note that a
     simple <literal>example.com</literal> is different and would NOT match.


@@ -2022,7 +2022,7 @@ for details.
   <term><literal>www.example.com</literal></term>
   <listitem>
    <para>
   <term><literal>www.example.com</literal></term>
   <listitem>
    <para>

-    means exactly the same. For domain-only patterns, the trailing <literal>/</literal> may
+    means exactly the same. For host-only patterns, the trailing <literal>/</literal> may

     be omitted.
    </para>
   </listitem>
     be omitted.
    </para>
   </listitem>


@@ -2071,6 +2071,15 @@ for details.
    </para>
   </listitem>
  </varlistentry>
    </para>
   </listitem>
  </varlistentry>

+ <varlistentry>
+  <term><literal>10.0.0.1/</literal></term>
+  <listitem>
+   <para>
+    Matches any URL with the host address <literal>10.0.0.1</literal>.
+    (Note that the real URL uses plain brackets, not angle brackets.)
+   </para>
+  </listitem>
+ </varlistentry>

  <varlistentry>
   <term><literal>&lt;2001:db8::1&gt;/</literal></term>
   <listitem>
  <varlistentry>
   <term><literal>&lt;2001:db8::1&gt;/</literal></term>
   <listitem>


@@ -2094,11 +2103,13 @@ for details.
 
 
 <!--   ~~~~~       New section      ~~~~~     -->
 
 
 <!--   ~~~~~       New section      ~~~~~     -->

-<sect3><title>The Domain Pattern</title>
+<sect3 id="host-pattern"><title>The Host Pattern</title>

 
 <para>
 
 <para>

- The matching of the domain part offers some flexible options: if the
- domain starts or ends with a dot, it becomes unanchored at that end.
+ The matching of the host part offers some flexible options: if the
+ host pattern starts or ends with a dot, it becomes unanchored at that end.
+ The host pattern is often referred to as domain pattern as it is usually
+ used to match domain names and not IP addresses.

  For example:
 </para>
 
  For example:
 </para>
 


@@ -6534,9 +6545,35 @@ stupid-server.example.com/</screen>
  in a syntax that imitates <ulink url="http://www.perl.org/">Perl</ulink>'s
  <literal>s///</literal> operator. If you are familiar with Perl, you
  will find this to be quite intuitive, and may want to look at the
  in a syntax that imitates <ulink url="http://www.perl.org/">Perl</ulink>'s
  <literal>s///</literal> operator. If you are familiar with Perl, you
  will find this to be quite intuitive, and may want to look at the

- PCRS documentation for the subtle differences to Perl behaviour. Most
- notably, the non-standard option letter <literal>U</literal> is supported,
- which turns the default to ungreedy matching.
+ PCRS documentation for the subtle differences to Perl behaviour.
+</para>
+
+<para>
+ Most notably, the non-standard option letter <literal>U</literal> is supported,
+ which turns the default to ungreedy matching (add <literal>?</literal> to
+ quantifiers to turn them greedy again).
+</para>
+
+<para>
+ The non-standard option letter <literal>D</literal> (dynamic) allows
+ to use the variables $host, $origin (the IP address the request came from),
+ $path and $url. The will be replaced with the value they refer to before
+ the filter is executed.
+</para>
+
+<para>
+ Note that '$' is a bad choice as delimiter for dynamic filters as you
+ might end up with unintended variables if you use a variable name
+ directly after the delimiter. Variables will be resolved without
+ escaping anything, therefore you also have to be careful not to chose
+ delimiters that appear in the replacement text. For example '<' should
+ be save, while '?' will sooner or later cause conflicts with $url.
+</para>
+
+<para>
+ The non-standard option letter <literal>T</literal> (trivial) prevents
+ parsing for backreferences in the substitute. Use if you want to include
+ text like '$&' in your substitute without quoting.

 </para>
 
 <para>
 </para>
 
 <para>