r4729 - in trunk/varnish-cache/doc/sphinx: . glossary installation tutorial

[phk at varnish-cache.org]

Author: phk
Date: 2010-04-26 22:09:14 +0200 (Mon, 26 Apr 2010)
New Revision: 4729

Added:
   trunk/varnish-cache/doc/sphinx/glossary/
   trunk/varnish-cache/doc/sphinx/glossary/index.rst
Modified:
   trunk/varnish-cache/doc/sphinx/index.rst
   trunk/varnish-cache/doc/sphinx/installation/index.rst
   trunk/varnish-cache/doc/sphinx/tutorial/index.rst
Log:
I started writing the tutorial, but got sidetracked on how to carry
through the hands-on.  Ended up starting a glossary instead.



Added: trunk/varnish-cache/doc/sphinx/glossary/index.rst
===================================================================
--- trunk/varnish-cache/doc/sphinx/glossary/index.rst	                        (rev 0)
+++ trunk/varnish-cache/doc/sphinx/glossary/index.rst	2010-04-26 20:09:14 UTC (rev 4729)
@@ -0,0 +1,111 @@
+
+.. _glossary:
+
+Varnish Glossary
+================
+
+.. glossary:: 
+   :sorted:
+
+   .. comment:
+
+	This file will be sorted automagically during formatting,
+	so we keep the source in subject order to make sure we
+	cover all bases.
+
+   .. comment: "components of varnish --------------------------------"
+
+   varnishd (NB: with 'd')
+	This is the actual Varnish cache program.  There is only
+	one program, but when you run it, you will get *two*
+	processes:  The "master" and the "worker" (or "child").
+
+   master (process)
+	One of the two processes in the varnishd program.
+	The master proces is a manager/nanny process which handles
+	configuration, parameters, compilation of :term:VCL etc.
+	but it does never get near the actual HTTP traffic.
+
+   worker (process)
+	The worker process is started and configured by the master
+	process.  This is the process that does all the work you actually
+	want varnish to do.  If the worker dies, the master will try start
+	it again, to keep your website alive..
+
+   backend
+	The HTTP server varnishd is caching for.  This can be
+	any sort of device that handles HTTP requests, including, but
+	not limited to:  a webserver, a CMS, a load-balancer 
+	another varnishd, etc.
+
+   client
+	The program which sends varnishd a HTTP request, typically
+	a browser, but do not forget to think about spiders, robots
+	script-kiddies and criminals.
+
+   varnishstat
+	Program which presents varnish statistics counters.
+
+   varnishlog
+	Program which presents varnish transaction log in native format.
+
+   varnishtop
+	Program which gives real-time "top-X" list view of transaction log.
+
+   varnishncsa
+	Program which presents varnish transaction log in "NCSA" format.
+
+   varnishhist
+	Eye-candy program showing responsetime histogram in 1980ies
+	ASCII-art style.
+
+   varnishtest
+	Program to test varnishd's behaviour with, simulates backend
+	and client according to test-scripts.
+
+   .. comment: "components of traffic ---------------------------------"
+
+   header
+	A HTTP protocol header, like "Accept-Encoding:".
+
+   request
+	What the client sends to varnishd and varnishd sends to the backend.
+
+   response
+	What the backend returns to varnishd and varnishd returns to 
+	the client.  When the response is stored in varnishd's cache,
+	we call it an object.
+
+   body
+	The bytes that make up the contents of the object, varnishd
+	does not care if they are in HTML, XML, JPEG or even EBCDIC,
+	to varnishd they are just bytes.
+
+   object
+	The cached version of a response.  Varnishd receives a reponse
+	from the backend and creates an object, from which it can
+	produce cached responses to clients.
+
+   .. comment: "configuration of varnishd -----------------------------"
+
+   VCL
+	Varnish Configuration Language, a small specialized language
+	for instructing Varnish how to behave.
+
+   .. comment: "actions in VCL ----------------------------------------"
+
+   hit
+	An object Varnish delivers from cache.
+
+   miss
+	An object Varnish fetches from the backend.  It may or may not
+	be putin the cache, that depends.
+
+   pass
+	An object Varnish does not try to cache, but simply fetches
+	from the backend and hands to the client.
+
+   pipe
+	Varnish just moves the bytes between client and backend, it
+	does not try to understand what they mean.
+

Modified: trunk/varnish-cache/doc/sphinx/index.rst
===================================================================
--- trunk/varnish-cache/doc/sphinx/index.rst	2010-04-26 08:50:25 UTC (rev 4728)
+++ trunk/varnish-cache/doc/sphinx/index.rst	2010-04-26 20:09:14 UTC (rev 4729)
@@ -19,6 +19,7 @@
    installation/index.rst
    tutorial/index.rst
    reference/index.rst
+   glossary/index.rst
 
 Indices and tables
 ==================

Modified: trunk/varnish-cache/doc/sphinx/installation/index.rst
===================================================================
--- trunk/varnish-cache/doc/sphinx/installation/index.rst	2010-04-26 08:50:25 UTC (rev 4728)
+++ trunk/varnish-cache/doc/sphinx/installation/index.rst	2010-04-26 20:09:14 UTC (rev 4729)
@@ -1,3 +1,5 @@
+.. _Installation:
+
 %%%%%%%%%%%%%%%%%%%%
 Varnish Installation
 %%%%%%%%%%%%%%%%%%%%

Modified: trunk/varnish-cache/doc/sphinx/tutorial/index.rst
===================================================================
--- trunk/varnish-cache/doc/sphinx/tutorial/index.rst	2010-04-26 08:50:25 UTC (rev 4728)
+++ trunk/varnish-cache/doc/sphinx/tutorial/index.rst	2010-04-26 20:09:14 UTC (rev 4729)
@@ -4,6 +4,36 @@
 Varnish Tutorial
 %%%%%%%%%%%%%%%%
 
+Welcome to the Varnish Tutorial, we hope this will help you get to 
+know and understand Varnish.
+
+Most tutorials are written in "subject-order", as the old Peanuts
+strip goes::
+
+	Jogging: A Handbook
+	Author:  S. Noopy
+	    Chapter 1: Left foot
+		It was a dark and stormy night...
+
+This is great when the reader has no choice, or nothing better to do, but
+read the entire document before starting.
+
+We have taken the other approach: "breadth-first", because experience
+has shown us that Varnish users wants to get things running, and then
+polish up things later on.
+
+With that in mind, we have written the tutorial so you can break off,
+as Calvin tells Ms. Wormwood, "when my brain is full for today", and
+come back later and learn more.
+
+That also means that right from the start, we will have several
+things going on in parallel and you will need at least four, sometimes
+more, terminal windows at the same time, to run the examples.
+
+
+//todo// First simple example (pending varnishtest support)
+
+
 .. todo::
         starting varnish with -d, seeing a transaction go through
         explain varnishlog output for a miss and a hit