Skip to content
This repository
Browse code

user manual ok

git-svn-id: https://erlyaws.svn.sourceforge.net/svnroot/erlyaws/trunk/yaws@260 9fbdc01b-0d2c-0410-bfb7-fb27d70d8b52
  • Loading branch information...
commit a481526f42506438d42df519c5ac12a5a91cada7 1 parent 2c9d438
Claes Wikstrom authored

Showing 5 changed files with 10,500 additions and 141 deletions. Show diff stats Hide diff stats

  1. +4,226 0 doc/a.eps
  2. +4,226 0 doc/b.eps
  3. +387 0 doc/layout.eps
  4. +1,395 141 doc/yaws.tex
  5. +266 0 doc/yaws_head.eps
4,226 doc/a.eps
4,226 additions, 0 deletions not shown
4,226 doc/b.eps
4,226 additions, 0 deletions not shown
387 doc/layout.eps
... ... @@ -0,0 +1,387 @@
  1 +%!PS-Adobe-2.0 EPSF-2.0
  2 +%%Title: /home/klacke/yaws/yaws/doc/layout.dia
  3 +%%Creator: Dia v0.88.1
  4 +%%CreationDate: Sat Nov 9 11:33:52 2002
  5 +%%For: klacke
  6 +%%Magnification: 1.0000
  7 +%%Orientation: Portrait
  8 +%%BoundingBox: 0 0 478 508
  9 +%%Pages: 1
  10 +%%BeginSetup
  11 +%%EndSetup
  12 +%%EndComments
  13 +%%BeginProlog
  14 +[ /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef
  15 +/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef
  16 +/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef
  17 +/.notdef /.notdef /space /exclam /quotedbl /numbersign /dollar /percent /ampersand /quoteright
  18 +/parenleft /parenright /asterisk /plus /comma /hyphen /period /slash /zero /one
  19 +/two /three /four /five /six /seven /eight /nine /colon /semicolon
  20 +/less /equal /greater /question /at /A /B /C /D /E
  21 +/F /G /H /I /J /K /L /M /N /O
  22 +/P /Q /R /S /T /U /V /W /X /Y
  23 +/Z /bracketleft /backslash /bracketright /asciicircum /underscore /quoteleft /a /b /c
  24 +/d /e /f /g /h /i /j /k /l /m
  25 +/n /o /p /q /r /s /t /u /v /w
  26 +/x /y /z /braceleft /bar /braceright /asciitilde /.notdef /.notdef /.notdef
  27 +/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef
  28 +/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef
  29 +/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef
  30 +/space /exclamdown /cent /sterling /currency /yen /brokenbar /section /dieresis /copyright
  31 +/ordfeminine /guillemotleft /logicalnot /hyphen /registered /macron /degree /plusminus /twosuperior /threesuperior
  32 +/acute /mu /paragraph /periodcentered /cedilla /onesuperior /ordmasculine /guillemotright /onequarter /onehalf
  33 +/threequarters /questiondown /Agrave /Aacute /Acircumflex /Atilde /Adieresis /Aring /AE /Ccedilla
  34 +/Egrave /Eacute /Ecircumflex /Edieresis /Igrave /Iacute /Icircumflex /Idieresis /Eth /Ntilde
  35 +/Ograve /Oacute /Ocircumflex /Otilde /Odieresis /multiply /Oslash /Ugrave /Uacute /Ucircumflex
  36 +/Udieresis /Yacute /Thorn /germandbls /agrave /aacute /acircumflex /atilde /adieresis /aring
  37 +/ae /ccedilla /egrave /eacute /ecircumflex /edieresis /igrave /iacute /icircumflex /idieresis
  38 +/eth /ntilde /ograve /oacute /ocircumflex /otilde /odieresis /divide /oslash /ugrave
  39 +/uacute /ucircumflex /udieresis /yacute /thorn /ydieresis] /isolatin1encoding exch def
  40 +/Times-Roman-latin1
  41 + /Times-Roman findfont
  42 + dup length dict begin
  43 + {1 index /FID ne {def} {pop pop} ifelse} forall
  44 + /Encoding isolatin1encoding def
  45 + currentdict end
  46 +definefont pop
  47 +/Times-Italic-latin1
  48 + /Times-Italic findfont
  49 + dup length dict begin
  50 + {1 index /FID ne {def} {pop pop} ifelse} forall
  51 + /Encoding isolatin1encoding def
  52 + currentdict end
  53 +definefont pop
  54 +/Times-Bold-latin1
  55 + /Times-Bold findfont
  56 + dup length dict begin
  57 + {1 index /FID ne {def} {pop pop} ifelse} forall
  58 + /Encoding isolatin1encoding def
  59 + currentdict end
  60 +definefont pop
  61 +/Times-BoldItalic-latin1
  62 + /Times-BoldItalic findfont
  63 + dup length dict begin
  64 + {1 index /FID ne {def} {pop pop} ifelse} forall
  65 + /Encoding isolatin1encoding def
  66 + currentdict end
  67 +definefont pop
  68 +/AvantGarde-Book-latin1
  69 + /AvantGarde-Book findfont
  70 + dup length dict begin
  71 + {1 index /FID ne {def} {pop pop} ifelse} forall
  72 + /Encoding isolatin1encoding def
  73 + currentdict end
  74 +definefont pop
  75 +/AvantGarde-BookOblique-latin1
  76 + /AvantGarde-BookOblique findfont
  77 + dup length dict begin
  78 + {1 index /FID ne {def} {pop pop} ifelse} forall
  79 + /Encoding isolatin1encoding def
  80 + currentdict end
  81 +definefont pop
  82 +/AvantGarde-Demi-latin1
  83 + /AvantGarde-Demi findfont
  84 + dup length dict begin
  85 + {1 index /FID ne {def} {pop pop} ifelse} forall
  86 + /Encoding isolatin1encoding def
  87 + currentdict end
  88 +definefont pop
  89 +/AvantGarde-DemiOblique-latin1
  90 + /AvantGarde-DemiOblique findfont
  91 + dup length dict begin
  92 + {1 index /FID ne {def} {pop pop} ifelse} forall
  93 + /Encoding isolatin1encoding def
  94 + currentdict end
  95 +definefont pop
  96 +/Bookman-Light-latin1
  97 + /Bookman-Light findfont
  98 + dup length dict begin
  99 + {1 index /FID ne {def} {pop pop} ifelse} forall
  100 + /Encoding isolatin1encoding def
  101 + currentdict end
  102 +definefont pop
  103 +/Bookman-LightItalic-latin1
  104 + /Bookman-LightItalic findfont
  105 + dup length dict begin
  106 + {1 index /FID ne {def} {pop pop} ifelse} forall
  107 + /Encoding isolatin1encoding def
  108 + currentdict end
  109 +definefont pop
  110 +/Bookman-Demi-latin1
  111 + /Bookman-Demi findfont
  112 + dup length dict begin
  113 + {1 index /FID ne {def} {pop pop} ifelse} forall
  114 + /Encoding isolatin1encoding def
  115 + currentdict end
  116 +definefont pop
  117 +/Bookman-DemiItalic-latin1
  118 + /Bookman-DemiItalic findfont
  119 + dup length dict begin
  120 + {1 index /FID ne {def} {pop pop} ifelse} forall
  121 + /Encoding isolatin1encoding def
  122 + currentdict end
  123 +definefont pop
  124 +/Courier-latin1
  125 + /Courier findfont
  126 + dup length dict begin
  127 + {1 index /FID ne {def} {pop pop} ifelse} forall
  128 + /Encoding isolatin1encoding def
  129 + currentdict end
  130 +definefont pop
  131 +/Courier-Oblique-latin1
  132 + /Courier-Oblique findfont
  133 + dup length dict begin
  134 + {1 index /FID ne {def} {pop pop} ifelse} forall
  135 + /Encoding isolatin1encoding def
  136 + currentdict end
  137 +definefont pop
  138 +/Courier-Bold-latin1
  139 + /Courier-Bold findfont
  140 + dup length dict begin
  141 + {1 index /FID ne {def} {pop pop} ifelse} forall
  142 + /Encoding isolatin1encoding def
  143 + currentdict end
  144 +definefont pop
  145 +/Courier-BoldOblique-latin1
  146 + /Courier-BoldOblique findfont
  147 + dup length dict begin
  148 + {1 index /FID ne {def} {pop pop} ifelse} forall
  149 + /Encoding isolatin1encoding def
  150 + currentdict end
  151 +definefont pop
  152 +/Helvetica-latin1
  153 + /Helvetica findfont
  154 + dup length dict begin
  155 + {1 index /FID ne {def} {pop pop} ifelse} forall
  156 + /Encoding isolatin1encoding def
  157 + currentdict end
  158 +definefont pop
  159 +/Helvetica-Oblique-latin1
  160 + /Helvetica-Oblique findfont
  161 + dup length dict begin
  162 + {1 index /FID ne {def} {pop pop} ifelse} forall
  163 + /Encoding isolatin1encoding def
  164 + currentdict end
  165 +definefont pop
  166 +/Helvetica-Bold-latin1
  167 + /Helvetica-Bold findfont
  168 + dup length dict begin
  169 + {1 index /FID ne {def} {pop pop} ifelse} forall
  170 + /Encoding isolatin1encoding def
  171 + currentdict end
  172 +definefont pop
  173 +/Helvetica-BoldOblique-latin1
  174 + /Helvetica-BoldOblique findfont
  175 + dup length dict begin
  176 + {1 index /FID ne {def} {pop pop} ifelse} forall
  177 + /Encoding isolatin1encoding def
  178 + currentdict end
  179 +definefont pop
  180 +/Helvetica-Narrow-latin1
  181 + /Helvetica-Narrow findfont
  182 + dup length dict begin
  183 + {1 index /FID ne {def} {pop pop} ifelse} forall
  184 + /Encoding isolatin1encoding def
  185 + currentdict end
  186 +definefont pop
  187 +/Helvetica-Narrow-Oblique-latin1
  188 + /Helvetica-Narrow-Oblique findfont
  189 + dup length dict begin
  190 + {1 index /FID ne {def} {pop pop} ifelse} forall
  191 + /Encoding isolatin1encoding def
  192 + currentdict end
  193 +definefont pop
  194 +/Helvetica-Narrow-Bold-latin1
  195 + /Helvetica-Narrow-Bold findfont
  196 + dup length dict begin
  197 + {1 index /FID ne {def} {pop pop} ifelse} forall
  198 + /Encoding isolatin1encoding def
  199 + currentdict end
  200 +definefont pop
  201 +/Helvetica-Narrow-BoldOblique-latin1
  202 + /Helvetica-Narrow-BoldOblique findfont
  203 + dup length dict begin
  204 + {1 index /FID ne {def} {pop pop} ifelse} forall
  205 + /Encoding isolatin1encoding def
  206 + currentdict end
  207 +definefont pop
  208 +/NewCenturySchoolbook-Roman-latin1
  209 + /NewCenturySchoolbook-Roman findfont
  210 + dup length dict begin
  211 + {1 index /FID ne {def} {pop pop} ifelse} forall
  212 + /Encoding isolatin1encoding def
  213 + currentdict end
  214 +definefont pop
  215 +/NewCenturySchoolbook-Italic-latin1
  216 + /NewCenturySchoolbook-Italic findfont
  217 + dup length dict begin
  218 + {1 index /FID ne {def} {pop pop} ifelse} forall
  219 + /Encoding isolatin1encoding def
  220 + currentdict end
  221 +definefont pop
  222 +/NewCenturySchoolbook-Bold-latin1
  223 + /NewCenturySchoolbook-Bold findfont
  224 + dup length dict begin
  225 + {1 index /FID ne {def} {pop pop} ifelse} forall
  226 + /Encoding isolatin1encoding def
  227 + currentdict end
  228 +definefont pop
  229 +/NewCenturySchoolbook-BoldItalic-latin1
  230 + /NewCenturySchoolbook-BoldItalic findfont
  231 + dup length dict begin
  232 + {1 index /FID ne {def} {pop pop} ifelse} forall
  233 + /Encoding isolatin1encoding def
  234 + currentdict end
  235 +definefont pop
  236 +/Palatino-Roman-latin1
  237 + /Palatino-Roman findfont
  238 + dup length dict begin
  239 + {1 index /FID ne {def} {pop pop} ifelse} forall
  240 + /Encoding isolatin1encoding def
  241 + currentdict end
  242 +definefont pop
  243 +/Palatino-Italic-latin1
  244 + /Palatino-Italic findfont
  245 + dup length dict begin
  246 + {1 index /FID ne {def} {pop pop} ifelse} forall
  247 + /Encoding isolatin1encoding def
  248 + currentdict end
  249 +definefont pop
  250 +/Palatino-Bold-latin1
  251 + /Palatino-Bold findfont
  252 + dup length dict begin
  253 + {1 index /FID ne {def} {pop pop} ifelse} forall
  254 + /Encoding isolatin1encoding def
  255 + currentdict end
  256 +definefont pop
  257 +/Palatino-BoldItalic-latin1
  258 + /Palatino-BoldItalic findfont
  259 + dup length dict begin
  260 + {1 index /FID ne {def} {pop pop} ifelse} forall
  261 + /Encoding isolatin1encoding def
  262 + currentdict end
  263 +definefont pop
  264 +/Symbol-latin1
  265 + /Symbol findfont
  266 +definefont pop
  267 +/ZapfChancery-MediumItalic-latin1
  268 + /ZapfChancery-MediumItalic findfont
  269 + dup length dict begin
  270 + {1 index /FID ne {def} {pop pop} ifelse} forall
  271 + /Encoding isolatin1encoding def
  272 + currentdict end
  273 +definefont pop
  274 +/ZapfDingbats-latin1
  275 + /ZapfDingbats findfont
  276 + dup length dict begin
  277 + {1 index /FID ne {def} {pop pop} ifelse} forall
  278 + /Encoding isolatin1encoding def
  279 + currentdict end
  280 +definefont pop
  281 +/cp {closepath} bind def
  282 +/c {curveto} bind def
  283 +/f {fill} bind def
  284 +/a {arc} bind def
  285 +/ef {eofill} bind def
  286 +/ex {exch} bind def
  287 +/gr {grestore} bind def
  288 +/gs {gsave} bind def
  289 +/sa {save} bind def
  290 +/rs {restore} bind def
  291 +/l {lineto} bind def
  292 +/m {moveto} bind def
  293 +/rm {rmoveto} bind def
  294 +/n {newpath} bind def
  295 +/s {stroke} bind def
  296 +/sh {show} bind def
  297 +/slc {setlinecap} bind def
  298 +/slj {setlinejoin} bind def
  299 +/slw {setlinewidth} bind def
  300 +/srgb {setrgbcolor} bind def
  301 +/rot {rotate} bind def
  302 +/sc {scale} bind def
  303 +/sd {setdash} bind def
  304 +/ff {findfont} bind def
  305 +/sf {setfont} bind def
  306 +/scf {scalefont} bind def
  307 +/sw {stringwidth pop} bind def
  308 +/tr {translate} bind def
  309 +
  310 +/ellipsedict 8 dict def
  311 +ellipsedict /mtrx matrix put
  312 +/ellipse
  313 +{ ellipsedict begin
  314 + /endangle exch def
  315 + /startangle exch def
  316 + /yrad exch def
  317 + /xrad exch def
  318 + /y exch def
  319 + /x exch def /savematrix mtrx currentmatrix def
  320 + x y tr xrad yrad sc
  321 + 0 0 1 startangle endangle arc
  322 + savematrix setmatrix
  323 + end
  324 +} def
  325 +
  326 +/mergeprocs {
  327 +dup length
  328 +3 -1 roll
  329 +dup
  330 +length
  331 +dup
  332 +5 1 roll
  333 +3 -1 roll
  334 +add
  335 +array cvx
  336 +dup
  337 +3 -1 roll
  338 +0 exch
  339 +putinterval
  340 +dup
  341 +4 2 roll
  342 +putinterval
  343 +} bind def
  344 +28.346000 -28.346000 scale
  345 +-3.700000 -19.050000 translate
  346 +%%EndProlog
  347 +
  348 +
  349 +1.000000 1.000000 1.000000 srgb
  350 +n 3.800000 1.200000 m 3.800000 19.000000 l 20.500000 19.000000 l 20.500000 1.200000 l f
  351 +0.100000 slw
  352 +[] 0 sd
  353 +[] 0 sd
  354 +0 slj
  355 +0.000000 0.000000 0.000000 srgb
  356 +n 3.800000 1.200000 m 3.800000 19.000000 l 20.500000 19.000000 l 20.500000 1.200000 l cp s
  357 +0.100000 slw
  358 +[] 0 sd
  359 +[] 0 sd
  360 +0 slc
  361 +n 3.750000 4.200000 m 20.300000 4.200000 l s
  362 +0.100000 slw
  363 +[] 0 sd
  364 +[] 0 sd
  365 +0 slc
  366 +n 3.850000 7.450000 m 20.450000 7.500000 l s
  367 +0.100000 slw
  368 +[] 0 sd
  369 +[] 0 sd
  370 +0 slc
  371 +n 3.850000 10.850000 m 20.450000 10.800000 l s
  372 +0.100000 slw
  373 +[] 0 sd
  374 +[] 0 sd
  375 +0 slc
  376 +n 3.850000 14.800000 m 20.350000 14.800000 l s
  377 +/Courier-Bold-latin1 ff 0.800000 scf sf
  378 +(100 bytes of HTML code) dup sw 2 div 11.100000 ex sub 2.800000 m gs 1 -1 sc sh gr
  379 +/Courier-Bold-latin1 ff 0.800000 scf sf
  380 +(120 bytes of Erlang code) dup sw 2 div 11.300000 ex sub 5.850000 m gs 1 -1 sc sh gr
  381 +/Courier-Bold-latin1 ff 0.800000 scf sf
  382 +(80 bytes of HTML code) dup sw 2 div 10.900000 ex sub 9.350000 m gs 1 -1 sc sh gr
  383 +/Courier-Bold-latin1 ff 0.800000 scf sf
  384 +(60 bytes of Erlang code) dup sw 2 div 11.150000 ex sub 13.000000 m gs 1 -1 sc sh gr
  385 +/Courier-Bold-latin1 ff 0.800000 scf sf
  386 +(140 bytes of HTML code) dup sw 2 div 10.950000 ex sub 16.950000 m gs 1 -1 sc sh gr
  387 +showpage
