[master] 969fa64 the explanation was not quite correct yet
Nils Goroll
nils.goroll at uplex.de
Fri Mar 13 18:58:09 CET 2015
commit 969fa6401dae1b3a418034e44863774abf7ea172
Author: Nils Goroll <nils.goroll at uplex.de>
Date: Fri Mar 13 18:05:45 2015 +0100
the explanation was not quite correct yet
diff --git a/doc/README.WRITING_RST.rst b/doc/README.WRITING_RST.rst
index 06e4a76..19e7fe6 100644
--- a/doc/README.WRITING_RST.rst
+++ b/doc/README.WRITING_RST.rst
@@ -9,9 +9,10 @@ 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:
+Trouble is that ``rst2man`` and ``rst2pdf`` working on individual
+files cannot parse `ref` roles to anything outside the current rst
+file, so we need to differenciate link targets depending on the kind
+of documentation:
* set link targets on the top of documents ending up in man-pages
following the manpage naming scheme, e.g.::
@@ -24,19 +25,19 @@ references anyway), so we need to do something of both:
.. _ref-varnishd-opt_T:
These can be referenced from other documents making up the html
- documentation, but not from documents creating man-pages.
+ documentation, but not from stand-alone documents (like 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
+ This will allow the use of `ref` in a compatible manner, IF
+ references 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`_::
+ link targets`_ in stand-alone documents, like this one creating
+ `References are tricky`_::
`References are tricky`_
More information about the varnish-commit
mailing list