doc: fix references (as described in doc/README.WRITING_RST.rst)

doc/sphinx/installation/bugs.rst

@@ -92,7 +92,7 @@ general forms:
 ..  (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:
+can reproduce the crash, do so while running :ref:`varnishd(1)` manually:
 
 	``varnishd -d <your other arguments> |& tee /tmp/_catch_bug``
 
@@ -127,8 +127,9 @@ If one or more threads are spinning, use ``strace`` or ``ktrace`` or ``truss``
 the Varnish process issues. Be aware that this may generate a lot
 of very repetitive data, usually one second worth of data is more than enough.
 
-Also, run ``varnishlog`` for a second, and collect the output
-for us, and if ``varnishstat`` shows any activity, capture that also.
+Also, run :ref:`varnishlog(1)` for a second, and collect the output
+for us, and if :ref:`varnishstat(1)` shows any activity, capture that
+also.
 
 When you have done this, kill the Varnish *child* process, and let
 the *master* process restart it.  Remember to tell us if that does
@@ -141,8 +142,8 @@ Varnish does something wrong
 ============================
 
 These are the easy bugs: usually all we need from you is the relevant
-transactions recorded with ``varnishlog`` and your explanation of
-what is wrong about what Varnish does.
+transactions recorded with :ref:`varnishlog(1)` and your explanation
+of what is wrong about what Varnish does.
 
 Be aware, that often Varnish does exactly what you asked it to, rather
 than what you intended it to do. If it sounds like a bug that would

doc/sphinx/phk/backends.rst

@@ -87,8 +87,9 @@ is a wildcard-ish scheme, where you can write things like::
 (Input very much welcome)
 
 The final question is if we use shortcut notation for output from
-varnishd, and the answer is no, because we do not want the stats-counters
-to change name because we load another VCL and suddenly need disabiguation.
+:ref:`varnishd(1)`, and the answer is no, because we do not want the
+stats-counters to change name because we load another VCL and suddenly
+need disabiguation.
 
 
 Sharing Health Status

doc/sphinx/reference/varnish-cli.rst

+.. role:: ref(emphasis)
+
+.. _varnish-cli(7):
+
 ===========
 varnish-cli
 ===========
@@ -40,7 +44,7 @@ If you invoke varnishd(1) with -T, -M or -d the CLI will be
 available. In debug mode (-d) the CLI will be in the foreground, with
 -T you can connect to it with varnishadm or telnet and with -M
 varnishd will connect back to a listening service *pushing* the CLI to
-that service. Please see varnishd(1) for details.
+that service. Please see :ref:`varnishd(1)` for details.
 
 
 Syntax
@@ -278,16 +282,16 @@ the backend contains "USERID=1663"::
 SEE ALSO
 ========
 
-* varnishd(1)
-* vanrishadm(1)
-* vcl(7)
+* :ref:`varnishd(1)`
+* :ref:`varnishadm(1)`
+* :ref:`vcl(7)`
 
 HISTORY
 =======
 
 The Varnish manual page was written by Per Buer in 2011. Some of the
-text was taken from the Varnish Cache wiki, the varnishd(7) man page
-or the Varnish source code.
+text was taken from the Varnish Cache wiki, the :ref:`varnishd(1)` man
+page or the Varnish source code.
 
 COPYRIGHT
 =========

doc/sphinx/reference/varnishadm.rst

-.. _ref-varnishadm:
+.. role:: ref(emphasis)
+
+.. _varnishadm(1):
 
 ==========
 varnishadm
@@ -43,13 +45,13 @@ OPTIONS
 -n name
     Connect to the instance of varnishd with this name.
 
--T address:port
+-T <address:port>
     Connect to the management interface at the specified address and port.
 
 
 The syntax and operation of the actual CLI interface is described in
-the varnish-cli(7) manual page. Parameteres are described in
-varnishd(1) manual page.
+the :ref:`varnish-cli(7)` manual page. Parameteres are described in
+:ref:`varnishd(1)` manual page.
 
 Additionally, a summary of commands can be obtained by issuing the
 *help* command, and a summary of parameters can be obtained by issuing
@@ -73,7 +75,7 @@ Some ways you can use varnishadm::
 SEE ALSO
 ========
 
-* varnishd(1)
+* :ref:`varnishd(1)`
 
 HISTORY
 =======

doc/sphinx/reference/varnishd.rst

@@ -358,13 +358,13 @@ The `varnishd` master process may also OR its exit code
 SEE ALSO
 ========
 
-* varnish-cli(7)
-* varnishlog(1)
-* varnishhist(1)
-* varnishncsa(1)
-* varnishstat(1)
-* varnishtop(1)
-* vcl(7)
+* :ref:`varnish-cli(7)`
+* :ref:`varnishlog(1)`
+* :ref:`varnishhist(1)`
+* :ref:`varnishncsa(1)`
+* :ref:`varnishstat(1)`
+* :ref:`varnishtop(1)`
+* :ref:`vcl(7)`
 
 HISTORY
 =======

doc/sphinx/reference/varnishhist.rst

-.. _ref-varnishhist:
+.. role:: ref(emphasis)
+
+.. _varnishhist(1):
 
 ===========
 varnishhist
@@ -33,11 +35,11 @@ The following options are available:
 SEE ALSO
 ========
 
-* varnishd(1)
-* varnishlog(1)
-* varnishncsa(1)
-* varnishstat(1)
-* varnishtop(1)
+* :ref:`varnishd(1)`
+* :ref:`varnishlog(1)`
+* :ref:`varnishncsa(1)`
+* :ref:`varnishstat(1)`
+* :ref:`varnishtop(1)`
 
 HISTORY
 =======

doc/sphinx/reference/varnishlog.rst

-.. _ref-varnishlog:
+.. role:: ref(emphasis)
+
+.. _varnishlog(1):
 
 ==========
 varnishlog
@@ -36,13 +38,13 @@ SIGNALS
 
 SEE ALSO
 ========
-* varnishd(1)
-* varnishhist(1)
-* varnishncsa(1)
-* varnishstat(1)
-* varnishtop(1)
-* vsl(7)
-* vsl-query(7)
+* :ref:`varnishd(1)`
+* :ref:`varnishhist(1)`
+* :ref:`varnishncsa(1)`
+* :ref:`varnishstat(1)`
+* :ref:`varnishtop(1)`
+* :ref:`vsl(7)`
+* :ref:`vsl-query(7)`
 
 HISTORY
 =======

doc/sphinx/reference/varnishncsa.rst

-.. _ref-varnishncsa:
+.. role:: ref(emphasis)
+
+.. _varnishncsa(1):
 
 ===========
 varnishncsa
@@ -134,9 +136,9 @@ SIGUSR1
 SEE ALSO
 ========
 
-varnishd(1)
-varnishlog(1)
-varnishstat(1)
+:ref:`varnishd(1)`
+:ref:`varnishlog(1)`
+:ref:`varnishstat(1)`
 
 HISTORY
 =======

doc/sphinx/reference/varnishstat.rst

-.. _ref-varnishstat:
+.. role:: ref(emphasis)
+
+.. _varnishstat(1):
 
 ===========
 varnishstat
@@ -184,11 +186,11 @@ between each block of output.
 SEE ALSO
 ========
 
-* varnishd(1)
-* varnishhist(1)
-* varnishlog(1)
-* varnishncsa(1)
-* varnishtop(1)
+* :ref:`varnishd(1)`
+* :ref:`varnishhist(1)`
+* :ref:`varnishlog(1)`
+* :ref:`varnishncsa(1)`
+* :ref:`varnishtop(1)`
 * curses(3)
 
 HISTORY

doc/sphinx/reference/varnishtest.rst

-.. _ref-varnishtest:
+.. role:: ref(emphasis)
+
+.. _varnishtest(1):
 
 ===========
 varnishtest
@@ -114,12 +116,12 @@ SEE ALSO
 ========
 
 * varnishtest source code repository with tests
-* varnishhist(1)
-* varnishlog(1)
-* varnishncsa(1)
-* varnishstat(1)
-* varnishtop(1)
-* vcl(7)
+* :ref:`varnishhist(1)`
+* :ref:`varnishlog(1)`
+* :ref:`varnishncsa(1)`
+* :ref:`varnishstat(1)`
+* :ref:`varnishtop(1)`
+* :ref:`vcl(7)`
 
 HISTORY
 =======

doc/sphinx/reference/varnishtop.rst

-.. _ref-varnishtop:
+.. role:: ref(emphasis)
+
+.. _varnishtop(1):
 
 ==========
 varnishtop
@@ -19,7 +21,7 @@ varnishtop |synopsis|
 DESCRIPTION
 ===========
 
-The varnishtop utility reads ``varnishd(1)`` shared memory logs and
+The varnishtop utility reads :ref:`varnishd(1)` shared memory logs and
 presents a continuously updated list of the most commonly occurring
 log entries.  With suitable filtering using the ``-I``, ``-i``, ``-X``
 and ``-x`` options, it can be used to display a ranking of requested
@@ -46,11 +48,11 @@ commonly used user agents::
 SEE ALSO
 ========
 
-* varnishd(1)
-* varnishhist(1)
-* varnishlog(1)
-* varnishncsa(1)
-* varnishstat(1)
+* :ref:`varnishd(1)`
+* :ref:`varnishhist(1)`
+* :ref:`varnishlog(1)`
+* :ref:`varnishncsa(1)`
+* :ref:`varnishstat(1)`
 
 HISTORY
 =======

doc/sphinx/reference/vcl.rst

-.. _reference-vcl:
+.. role:: ref(emphasis)
+
+.. _vcl(7):
 
 ===
 VCL
@@ -220,7 +222,7 @@ are available:
     Timeout between bytes.
 
   probe
-    Attach a probe to the backend. See Probes.
+    Attach a probe to the backend. See `Probes`_
 
   max_connections
     Maximum number of open connections towards this backend. If
@@ -228,7 +230,7 @@ are available:
     connections.
 
 Backends can be used with *directors*. Please see the
-vmod_directors(3) man page for more information.
+:ref:`vmod_directors(3)` man page for more information.
 
 .. _reference-vcl_probes:
 
@@ -418,9 +420,9 @@ For examples, please see the online documentation.
 SEE ALSO
 ========
 
-* varnishd(1)
-* vmod_directors(3)
-* vmod_std(3)
+* :ref:`varnishd(1)`
+* :ref:`vmod_directors(3)`
+* :ref:`vmod_std(3)`
 
 HISTORY
 =======

doc/sphinx/reference/vsl-query.rst

-.. _ref-vsl-query:
+.. role:: ref(emphasis)
+
+.. _vsl-query(7):
 
 =========
 vsl-query

doc/sphinx/reference/vsl.rst

-.. _reference-vsl:
+.. role:: ref(emphasis)
+
+.. _vsl(7):
 
 ===
 VSL
@@ -109,7 +111,8 @@ Martin Blix Grydeland.
 
 SEE ALSO
 ========
-* varnishlog(1)
-* varnishhist(1)
-* varnishncsa(1)
-* varnishtop(1)
+
+* :ref:`varnishlog(1)`
+* :ref:`varnishhist(1)`
+* :ref:`varnishncsa(1)`
+* :ref:`varnishtop(1)`

doc/sphinx/tutorial/peculiarities.rst

@@ -23,8 +23,8 @@ varnishadm
 ~~~~~~~~~~
 
 Varnish Cache has an admin console. You can connect it it through the
-``varnishadm`` command. In order to connect the user needs to be able to
-read `/etc/varnish/secret` in order to authenticate.
+:ref:`varnishadm(1)` command. In order to connect the user needs to be
+able to read `/etc/varnish/secret` in order to authenticate.
 
 Once you've started the console you can do quite a few operations on
 Varnish, like stopping and starting the cache process, load VCL,
@@ -39,11 +39,7 @@ varnishlog
 ~~~~~~~~~~
 
 Varnish does not log to disk. Instead it logs to a chunk of memory. It
-is actually streaming the logs. At any time you'll be able to connect to the
-stream and see what is going on. Varnish logs quite a bit of
+is actually streaming the logs. At any time you'll be able to connect
+to the stream and see what is going on. Varnish logs quite a bit of
 information. You can have a look at the logstream with the command
-``varnishlog``.
-
-
-
-
+:ref:`varnishlog(1)`.

doc/sphinx/users-guide/increasing-your-hitrate.rst

@@ -16,9 +16,10 @@ you should find useful to understand what is happening in your
 Varnish setup.
 
 Note that you need a tool to see the HTTP headers that fly between
-Varnish and the backend. On the Varnish server, the easiest way to
-do this is to use `varnishlog` and `varnishtop` but sometimes a
-client-side tool makes sense. Here are the ones we commonly use.
+Varnish and the backend. On the Varnish server, the easiest way to do
+this is to use :ref:`varnishlog(1)` and :ref:`varnishtop(1)` but
+sometimes a client-side tool makes sense. Here are the ones we
+commonly use.
 
 Tool: varnishtop
 ~~~~~~~~~~~~~~~~
@@ -26,19 +27,19 @@ Tool: varnishtop
 You can use varnishtop to identify what URLs are hitting the backend
 the most. ``varnishtop -i BereqURL`` is an essential command, showing
 you the top requests Varnish is sending to the backend. You can see some
-other examples of `varnishtop` usage in :ref:`users-guide-statistics`.
+other examples of :ref:`varnishtop(1)` usage in :ref:`users-guide-statistics`.
 
 
 Tool: varnishlog
 ~~~~~~~~~~~~~~~~
 
 When you have identified an URL which is frequently sent to the
-backend you can use `varnishlog` to have a look at the request.
-``varnishlog -q 'ReqURL ~ "^/foo/bar"'`` will show you the requests
-coming from the client matching `/foo/bar`.
+backend you can use :ref:`varnishlog(1)` to have a look at the
+request.  ``varnishlog -q 'ReqURL ~ "^/foo/bar"'`` will show you the
+requests coming from the client matching `/foo/bar`.
 
-For more information on how `varnishlog` works please see
-:ref:`users-guide-logging` or man :ref:`ref-varnishlog`.
+For more information on how :ref:`varnishlog(1)` works please see
+:ref:`users-guide-logging` or then man page.
 
 For extended diagnostics headers, see
 https://www.varnish-cache.org/trac/wiki/VCLExampleHitMissHeader
@@ -240,8 +241,8 @@ Age
 ~~~
 
 Varnish adds an 'Age' header to indicate how long the object has been
-kept inside Varnish. You can grep out 'Age' from `varnishlog` with
-``varnishlog -I RespHeader:^Age``.
+kept inside Varnish. You can grep out 'Age' from :ref:`varnishlog(1)`
+with ``varnishlog -I RespHeader:^Age``.
 
 Pragma
 ~~~~~~

doc/sphinx/users-guide/operation-logging.rst

@@ -74,4 +74,4 @@ want to know are:
 
 .. XXX:Maybe a couple of sample commands here? benc
 
-For more information on this topic please see :ref:`ref-varnishlog`.
+For more information on this topic please see :ref:`varnishlog(1)`.

doc/sphinx/users-guide/operation-statistics.rst

@@ -11,7 +11,7 @@ Varnish comes with a couple of nifty and very useful statistics generating tools
 varnishtop
 ~~~~~~~~~~
 
-The `varnishtop` utility reads the shared memory logs and presents a
+The :ref:`varnishtop(1)` utility reads the shared memory logs and presents a
 continuously updated list of the most commonly occurring log entries.
 
 With suitable filtering using the -I, -i, -X and -x options, it can be
@@ -23,34 +23,27 @@ the client. ``varnishtop -i BereqURL`` will show you what your backend
 is being asked the most. ``varnishtop -I ReqHeader:Accept-Encoding`` will
 show the most popular Accept-Encoding header the client are sending you.
 
-For more information please see :ref:`ref-varnishtop`.
-
 varnishhist
 ~~~~~~~~~~~
 
-The `varnishhist` utility reads `varnishd(1)` shared memory logs and
-presents a continuously updated histogram showing the distribution of
-the last N requests by their processing.  
+The :ref:`varnishhist(1)` utility reads :ref:`varnishd(1)` shared
+memory logs and presents a continuously updated histogram showing the
+distribution of the last N requests by their processing.
 .. XXX:1? benc
 The value of N and the
 vertical scale are displayed in the top left corner.  The horizontal
 scale is logarithmic.  Hits are marked with a pipe character ("|"),
 and misses are marked with a hash character ("#").
 
-For more information please see :ref:`ref-varnishhist`.
-
-
 varnishstat
 ~~~~~~~~~~~
 
 Varnish has lots of counters. We count misses, hits, information about
 the storage, threads created, deleted objects. Just about
-everything. `varnishstat` will dump these counters. This is useful when
+everything. :ref:`varnishstat(1)` will dump these counters. This is useful when
 tuning Varnish.
 
-There are programs that can poll `varnishstat` regularly and make nice
-graphs of these counters. One such program is Munin. Munin can be
-found at http://munin-monitoring.org/ . There is a plugin for munin in
-the Varnish source code.
-
-For more information please see :ref:`ref-varnishstat`.
+There are programs that can poll :ref:`varnishstat(1)` regularly and
+make nice graphs of these counters. One such program is Munin. Munin
+can be found at http://munin-monitoring.org/ . There is a plugin for
+munin in the Varnish source code.

doc/sphinx/users-guide/sizing-your-cache.rst

@@ -13,10 +13,10 @@ Deciding on cache size can be a tricky task. A few things to consider:
    they are cheap to serve from the backend and you have a limited
    amount of memory.
 
- * Watch the `n_lru_nuked` counter with :ref:`ref-varnishstat` or
-   some other tool. If you have a lot of LRU activity then your cache
-   is evicting objects due to space constraints and you should
-   consider increasing the size of the cache.
+ * Watch the `n_lru_nuked` counter with :ref:`varnishstat(1)` or some
+   other tool. If you have a lot of LRU activity then your cache is
+   evicting objects due to space constraints and you should consider
+   increasing the size of the cache.
 
 Be aware that every object that is stored also carries overhead that
 is kept outside the actually storage area. So, even if you specify ``-s

doc/sphinx/users-guide/troubleshooting.rst

@@ -3,11 +3,13 @@
 Troubleshooting Varnish
 =======================
 
-Sometimes Varnish misbehaves or rather behaves the way you told it to behave but not necessarily the way you want it to behave. In order for you to understand whats
-going on there are a couple of places you can check. `varnishlog`,
-`/var/log/syslog`, `/var/log/messages` are all good places where Varnish might
-leave clues of whats going on. This section will guide you through
-basic troubleshooting in Varnish.
+Sometimes Varnish misbehaves or rather behaves the way you told it to
+behave but not necessarily the way you want it to behave. In order for
+you to understand whats going on there are a couple of places you can
+check. :ref:`varnishlog(1)`, `/var/log/syslog`, `/var/log/messages`
+are all good places where Varnish might leave clues of whats going
+on. This section will guide you through basic troubleshooting in
+Varnish.
 
 
 When Varnish won't start
@@ -101,26 +103,26 @@ to get a stack trace of the thread that caused the segfault.
 Varnish gives me Guru meditation
 --------------------------------
 
-First find the relevant log entries in `varnishlog`. That will probably
-give you a clue. Since `varnishlog` logs a lot of data it might be hard
-to track the entries down. You can set `varnishlog` to log all your 503
-errors by issuing the following command::
+First find the relevant log entries in :ref:`varnishlog(1)`. That will
+probably give you a clue. Since :ref:`varnishlog(1)` logs a lot of
+data it might be hard to track the entries down. You can set
+:ref:`varnishlog(1)` to log all your 503 errors by issuing the
+following command::
 
    $ varnishlog -q 'RespStatus == 503' -g request
 
-If the error happened just a short time ago the transaction might still
-be in the shared memory log segment. To get `varnishlog` to process the
-whole shared memory log just add the '-d' parameter::
+If the error happened just a short time ago the transaction might
+still be in the shared memory log segment. To get :ref:`varnishlog(1)`
+to process the whole shared memory log just add the '-d' parameter::
 
    $ varnishlog -d -q 'RespStatus == 503' -g request
 
-Please see the `vsl-query` and `varnishlog` man pages for elaborations
-on further filtering capabilities and explanation of the various
-options.
+Please see the :ref:`vsl-query(7)` and :ref:`varnishlog(1)` man pages
+for elaborations on further filtering capabilities and explanation of
+the various options.
 
 
 Varnish doesn't cache
 ---------------------
 
 See :ref:`users-guide-increasing_your_hitrate`.
-

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

@@ -186,7 +186,7 @@ poll will send a GET request to /. If 3 out of the last 5 polls succeeded
 the backend is considered healthy, otherwise it will be marked as sick.
 
 Refer to the :ref:`reference-vcl_probes` section in the
-:ref:`reference-vcl` documentation for more information.
+:ref:`vcl(7)` documentation for more information.
 
 Now we define the 'director'::
 

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

@@ -11,7 +11,7 @@ Note that VCL doesn't contain any loops or jump statements.
 
 This section provides an outline of the more important parts of the
 syntax. For a full documentation of VCL syntax please see
-:ref:`reference-vcl` in the reference.
+:ref:`vcl(7)` in the reference.
 
 Strings
 ~~~~~~~
@@ -60,10 +60,10 @@ Operators
 The following operators are available in VCL. See the examples further
 down for, uhm, examples.
 
-= 
+=
  Assignment operator.
 
-== 
+==
  Comparison.
 
 ~

doc/sphinx/whats-new/upgrading.rst

@@ -243,7 +243,6 @@ Other changes
 New log filtering
 ~~~~~~~~~~~~~~~~~
 
-The logging framework has a new filtering language, which means
-that the -m switch has been replaced with a new -q switch.
-See :ref:`ref-vsl-query` for more information about the new
-query language.
+The logging framework has a new filtering language, which means that
+the -m switch has been replaced with a new -q switch.  See
+:ref:`vsl-query(7)` for more information about the new query language.

lib/libvcc/vmodtool.py

@@ -309,7 +309,9 @@ class Vmod(object):
 		self.doc_str.append(l)
 
 	def doc_dump(self, fo, suf):
+		fo.write(".. role:: ref(emphasis)\n\n")
 		i = "vmod_" + self.nam
+		fo.write(".. _" + i + "(" + self.sec + "):\n\n")
 		fo.write("=" * len(i) + "\n")
 		fo.write(i + "\n")
 		fo.write("=" * len(i) + "\n")

lib/libvmod_std/vmod.vcc

@@ -260,8 +260,8 @@ Example
 SEE ALSO
 ========
 
-* vcl(7)
-* varnishd(1)
+* :ref:`vsl(7)`
+* :ref:`varnishd(1)`
 
 HISTORY
 =======
@@ -275,4 +275,3 @@ COPYRIGHT
 
 This document is licensed under the same licence as Varnish
 itself. See LICENCE for details.
-