generated

[privoxy.git] / doc / webserver / user-manual / templates.html

diff --git a/doc/webserver/user-manual/templates.html b/doc/webserver/user-manual/templates.html
index d4b24f1..dbd8a60 100644 (file)
--- a/doc/webserver/user-manual/templates.html
+++ b/doc/webserver/user-manual/templates.html
@@ -4,8 +4,7 @@
 >Templates</TITLE
 ><META
 NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.64
-"><LINK
+CONTENT="Modular DocBook HTML Stylesheet Version 1.60"><LINK
 REL="HOME"
 TITLE="Privoxy User Manual"
 HREF="index.html"><LINK
@@ -75,49 +74,161 @@ NAME="TEMPLATES"
 >10. Templates</A
 ></H1
 ><P
-> When <SPAN
+> All <SPAN
 CLASS="APPLICATION"
 >Privoxy</SPAN
-> displays one of its internal 
- pages, such as a <A
-HREF="http://bogus_404_page.com"
+> built-in pages, i.e. error pages such as the 
+ <A
+HREF="http://show-the-404-error.page"
 TARGET="_top"
->404 Not Found error page</A
+><SPAN
+CLASS="QUOTE"
+>"404 - No Such Domain"</SPAN
+>
+ error page</A
+>, the <A
+HREF="http://ads.bannerserver.example.com/nasty-ads/sponsor.html"
+TARGET="_top"
+><SPAN
+CLASS="QUOTE"
+>"BLOCKED"</SPAN
+>
+ page</A
 >
+ and all pages of its <A
+HREF="http://config.privoxy.org/"
+TARGET="_top"
+>web-based
+ user interface</A
+>, are generated from <I
+CLASS="EMPHASIS"
+>templates</I
+>. 
  (<SPAN
 CLASS="APPLICATION"
 >Privoxy</SPAN
-> must be running for link to work as
- intended), it uses the appropriate template. On Linux, BSD, and Unix, these
- are located in <TT
+> must be running for the above links to work as
+ intended)</P
+><P
+> These templates are stored in a subdirectory of the <A
+HREF="config.html#CONFDIR"
+>configuration
+ directory</A
+> called <TT
 CLASS="FILENAME"
->/etc/privoxy/templates</TT
-> by default. These
- may be customized, if desired. <TT
+>templates</TT
+>. On unixish platforms,
+ this is typically
+ <A
+HREF="file:///etc/privoxy/templates/"
+TARGET="_top"
+><TT
 CLASS="FILENAME"
->cgi-style.css</TT
-> is used to
- control the HTML attributes (fonts, etc).</P
+>/etc/privoxy/templates/</TT
+></A
+>.</P
 ><P
-> The default 
-<A
-HREF="http://ads.bannerserver.example.com/nasty-ads/sponsor.html"
+> The templates are basically normal HTML files, but with place-holders (called symbols
+ or exports), which <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> fills at run time. You can
+ edit the templates with a normal text editor, should you want to customize them.
+ (<I
+CLASS="EMPHASIS"
+>Not recommended for the casual user</I
+>). Note that
+ just like in configuration files, lines starting with <TT
+CLASS="LITERAL"
+>#</TT
+> are
+ ignored when the templates are filled in.</P
+><P
+> The place-holders are of the form <TT
+CLASS="LITERAL"
+>@name@</TT
+>, and you will
+ find a list of available symbols, which vary from template to template,
+ in the comments at the start of each file. Note that these comments are not
+ always accurate, and that it's probably best to look at the existing HTML
+ code to find out which symbols are supported and what they are filled in with.</P
+><P
+> A special application of this substitution mechanism is to make whole
+ blocks of HTML code disappear when a specific symbol is set. We use this
+ for many purposes, one of them being to include the beta warning in all
+ our user interface (CGI) pages when <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+>
+ in in an alpha or beta development stage:</P
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>&#60;!-- @if-unstable-start --&#62;
+
+  ... beta warning HTML code goes here ...
+
+&#60;!-- if-unstable-end@ --&#62;</PRE
+></TD
+></TR
+></TABLE
+></P
+><P
+> If the "unstable" symbol is set, everything in between and including
+ <TT
+CLASS="LITERAL"
+>@if-unstable-start</TT
+> and <TT
+CLASS="LITERAL"
+>if-unstable-end@</TT
+>
+ will disappear, leaving nothing but an empty comment:</P
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>&#60;!--  --&#62;</PRE
+></TD
+></TR
+></TABLE
+></P
+><P
+> There's also an if-then-else construct and an <TT
+CLASS="LITERAL"
+>#include</TT
+>
+ mechanism, but you'll sure find out if you are inclined to edit the
+ templates ;-)</P
+><P
+> All templates refer to a style located at
+ <A
+HREF="http://config.privoxy.org/send-stylesheet"
 TARGET="_top"
->Blocked 
-(<SPAN
+><TT
+CLASS="LITERAL"
+>http://config.privoxy.org/send-stylesheet</TT
+></A
+>.
+ This is, of course, locally served by <SPAN
 CLASS="APPLICATION"
 >Privoxy</SPAN
-> needs to be running for page to display)</A
 >
- banner page with the bright red top 
- banner, is called just <SPAN
-CLASS="QUOTE"
->"<TT
+ and the source for it can be found and edited in the
+ <TT
 CLASS="FILENAME"
->blocked</TT
->"</SPAN
->. This 
- may be customized or replaced with something else if desired.&#13;</P
+>cgi-style.css</TT
+> template.</P
 ></DIV
 ><DIV
 CLASS="NAVFOOTER"