[master] c8add6f Add a conventions section.

[Lasse Karstensen]

commit c8add6f7d95d49846c23d5c21c31c6504fcbb092
Author: Lasse Karstensen <lkarsten at varnish-software.com>
Date:   Thu Mar 20 15:29:52 2014 +0100

    Add a conventions section.
    
    Try to document our conventions when it comes to commands, paths, tool names
    and similar.
    
    Also write some formatting rules for maintainers, like wrapping at 80
    characters and avoiding tabs.
    
    I'm happy to discuss changing these if someone feels strongly about anything,
    the main point is just to make it easier to read though being consequent about
    it throughout the manual.

diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst
index 830149a..11b4cce 100644
--- a/doc/sphinx/index.rst
+++ b/doc/sphinx/index.rst
@@ -1,36 +1,75 @@
+Welcome to the Varnish documentation!
+=====================================
+
+Introduction
+------------
+
+Varnish Cache is a web application accelerator also known as a caching HTTP
+reverse proxy. You install it in front of any server that speaks HTTP and
+configure it to cache the contents. Varnish Cache is really, really fast. It
+typically speeds up delivery with a factor of 300 - 1000x, depending on your
+architecture.
+
+
+To get started with Varnish-Cache we recommend that you read the installation
+guide :ref:`install-index`. Once you have Varnish up and running we recommend
+that you go through our tutorial - :ref:`tutorial-index`, and finally the
+:ref:`users_guide_index`.
+
+If you need to find out how to use a specific Varnish tool, the
+:ref:`reference-index` contains detailed documentation over the tools. Changes
+from previous versions are located in the :ref:`whats-new-index` chapter. In
+closing, we have :ref:`phk`, a collection of blog posts from Poul-Henning Kamp
+related to Varnish and HTTP.
+
+
+Conventions used
+----------------
+
+Conventions used in this manual include:
+
+  ``service varnish restart``
+    A command you can run, or a shortkey you can press. Used either in the
+    terminal or after starting one of the tools.
+
+  `/usr/local/`, `varnishadm`, `sess_timeout`
+    A utility, Varnish configurable parameter or path.
+
+  http://www.varnish-cache.org/
+    A hyperlink.
+
+Longer listings like example command output and VCL will look like this::
+
+    $ /opt/varnish/sbin/varnishd -V
+    varnishd (varnish-4.0.0-tp1 revision ddd00e1)
+    Copyright (c) 2006 Verdens Gang AS
+    Copyright (c) 2006-2011 Varnish Software AS
+
+
+.. For maintainers:
+.. * always write Varnish with a capital V: Varnish, Varnish Cache.
+.. * Write Varnish tools as their executable name: `varnishd`, `varnishadm`.
+.. * if part of a command actually runable by the reader, use double backticks:
+..   ``varnishd -f foo.c``
+.. * wrap lines at 80 characters, ident with 4 spaces. No tabs, please.
 .. We use the following header indicators
 .. For titles:
 
 .. H1
 .. %%%%%
+
 .. Title
 .. %%%%%
 
 .. H2 - H5
-.. ====================== 
+.. ======================
 .. ----------------------
 .. ~~~~~~~~~~~~~~~~~~~~~~
-.. ...................... 
+.. ......................
 
-Welcome to the Varnish documentation!
-=====================================
-
-Introduction
-------------
-
-Varnish Cache is a web application accelerator also known as a caching HTTP reverse proxy. You install it in front of any server that speaks HTTP and configure it to cache the contents. Varnish Cache is really, really fast. It typically speeds up delivery with a factor of 300 - 1000x, depending on your architecture. 
-It has its mission in front of a
-web server and cache content and it makes your web site go faster.
-
-To get started with Varnish-Cache we recommend that you read the installation guide
-:ref:`install-index`. Once you have Varnish up and running we recommend that you go through
-our tutorial - :ref:`tutorial-index`, and finally the :ref:`users_guide_index`.
-
-If you need to find out how to use a specific Varnish tool, the
-:ref:`reference-index` contains detailed documentation over the tools. Changes from previous versions are located in
-the :ref:`whats-new-index` chapter. In closing, we have :ref:`phk`, a collection
-of blog posts from Poul-Henning Kamp related to Varnish and HTTP.
 
+Table of contents
+-----------------
 
 
 .. toctree::