Squash some RST warnings

doc/sphinx/installation/bugs.rst

@@ -83,13 +83,14 @@ general forms:
 	for HTTP headers and Cookies.
 
 	Please try that before reporting a bug.
-..  (TODO: which params to tweak)
 
 "Assert error in ..."
 	This is something bad that should never happen, and a bug
 	report is almost certainly in order. As always, if in doubt
 	ask us on IRC before opening the ticket.
 
+..  (TODO: in the ws-size note above, mention which params to tweak)
+
 In your syslog it may all be joined into one single line, but if you
 can reproduce the crash, do so while running `varnishd` manually:
 

doc/sphinx/installation/install.rst

@@ -141,7 +141,7 @@ And finally, the true test of a brave heart::
 
 	sudo make install
 
-Varnish will now be installed in `/usr/local`. The ``varnishd` binary is in
+Varnish will now be installed in `/usr/local`. The ``varnishd`` binary is in
 `/usr/local/sbin/varnishd` and its default configuration will be
 `/usr/local/etc/varnish/default.vcl`.
 

doc/sphinx/users-guide/command-line.rst

@@ -16,7 +16,7 @@ you will find the startup options here:
 
 
 '-a' *listen_address*
-^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^
 
 The '-a' argument defines what address Varnish should listen to, and service HTTP requests from.
 
@@ -42,7 +42,7 @@ If your webserver runs on the same machine, you will have to move
 it to another port number first.
 
 '-f' *VCL-file* or '-b' *backend*
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
 Varnish needs to know where to find the HTTP server it is caching for.

doc/sphinx/users-guide/esi.rst

@@ -82,7 +82,7 @@ For example::
   -->
 
 Doing ESI on JSON and other non-XML'ish content
-----------------------------------------------
+-----------------------------------------------
 
 Please note that Varnish will peek at the included content. If it
 doesn't start with a "<" Varnish assumes you didn't really mean to

doc/sphinx/users-guide/index.rst

@@ -40,9 +40,8 @@ from a transactional level to aggregating statistics.
    vcl
    report
    performance
-   esi   
+   esi
    troubleshooting
-   orphans
 
 .. customizing (which is a non ideal title)
 

doc/sphinx/users-guide/run_security.rst

@@ -168,8 +168,6 @@ Furthermore you may want to look at and lock down:
 
 :ref:`ref_param_syslog_cli_traffic`
 	Log all CLI commands to `syslog(8)`, so you know what goes on.
-.. XXX: syslog(8)? benc
-
 
 :ref:`ref_param_vcc_unsafe_path`
 	Restrict VCL/VMODS to :ref:`ref_param_vcl_dir` and :ref:`ref_param_vmod_dir`

doc/sphinx/users-guide/troubleshooting.rst

@@ -91,10 +91,8 @@ A core dumped is usually due to a bug in Varnish. However, in order to
 debug a segfault the developers need you to provide a fair bit of
 data.
 
- * Make sure you have Varnish installed with symbols
-.. XXX:Symbols? benc
- * Make sure core dumps are enabled (ulimit)
-.. XXX:ulimit? benc
+ * Make sure you have Varnish installed with debugging symbols.
+ * Make sure core dumps are allowed in the parent shell. (``ulimit -c unlimited``)
 
 Once you have the core you open it with `gdb` and issue the command ``bt``
 to get a stack trace of the thread that caused the segfault.

doc/sphinx/users-guide/vcl-syntax.rst

@@ -82,20 +82,20 @@ down for, uhm, examples.
 Subroutines
 ~~~~~~~~~~~
 
-A subroutine is used to group code for legibility or reusability:
-::
-  
+A subroutine is used to group code for legibility or reusability::
+
   sub pipe_if_local {
     if (client.ip ~ local) {
       return (pipe);
     }
   }
 
+
 Subroutines in VCL do not take arguments, nor do they return values.
 
 To call a subroutine, use the call keyword followed by the subroutine's name::
 
-call pipe_if_local;
+  call pipe_if_local;
 
 Varnish has quite a few built in subroutines that are called for each
 transaction as it flows through Varnish. These builtin subroutines are all named vcl_*. Your own subroutines cannot start their name with vcl_.

doc/sphinx/users-guide/vcl-variables.rst

 
-Requests and responses as objects
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Request and response VCL objects
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. XXX: refactored headline. benc
 
-In VCL, there several important objects that you need to be aware of. These objects can be accessed and manipulated using VCL.
+In VCL, there several important objects that you need to be aware of. These
+objects can be accessed and manipulated using VCL.
 
 
 *req*
- The request object. When Varnish has received the request the `req` object is 
- created and populated. Most of the work you do in `vcl_recv` you 
+ The request object. When Varnish has received the request the `req` object is
+ created and populated. Most of the work you do in `vcl_recv` you
  do on or with the `req` object.
 
 *bereq*
- The backend request object. Varnish contructs this before sending it to the 
+ The backend request object. Varnish contructs this before sending it to the
  backend. It is based on the `req` object.
 
 .. XXX:in what way? benc
 
 *beresp*
- The backend response object. It contains the headers of the object 
- coming from the backend. If you want to modify the reponse coming from the 
- server you modify this object in `vcl_backend_reponse`. 
+ The backend response object. It contains the headers of the object
+ coming from the backend. If you want to modify the response coming from the
+ server you modify this object in `vcl_backend_reponse`.
 
 *resp*
  The HTTP response right before it is delivered to the client. It is
  typically modified in `vcl_deliver`.
 
 *obj* 
- The object as it is stored in cache. Mostly read only.
+ The object as it is stored in cache. Read only.
+
 .. XXX:What object? the current request? benc