1,536 doc/yaws.tex
@@ -8,6 +8,15 @@
8 8 \setlength\parskip{\medskipamount}
9 9 \setlength\parindent{0pt}
10 10 \usepackage{url}
  11 +\usepackage[dvips]{graphicx}
  12 +
  13 +\newcommand{\Erlang} % Write Erlang correctly
  14 + {{\sc Erlang}}
  15 +
  16 +
  17 +\newcommand{\Yaws} % Write Erlang correctly
  18 + {{\sc Yaws}}
  19 +
11 20
12 21 \makeatletter
13 22
@@ -26,37 +35,50 @@
26 35 \author{Claes Wikstrom\\
27 36 klacke@hyber.org}
28 37
  38 +
  39 +
  40 +
  41 +
29 42 \maketitle
30 43 \tableofcontents{}
31 44
32 45
  46 +
33 47 \chapter{Introduction}
34 48
35 49
36   -Yaws is an Erlang web server. It's written entirely in Erlang and it uses
37   -Erlang as its embedded language similar to PHP in Apache or Java in Tomcat.
  50 +\begin{figure}[h]
  51 +\begin{center}
  52 +
  53 + \includegraphics[scale=0.6] {yaws_head.eps}
  54 +
  55 +\end{center}
  56 +\end{figure}
