This is how we get refernces working both with shinx and rst2(man|pdf)

doc/README.WRITING_RST.rst

+THINGS TO CONSIDER WHEN WRITING VARNISH RST DOCUMENTATION
+=========================================================
+
+References are tricky
+---------------------
+
+To build html documentation, we want to create cross-document
+cross-references using::
+
+  :ref:`reference name`
+
+Trouble is that ``rst2man`` and ``rst2pdf`` refuse to parse `ref`
+roles (and wouldn't know where to create a link for cross-document
+references anyway), so we need to do something of both:
+
+* set link targets on the top of documents ending up in man-pages
+  following the manpage naming scheme, e.g.::
+
+    .. _varnishd(1):
+
+* set link targets for imporant paramgraphs following the scheme
+  ref-`doc`-`section`, for instance::
+
+    .. _ref-varnishd-opt_T:
+
+  These can be referenced from other documents making up the html
+  documentation, but not from documents creating man-pages.
+
+* in all documents which are used to create man-pages, add the
+  following definition at the top::
+
+    .. role:: ref(emphasis)
+
+  This will allow the use of `ref` in a compatible manner, IF refences
+  follow the man-page naming scheme
+
+* to be compatible both with ``sphinx`` and ``rst2man``, use `implicit
+  link targets`_ only, like this one creating `References are
+  tricky`_::
+
+    `References are tricky`_
+
+.. _implicit link targets: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#implicit-hyperlink-targets
+
+HISTORY
+=======
+
+This README was initially started by Nils Goroll.
+
+COPYRIGHT
+=========
+
+This document is licensed under the same licence as Varnish
+itself. See LICENCE for details.
+
+* Copyright 2014 UPLEX - Nils Goroll Systemoptimierung

doc/sphinx/reference/varnishd.rst

-.. _ref-varnishd:
+.. role:: ref(emphasis)
+
+.. _varnishd(1):
 
 ========
 varnishd
@@ -58,7 +60,7 @@ OPTIONS
 -f config
 
   Use the specified VCL configuration file instead of the builtin
-  default.  See :ref:`users_vcl` for details on VCL syntax. When no
+  default.  See :ref:`vcl(7)` for details on VCL syntax. When no
   configuration is supplied varnishd will not start the cache process.
 
 -F
@@ -73,7 +75,7 @@ OPTIONS
 
 -h <type[,options]>
 
-  Specifies the hash algorithm.  See :ref:`ref-varnishd-opt_s` for a
+  Specifies the hash algorithm.  See `Hash Algorithm Options`_ for a
   list of supported algorithms.
 
 -i identity
@@ -112,9 +114,9 @@ OPTIONS
 
 -p <param=value>
 
-  Set the parameter specified by param to the specified value.  See
-  :ref:`ref-varnishd-params` for a list of parameters. This option can
-  be used multiple times to specify multiple parameters.
+  Set the parameter specified by param to the specified value, see
+  `List of Parameters`_ for details. This option can be used multiple
+  times to specify multiple parameters.
 
 -r <param[,param...]>
 
@@ -127,7 +129,7 @@ OPTIONS
 
 -s <[name=]type[,options]>
 
-  Use the specified storage backend, see :ref:`ref-varnishd-opt_s`
+  Use the specified storage backend, see `Storage Backend Options`_.
 
   This option can be used multiple times to specify multiple storage
   files. Names are referenced in logs, vcl, statistics, etc.
@@ -140,7 +142,7 @@ OPTIONS
 -T <address[:port]>
 
   Offer a management interface on the specified address and port.  See
-  :ref:`ref-varnishd-opt_T` for a list of management commands.
+  `Management Interface`_ for a list of management commands.
 
 -t ttl
 

doc/sphinx/users-guide/compression.rst

@@ -11,7 +11,7 @@ be smart and do the sensible thing.
 
 If you don't want Varnish tampering with the encoding you can disable
 compression all together by setting the parameter `http_gzip_support` to
-false. Please see man :ref:`ref-varnishd` for details.
+false. Please see man :ref:`varnishd(1)` for details.
 
 Default behaviour
 ~~~~~~~~~~~~~~~~~

doc/sphinx/users-guide/index.rst

@@ -20,7 +20,7 @@ following the major interfaces to Varnish as a service:
 respect to storage, sockets, security and how you can control and
 communicate with Varnish once it is running.
 
-:ref:`users_vcl` is about getting Varnish to handle the
+:ref:`vcl(7)` is about getting Varnish to handle the
 HTTP requests the way you want, what to cache, how to cache it,
 modifying HTTP headers etc. etc.
 

doc/sphinx/users-guide/intro.rst

@@ -73,7 +73,7 @@ VCL code can be extended using external modules, called VMODs or
 even by inline C-code if you are brave, so in terms of what Varnish
 can do for your HTTP traffic, there really is no limit.
 
-:ref:`users_vcl` describes VCL and what it can do in great detail.
+:ref:`vcl(7)` describes VCL and what it can do in great detail.
 
 Varnish uses a segment of shared memory to report and log its activities and
 status. For each HTTP request, a number of very detailed records will

doc/sphinx/users-guide/vcl.rst

-.. _users_vcl:
+.. _vcl(7):
 
 VCL - Varnish Configuration Language
 ------------------------------------