38 57
39   -The advantages of Erlang as an embedded webpage language as opposed to
  58 +\Yaws\ is an \Erlang\ web server. It's written in \Erlang\ and it uses
  59 +\Erlang\ as its embedded language similar to PHP in Apache or Java in Tomcat.
  60 +
  61 +The advantages of \Erlang\ as an embedded web page language as opposed to
40 62 Java or PHP are many.
41 63 \begin{itemize}
42 64
43   -\item{Speed - Using Erlang for both implementing the webserver itself as well
  65 +\item{Speed - Using \Erlang\ for both implementing the web server itself as well
44 66 as embedded script language gives excellent dynamic page generation
45 67 performance.}
46 68
47 69 \item{Beauty - Well this is subjective}
48 70
49   -\item{Scalability - due to the light weight processes of Erlang, Yaws
  71 +\item{Scalability - due to the light weight processes of \Erlang\ , \Yaws\
50 72 is able to handle a very large number of concurrent connections}
51 73
52 74 \end{itemize}
53 75
54   -Yaws has a wide feature set, it supports:
  76 +\Yaws\ has a wide feature set, it supports:
55 77
56 78 \begin{enumerate}
57 79 \item HTTP 1.0 and HTTP 1.1
58 80 \item Static content page delivery
59   -\item Dynamic content generation using embedded erlang code in the
  81 +\item Dynamic content generation using embedded \Erlang\ code in the
60 82 HTML pages
61 83 \item Common Log Format traffic logs
62 84 \item Virtual hosting with several servers on the same IP address
@@ -69,6 +91,7 @@ \chapter{Introduction}
69 91 generated pages.
70 92 \item SSL
71 93 \item Support for WWW-Authenticated pages.
  94 +\item Support API for cookie based sessions.
72 95 \item Application Modules where virtual directory hierarchies can
73 96 be made.
74 97 \item Embedded mode
@@ -77,22 +100,22 @@ \chapter{Introduction}
77 100 \section{Prerequisites}
78 101 This document requires that the reader:
79 102 \begin{itemize}
80   -\item Is well acquainted with the Erlang programming language
  103 +\item Is well acquainted with the \Erlang\ programming language
81 104 \item Understands basic Web technologies.
82 105 \end{itemize}
83 106
84 107
85 108 \section{A tiny example}
86 109
87   -We introduce yaws by help of a tiny example.
88   - The webserver yaws serves and delivers
89   -static content pages similar to any old webserver, except that Yaws does this
  110 +We introduce \Yaws\ by help of a tiny example.
  111 + The web server \Yaws\ serves and delivers
  112 +static content pages similar to any old web server, except that \Yaws\ does this
90 113 much faster than most web servers. It's the dynamic pages
91   -that makes yaws interesting. Any page with the suffix ``.yaws'' is considered
92   -a dynamic yaws page. A yaws page can contain embedded Erlang snippets that
  114 +that makes \Yaws\ interesting. Any page with the suffix ``.yaws'' is considered
  115 +a dynamic \Yaws\ page. A \Yaws\ page can contain embedded \Erlang\ snippets that
93 116 are executed while the page is being delivered to the WWW browser.
94 117
95   -Example 1.1 is the HTML code for a small yaws page.
  118 +Example 1.1 is the HTML code for a small \Yaws\ page.
96 119
97 120
98 121 \begin{figure}[h]
@@ -103,7 +126,7 @@ \section{A tiny example}
103 126
104 127 <erl>
105 128 out(Arg) ->
106   - {html, "<p>This string get's inserted into HTML document dynamically"}.
  129 + {html, "<p>This string gets inserted into HTML document dynamically"}.
107 130 </erl>
108 131
109 132 <p> And here is some more HTML code
@@ -113,32 +136,32 @@ \section{A tiny example}
113 136 \caption{Example 1.1}
114 137 \end{figure}
115 138
116   -It illustrates the basic idea behing yaws. The HTML code
117   -can contain <erl> and </erl> tags and inside these tags an erlang function
  139 +It illustrates the basic idea behind \Yaws\ . The HTML code
  140 +can contain <erl> and </erl> tags and inside these tags an \Erlang\ function
118 141 called out/1 gets called and the output of that function is inserted
119 142 into the HTML document, dynamically.
120 143
121 144 It is possible to have several chunks of HTML code together with several
122   -chunks of Erlang code in the same yaws page.
  145 +chunks of \Erlang\ code in the same \Yaws\ page.
123 146
124 147 The \verb+Arg+ argument supplied to the automatically invoked \verb+out/1+
125   -function is an Erlang record that contains various data which is interesting
  148 +function is an \Erlang\ record that contains various data which is interesting
126 149 when generating dynamic pages. For example the HTTP headers which were sent
127 150 from the WWW client, the actual TCP/IP socket leading to the WWW client.
128 151 This will be elaborated on throughly in later chapters.
129 152
130 153 The \verb+out/1+ function returned the tuple \verb+{html, String}+ and
131   -\verb+String+ would be inserted into the HTML output. There are number
  154 +\verb+String+ gets inserted into the HTML output. There are number
132 155 of different return values that can be returned from the \verb+out/1+ function
133   -in order to control the behaviour and output from the Yaws web server.
  156 +in order to control the behavior and output from the \Yaws\ web server.
134 157
135 158
136 159
137 160 \chapter{Compile, Install, Config and Run}
138 161
139   -This chapter is more of a ``Getting started'' character than a full
140   -description of the Yaws configuration.
141   -Yaws is hosted on Sourceforge at
  162 +This chapter is more of a ``Getting started'' guide than a full
  163 +description of the \Yaws\ configuration.
  164 +\Yaws\ is hosted on Sourceforge at
142 165 \textit { http://sourceforge.net/projects/erlyaws/ }. This is where the source code
143 166 resides in a CVS repository and the latest unreleased version is
144 167 available through anonymous CVS through the following commands:
@@ -153,16 +176,16 @@ \chapter{Compile, Install, Config and Run}
153 176 \end{verbatim}
154 177
155 178
156   -Released version of Yaws are available either at the Soureforge site or
  179 +Released version of \Yaws\ are available either at the Sourceforge site or
157 180 at \textit{http://yaws.hyber.org/download}.
158 181
159 182
160 183
161 184 \subsection{Compile and Install}
162 185
163   -To compile and install a Yaws release
164   -one of the prerequisites is a properly installed Erlang system. Yaws
165   -runs on Erlang releases OTP R8 and later. Get Erlang from
  186 +To compile and install a \Yaws\ release
  187 +one of the prerequisites is a properly installed \Erlang\ system. \Yaws\
  188 +runs on \Erlang\ releases OTP R8 and later. Get \Erlang\ from
166 189 \textit{http://www.erlang.org}
167 190
168 191 Compile and install is straight forward:
@@ -177,21 +200,21 @@ \subsection{Compile and Install}
177 200 There is no configure script (yet) since there are no items
178 201 to configure.
179 202
180   -The make command will compile the Yaws web server with the \verb+erlc+
  203 +The make command will compile the \Yaws\ web server with the \verb+erlc+
181 204 compiler found in \$PATH.
182 205
183   -make install - will install the executable - called yaws in
  206 +make install - will install the executable - called \verb+yaws+ in
184 207 /usr/local/bin/ and a working configuration file in \textit{ /etc/yaws.conf}
185 208
186 209 make local\_install will install the executable in \$HOME/bin and a
187 210 working configuration file in \$HOME/yaws.conf
188 211
189   -While developing a Yaws site, it's typically most convenient to
190   -use the local\_install and run Yaws as a non priviliged user.
  212 +While developing a \Yaws\ site, it's typically most convenient to
  213 +use the local\_install and run \Yaws\ as a non privileged user.
191 214
192 215
193 216 \subsection{Configure}
194   -Let's take a look at the config file that get's written to \$HOME after
  217 +Let's take a look at the config file that gets written to \$HOME after
195 218 a local\_install.
196 219
197 220
@@ -204,12 +227,12 @@ \subsection{Configure}
204 227 ebin_dir = /home/klacke/yaws/yaws/examples/ebin
205 228 include_dir = /home/klacke/yaws/yaws/examples/include
206 229
207   -#end then a set of servers
  230 +# and then a set of servers
208 231
209 232 <server localhost>
210   - port = 8000
211   - listen = 127.0.0.1
212   - docroot = /home/klacke/yaws/yaws/scripts/../www
  233 + port = 8000
  234 + listen = 127.0.0.1
  235 + docroot = /home/klacke/yaws/yaws/scripts/../www
213 236 </server>
214 237
215 238
@@ -218,13 +241,13 @@ \subsection{Configure}
218 241 \end{figure}
219 242
220 243 The configuration consists of an initial set of global
221   -variables that are valid for all servers defined.
  244 +variables that are valid for all defined servers.
222 245
223   -The only one we need to care about for now is the logdir
224   -directive. Yaws will produce a number of logfiles and they will -
  246 +The only global directive we need to care about for now is the logdir.
  247 +\Yaws\ produces a number of log files and they will -
225 248 using the Configuration from Figure 2.1 - end up in the current
226 249 working directory.
227   -We start yaws interactively as
  250 +We start \Yaws\ interactively as
228 251 \begin{verbatim}
229 252 # ~/bin/yaws -i
230 253 Erlang (BEAM) emulator version 5.1.2.b2 [source]
@@ -236,26 +259,27 @@ \subsection{Configure}
236 259 =INFO REPORT==== 30-Oct-2002::01:38:22 ===
237 260 Listening to 127.0.0.1:8000 for servers ["localhost:8000"]
238 261
239   -1>
  262 +1>
240 263 \end{verbatim}
241 264
242   -By starting yaws in interactive mode (using the command switch \textit{-i}
243   -we get a regular erlang prompt. This is most convenient when developing
244   -web pages. For example we can/get:
  265 +By starting \Yaws\ in interactive mode (using the command switch \textit{-i}
  266 +we get a regular \Erlang\ prompt. This is most convenient when developing
  267 +\Yaws\ /http pages. For example we:
245 268 \begin{itemize}
246   -\item{Dynamically compile and load optional helper modules we need.}
247   -\item{We Get all the crash and error reports written directly to the
  269 +\item{Can dynamically compile and load optional helper modules we need.}
  270 +\item{Get all the crash and error reports written directly to the
248 271 terminal.}
249 272 \end{itemize}
250 273
251   -The configuration in picture 2.1 defined one HTTP server on
  274 +The configuration in Example 2.1 defined one HTTP server on
252 275 address 127.0.0.1:8000 called "localhost".
253 276 It is important to understand the difference between the name and
254 277 the address of a server. The name is the expected value in the
255 278 client Host: header. That is typically the same as the fully qualified
256   -DNS name of the server whereas the address is IP address of the server.
  279 +DNS name of the server whereas the address is the actual
  280 +IP address of the server.
257 281
258   -Since Yaws support virtual hosting with several servers on the same
  282 +Since \Yaws\ support virtual hosting with several servers on the same
259 283 IP address, this matters.
260 284
261 285 Nevertheless, our server listens to \textit{127.0.0.1:8000} and
@@ -263,11 +287,11 @@ \subsection{Configure}
263 287 is \textit{http://localhost:8000}.
264 288
265 289 The document root (docroot) for the server is set to the www directory in the
266   -Yaws source code distribution. This directory contains a bunch of
  290 +\Yaws\ source code distribution. This directory contains a bunch of
267 291 examples and we should be able to run all those example now on the
268 292 URL \textit{http://localhost:8000}.
269 293
270   -Instead of editing and adding files in the yaws www directory, we
  294 +Instead of editing and adding files in the \Yaws\ www directory, we
271 295 create yet another server on the same IP address but a different port
272 296 number - and in particular a different document root where we can add
273 297 our own files.
@@ -286,15 +310,15 @@ \subsection{Configure}
286 310 include_dir = /home/klacke/test
287 311
288 312 <server localhost>
289   - port = 8000
290   - listen = 127.0.0.1
291   - docroot = /home/klacke/yaws/yaws/www
  313 + port = 8000
  314 + listen = 127.0.0.1
  315 + docroot = /home/klacke/yaws/yaws/www
292 316 </server>
293 317
294 318 <server localhost>
295   - port = 8001
296   - listen = 127.0.0.1
297   - docroot = /home/klacke/test
  319 + port = 8001
  320 + listen = 127.0.0.1
  321 + docroot = /home/klacke/test
298 322 </server>
299 323
300 324
@@ -305,18 +329,18 @@ \subsection{Configure}
305 329
306 330 We can now start to add static content in the form of
307 331 HTML pages, dynamic content in the form of .yaws pages or
308   -erlang/beam code that can be used to generate the dynamic content.
  332 +\Erlang\ .beam code that can be used to generate the dynamic content.
309 333
310   -The load path will be set so that beam code in the directory ~/test
  334 +The load path will be set so that beam code in the directory \verb+~/test+
311 335 will be automatically loaded when referenced.
312 336
313   -It is best to run yaws interactively while developing the site.
314   -In order to start the yaws as a daemon, we give the flags:
  337 +It is best to run \Yaws\ interactively while developing the site.
  338 +In order to start the \Yaws\ as a daemon, we give the flags:
315 339 \begin{verbatim}
316 340 # yaws -D -heart
317 341 \end{verbatim}
318 342
319   -The \textit{-D} flags instructs yaws to run as a daemon and the
  343 +The \textit{-D} flags instructs \Yaws\ to run as a daemon and the
320 344 \textit{-heart} flags will start a heartbeat program called heart
321 345 which restarts the daemon if it should crash or if it stops responding to
322 346 a regular heartbeat.
@@ -342,17 +366,17 @@ \subsection{Configure}
342 366
343 367 \chapter{Static content}
344 368
345   -Yaws acts very much like any regular web server while delivering
346   -static pages. By default yaws will cache static content in RAM.
347   -The caching behaviour is controlled by a number of global
  369 +\Yaws\ acts very much like any regular web server while delivering
  370 +static pages. By default \Yaws\ will cache static content in RAM.
  371 +The caching behavior is controlled by a number of global
348 372 configuration directives. Since the RAM caching occupies memory,
349 373 it may be interesting to tweak the default values for the caching directives
350   -or even to turn it off completeley.
  374 +or even to turn it off completely.
351 375
352 376 The following configuration directives control the caching behavior
353 377 \begin{itemize}
354 378 \item \textit{max\_num\_cached\_files = Integer}
355   -Yaws will cache small files such as commonly
  379 +\Yaws\ will cache small files such as commonly
356 380 accessed GIF images in RAM. This directive sets a
357 381 maximum number on the number of cached files. The
358 382 default value is 400.
@@ -366,7 +390,7 @@ \chapter{Static content}
366 390 \item\textit{max\_size\_cached\_file = Integer}
367 391
368 392 This directive sets a maximum size on the files
369   - that are RAM cached by yaws. The default value i
  393 + that are RAM cached by \Yaws\ . The default value i
370 394 8000, 8 batters.
371 395
372 396
@@ -383,8 +407,8 @@ \chapter{Static content}
383 407
384 408 \chapter{Dynamic content}
385 409
386   -Dynamic content is what yaws is about. Most web servers are designed
387   -with HTTP and static content in mind whereas Yaws is designed
  410 +Dynamic content is what \Yaws\ is about. Most web servers are designed
  411 +with HTTP and static content in mind whereas \Yaws\ is designed
388 412 for dynamic pages from the start.
389 413 Most large sites on the Web today make heavy use of dynamic pages.
390 414
@@ -392,21 +416,21 @@ \chapter{Dynamic content}
392 416
393 417 \section{Introduction}
394 418
395   -When the client GETs a a page that has a .yaws suffix. The yaws server
  419 +When the client GETs a a page that has a .yaws suffix. The \Yaws\ server
396 420 will read that page from the hard disk and divide it in parts
397   -that consist of HTML code and Erlang code. Each chunk of erlang code
398   -will be compiled into a module. The chunk of Erlang code must contain
399   -a function \verb+out/1+. If it doesn't the yaws server will insert a
  421 +that consist of HTML code and \Erlang\ code. Each chunk of \Erlang\ code
  422 +will be compiled into a module. The chunk of \Erlang\ code must contain
  423 +a function \verb+out/1+. If it doesn't the \Yaws\ server will insert a
400 424 proper error message into the generated HTML output.
401 425
402   -When the Yaws server ships a .yaws page it will ship chunk by chunk
  426 +When the \Yaws\ server ships a .yaws page it will process it chunk by chunk
403 427 through the .yaws file. If it is HTML code, the server will ship that
404   -as is whereas if it is Erlang code, the yaws server will invoke the
405   -\verb+out/1+ function in that code and insert the output into the stream
  428 +as is, whereas if it is \Erlang\ code, the \Yaws\ server will invoke the
  429 +\verb+out/1+ function in that code and insert the output of that \verb+out/1+ function into the stream
406 430 of HTML that is being shipped to the client.
407 431
408   -Yaws will (of cource) cache the result of the compilation
409   -and the next time a client requests the same .yaws page Yaws will
  432 +\Yaws\ will (of course) cache the result of the compilation
  433 +and the next time a client requests the same .yaws page \Yaws\ will
410 434 be able to invoke the already compiled modules directly.
411 435
412 436
@@ -440,15 +464,15 @@ \section{EHTML}
440 464 \verb+{ehtml, EHTML}+. The term \verb+EHTML+ must adhere to the
441 465 following structure:
442 466
443   -$EHTML = [EHTML] | \{HTMLTAG, Attrs, Body\} |
444   - \{HTMLTAG, Attrs\} | \{HTMLTAG\} |
  467 +$EHTML = [EHTML] | \{TAG, Attrs, Body\} |
  468 + \{TAG, Attrs\} | \{TAG\} |
445 469 binary() | character()$
446 470
447   -$HTMLTAG = atom()$
  471 +$TAG = atom()$
448 472
449 473 $Attrs = [\{HtmlAttribute, Value\}]$
450 474
451   -$HtmlAttribute = atom()$
  475 +$HtmlAttribute = atom()$
452 476
453 477 $Value = string() | atom()$
454 478
@@ -458,15 +482,15 @@ \section{EHTML}
458 482 The tuple
459 483 \begin{verbatim}
460 484 {ehtml, {table, [{bgcolor, grey}],
461   - [
462   - {tr, [],
463   - [
464   - {td, [], "1"},
465   - {td, [], "2"},
466   - {td, [], "3"}
467   - ],
468   - {tr, [],
469   - [{td, [{colspan, "3"}], "444"}]}}]}}.
  485 + [
  486 + {tr, [],
  487 + [
  488 + {td, [], "1"},
  489 + {td, [], "2"},
  490 + {td, [], "3"}
  491 + ],
  492 + {tr, [],
  493 + [{td, [{colspan, "3"}], "444"}]}}]}}.
470 494 \end{verbatim}
471 495
472 496 Would be expanded into the following HTML code
@@ -485,15 +509,16 @@ \section{EHTML}
485 509 \end{verbatim}
486 510
487 511 At a first glance it may appears as if the HTML code is more
488   -beautiful than the Erlang tuple. That may very well be the
  512 +beautiful than the \Erlang\ tuple. That may very well be the
489 513 case from a purely aesthetic point of view. However the
490   -Erlang code has the advantage of being perfectly indented by editors
491   -that have syntax support for Erlang (read Emacs). Furthermore, the erlang
492   -code is easier to manipulate from an Erlang program.
  514 +\Erlang\ code has the advantage of being perfectly indented by editors
  515 +that have syntax support for \Erlang\ (read Emacs). Furthermore, the \Erlang\
  516 +code is easier to manipulate from an \Erlang\ program.
493 517
494 518 As an example of some more interesting ehtml we could have
495   -an \verb+out/1+ function that prints some of the HTTP headers
496   -In the www directory of the Yaws source code distribution we have
  519 +an \verb+out/1+ function that prints some of the HTTP headers.
  520 +
  521 +In the www directory of the \Yaws\ source code distribution we have
497 522 a file called \verb+arg.yaws+. The file demonstrates the Arg \#arg record
498 523 parameter which is passed to the \verb+out/1+ function.
499 524
@@ -502,7 +527,7 @@ \section{EHTML}
502 527 in detail.
503 528
504 529 Here is the \verb+yaws_api.hrl+ file which is in included by default
505   -in all yaws files. The \#arg{} record contains many fields that are
  530 +in all \Yaws\ files. The \#arg{} record contains many fields that are
506 531 useful when processing HTTP request dynamically.
507 532 We have access to basically all the information which associated to the
508 533 client request such as:
@@ -513,7 +538,7 @@ \section{EHTML}
513 538 \item The HTTP request - parsed into a \#http\_request record
514 539 \item clidata - Data which is POSTed by the client
515 540 \item querydata - This is the remainder of the URL following the first
516   -occurance of a ? character - if any.
  541 +occurrence of a ? character - if any.
517 542 \item docroot - The absolute path to the docroot of the virtual server
518 543 that is processing the request.
519 544 \end{itemize}
@@ -523,31 +548,20 @@ \section{EHTML}
523 548 \begin{verbatim}
524 549
525 550
526   -
527   -%%%----------------------------------------------------------------------
528   -%%% File : yaws_api.hrl
529   -%%% Author : Claes Wikstrom <klacke@hyber.org>
530   -%%% Purpose :
531   -%%% Created : 24 Jan 2002 by Claes Wikstrom <klacke@hyber.org>
532   -%%%----------------------------------------------------------------------
533   -
534   --author('klacke@hyber.org').
535   -
536   -
537 551 -record(arg, {
538   - clisock, %% the socket leading to the peer client
539   - headers, %% headers
540   - req, %% request
541   - clidata, %% The client data (as a binary in POST requests)
542   - querydata, %% Was the URL on the form of ...?query (GET reqs)
543   - appmoddata, %% the remainder of the path leading up to the querey
544   - docroot, %% where's the data
545   - fullpath, %% full path to yaws file
546   - cont, %% Continuation for chunked multipart uploads
547   - state, %% State for use by users of the out/1 callback
548   - pid, %% pid of the yaws worker process
549   - opaque %% useful to pass static data
550   - }).
  552 + clisock, %% the socket leading to the peer client
  553 + headers, %% headers
  554 + req, %% request
  555 + clidata, %% The client data (as a binary in POST requests)
  556 + querydata, %% Was the URL on the form of ...?query (GET reqs)
  557 + appmoddata, %% the remainder of the path leading up to the query
  558 + docroot, %% where's the data
  559 + fullpath, %% full path to yaws file
  560 + cont, %% Continuation for chunked multipart uploads
  561 + state, %% State for use by users of the out/1 callback
  562 + pid, %% pid of the yaws worker process
  563 + opaque %% useful to pass static data
  564 + }).
551 565
552 566
553 567 -record(http_request, {method,
@@ -583,7 +597,7 @@ \section{EHTML}
583 597 such as \verb+appmod+, \verb+opaque+ that will be discussed in later chapters.
584 598
585 599 Now, we show some code which displays the content of the Arg \#arg record.
586   -The code is avaiable in yaws/www/arg.yaws and after a a \verb+local_install+
  600 +The code is available in yaws/www/arg.yaws and after a a \verb+local_install+
587 601 a request to \textit{http://localhost:8000/arg.yaws} will run the code.
588 602
589 603 \begin{verbatim}
@@ -601,7 +615,6 @@ \section{EHTML}
601 615 out(A) ->
602 616 Req = A#arg.req,
603 617 H = yaws_api:reformat_header(A#arg.headers),
604   - io:format("H: ~p~n",[H]),
605 618 {ehtml,
606 619 [{h4,[], "The headers passed to us were:"},
607 620 {hr},
@@ -635,13 +648,13 @@ \section{EHTML}
635 648
636 649 The code utilizes 4 functions from the \verb+yaws_api+ module.
637 650 \verb+yaws_api+ is a general purpose www api module that contains various
638   -functions that are handy while developing yaws code. We will see many
  651 +functions that are handy while developing \Yaws\ code. We will see many
639 652 more of those functions during the examples in the following chapters.
640 653
641 654 The functions used are:
642 655 \begin{itemize}
643 656 \item \verb+yaws_api:f/2+ alias for io\_lib:format/2. The \verb+f/1+ function
644   -is automatically \verb+-include+ed in all Yaws code.
  657 +is automatically \verb+-includeed+ in all \Yaws\ code.
645 658 \item \verb+yaws_api:reformat_header/1+ - This function takes the \#headers record
646 659 and unparses it, that is reproduces regular text.
647 660 \item \verb+yaws_api:parse_query/1+ - The topic of next section.
@@ -653,14 +666,14 @@ \section{POSTs}
653 666
654 667 \subsection{Queries}
655 668
656   -The user can suppy data to the server in many ways. The most
  669 +The user can supply data to the server in many ways. The most
657 670 common is to give the data in the actual URL.
658 671 If we invoke:
659 672
660   -verb+GET http://localhost:8000/arg.yaws?kalle=duck\&goofy=unknown+
  673 +\verb+GET http://localhost:8000/arg.yaws?kalle=duck&goofy=unknown+
661 674
662 675 we pass two parameters to the \textit{arg.yaws} page.
663   -That data is url-encoded by the browser and the server can retrieve the
  676 +That data is URL-encoded by the browser and the server can retrieve the
664 677 data by looking at the remainder of the URL following the ? character.
665 678 If we invoke the \verb+arg.yaws+ page with the above mentioned URL we get
666 679 as the result of \verb+yaws_parse_query/1+:
@@ -669,7 +682,7 @@ \subsection{Queries}
669 682
670 683 $goofy = unknown$
671 684
672   -In Erlang terminology, the call \verb+yaws_api:parse_query(Arg)+ returns
  685 +In \Erlang\ terminology, the call \verb+yaws_api:parse_query(Arg)+ returns
673 686 the list:
674 687 \begin{verbatim}
675 688 [{kalle, "duck"}, {goofy, "unknown"}]
@@ -678,8 +691,8 @@ \subsection{Queries}
678 691 Note that the first element is transformed into an atom, whereas the value
679 692 is still a string.
680 693
681   -hence, a webpage can contain URLs with a query and thus pass data to the
682   -webserver. This scheme works both with GET and POST requests.
  694 +hence, a web page can contain URLs with a query and thus pass data to the
  695 +web server. This scheme works both with GET and POST requests.
683 696 It is the easiest way to pass data to the Web server since no FORM is required
684 697 in the web page.
685 698
@@ -687,10 +700,117 @@ \subsection{Queries}
687 700 \subsection{Forms}
688 701
689 702 In order to POST data a FORM is required, say that we have a page called
690   -\verb+form.yaws+ That contain the following code:
  703 +\verb+form.yaws+ that contain the following code:
  704 +
  705 +\begin{verbatim}
  706 +<html>
  707 +<form action="/post_form.yaws"
  708 + method="post"
  709 +
  710 +<p> A Input field
  711 +<input name="xyz" type="text">
  712 +<input type="submit">
  713 +</form>
  714 +</html>
  715 +\end{verbatim}
  716 +
  717 +This will produce a page with a simple input field and a Submit button.
  718 +
  719 +
  720 +
  721 +\begin{figure}[h]
  722 +\begin{center}
  723 +
  724 + \includegraphics[scale=0.6] {a.eps}
  725 +
  726 +\end{center}
  727 +\end{figure}
  728 +
  729 +
  730 +
  731 +If we enter something - say ``Hello there `` -
  732 +in the input field and click the Submit button the
  733 +client will request the page indicated in the ``action'' attribute, namely
  734 +\verb+post_form.yaws+.
  735 +
  736 +
  737 +If that \Yaws\ page has the following code:
  738 +\begin{verbatim}
  739 +out(A) ->
  740 + L = yaws_api:parse_post(A),
  741 + {html, f("~p", [L])}
  742 +\end{verbatim}
  743 +
  744 +The user will see the output
  745 +\begin{verbatim}
  746 +[{xyz, "Hello there"}]
  747 +\end{verbatim}
  748 +
  749 +The differences between using the query part of the URL
  750 +and a form are the following:
  751 +\begin{itemize}
  752 +\item Using the query arg only works in GET request. We parse the
  753 +query argument with the function \verb+yaws_api:parse_query(Arg)+
  754 +
  755 +\item If we use a form and POST the user data the client will
  756 +transmit the user data in the body of the request.
  757 +That is - the client sends a request to get the page using the POST method
  758 +and it then attaches the user data - encoded - into the body of the
  759 +request.
  760 +
  761 +A POST request can have a query part in its URL as well as user data
  762 +in the body.
  763 +\end{itemize}
  764 +
  765 +
  766 +\section{POSTing files}
691 767
  768 +It is possible to upload files from the client to the server by
  769 +means of POST. We indicate this in the form by telling the browser that we
  770 +want a different encoding, here is a form that does this:
  771 +\begin{verbatim}
  772 +
  773 +out(A) ->
  774 + Form =
  775 + {form, [{enctype, "multipart/form-data"},
  776 + {method, post},
  777 + {action, "file_upload_form.yaws"}],
  778 + [{input, [{type, submit}, {value, "Upload"}]},
  779 + {input, [{type,file}, {width, "50"}, {name, foo}]}]},
  780 + {ehtml, {html,[], [{h2,[], "A simple file upload page"},
  781 + Form]}}.
  782 +
  783 +\end{verbatim}
  784 +
  785 +The page delivers the entire HTML page with enclosing \verb+html+ markers.
  786 +It looks like:
  787 +
  788 +
  789 +\begin{figure}[h]
  790 +\begin{center}
  791 +
  792 + \includegraphics[scale=0.6] {b.eps}
  793 +
  794 +\end{center}
  795 +\end{figure}
  796 +
  797 +The user get an option to browse the local host for a file
  798 +or the user can explicitly fill in the file name in the input
  799 +field. The file browsing part is automatically taken care of by the
  800 +browser.
  801 +
  802 +The action field in the form states that the client shall POST to a page called
  803 +\verb+file_upload_form.yaws+. This page will get the contents of the file
  804 +in the body of the POST message. Here we have one easy case and one hard
  805 +case. \Yaws\ will read the data from the client. However if the file is large
  806 +the entire contents of the file will not be part of the read operation.
  807 +It is not acceptable to let \Yaws\ continue to read the full POST body
  808 +and then when that is done, invoke the POST page. \Yaws\ must
  809 +feed the page with the chunks of the file as they arrive.
692 810
  811 +First the easy case:
693 812
  813 +Not YET Written ... ..... fill this in later .....
694 814
695 815
696 816
@@ -698,28 +818,1162 @@ \subsection{Forms}
698 818
699 819 \chapter{Mode of operation}
700 820
  821 +\section{On the fly compilation}
  822 +When the client requests a \Yaws\ page, \Yaws\ will look in its caches
  823 +(there is one cache per virtual server) to see if it finds the
  824 +requested page in the cache. If \Yaws\ doesn't find the page in the
  825 +cache, it will compile the page. This only happens the first time a
  826 +page is requested.
  827 +Say that the page is 400 bytes big has the following layout:
  828 +
  829 +
  830 +
  831 +\begin{figure}[h]
  832 +\begin{center}
  833 +
  834 + \includegraphics[scale=0.4] {layout.eps}
  835 +
  836 +\end{center}
  837 +\end{figure}
  838 +
  839 +The \Yaws\ server will then parse the file and produce a structure
  840 +which makes it possible to deliver the page in a readily fashion the
  841 +next time the same page is requested.
  842 +
  843 +When shipping the page it will
  844 +\begin{enumerate}
  845 +\item Ship the first 100 bytes from the file
  846 +\item Evaluate the first \Erlang\ chunk in the file and ship the output
  847 +from the \verb+out/1+ function in that chunk. It will also jump ahead
  848 +in the file and skip 120 bytes.
  849 +\item Ship 80 bytes of HTML code
  850 +\item Again evaluate an \Erlang\ chunk, this time the second and jump
  851 +ahead 60 bytes in the file.
  852 +\item And finally ship 140 bytes of HTML code to the client
  853 +\end{enumerate}
  854 +
  855 +\Yaws\ writes the source output of the compilation into a directory
  856 +/tmp/yaws/\$UID. The beam files are never written to a file.
  857 +Sometimes it can be useful to look at the generated source code
  858 +files, for example if the \Yaws\ /\Erlang\ code contains a compilation
  859 +error which is hard to understand.
  860 +
  861 +
  862 +\section{Evaluating the \Yaws\ code}
  863 +
  864 +All client requests will execute in their own \Erlang\ process.
  865 +For each group of virtual hosts on the same IP:PORT pair
  866 +one \Erlang\ process listens for incoming requests.
  867 +
  868 +This process spawns acceptor processes for each incoming request.
  869 +Each acceptor process reads and parses all the HTTP headers from the
  870 +client. It then looks at the Host: header to figure out which
  871 +virtual server to use, i.e. which docroot to use for this
  872 +particular request. If the Host: header doesn't match
  873 +any server from \textit{yaws.conf} with that IP:PORT pair, the first
  874 +one from \textit{yaws.conf} is chosen.
  875 +
  876 +
  877 +By default \Yaws\ will not ship any data at all to the client
  878 +while evaluating a \Yaws\ page. The headers as well as the generated
  879 +content are accumulated and not shipped to the client until the
  880 +entire page has been processed.
  881 +
  882 +
  883 +
701 884 \chapter{SSL}
702 885
703   -\chapter{Security}
  886 +SSL - Secure Socket Layer is a protocol used on the Web for
  887 +delivering encrypted pages to the WWW client. SSL is widely deployed
  888 +on the Internet and virtually all bank transactions as well as all
  889 +on-line shopping today is done with SSL encryption. There are many
  890 +good sources on the net that describes SSL in detail - and I will not
  891 +try to do that here.
  892 +There is for example a good document at:
  893 +\verb+http://www.tldp.org/HOWTO/SSL-Certificates-HOWTO/+ which
  894 +describes how to manage certificates and keys.
  895 +
  896 +In order to run an SSL server we must have a certificate. Either we
  897 +can create a so called self-signed certificate ourselves or buy a
  898 +certificate from one of the many CA's (Certificate Authority's) on the
  899 +net. \Yaws\ use the otp interface to openssl.
  900 +
  901 +To setup a \Yaws\ server with SSL we could have a \textit{yaws.conf} file that
  902 +looks like:
  903 +
  904 +\begin{verbatim}
  905 +
  906 + logdir = /var/log/yaws
  907 +
  908 +<server www.funky.org>
  909 + port = 443
  910 + listen = 192.168.128.32
  911 + docroot = /var/yaws/www.funky.org
  912 + <ssl>
  913 + keyfile = /etc/funky.key
  914 + certfile = /etc/funky.cert
  915 + password = gazonk
  916 + </ssl>
  917 + </server>
  918 +\end{verbatim}
  919 +
  920 +This is the easiest possible SSL configuration. The configuration
  921 +refers to a certificate file and a key file. The certificate file
  922 +must contain the name "www.funky.org" as it "Common Name".
  923 +
  924 +The keyfile is the private key file and it is encrypted using
  925 +the password "gazonk".
  926 +
  927 +
  928 +
  929 +
  930 +