Merge "[contributor] Update guideline of RST reference"

doc/contributor-guide/source/rst-conv/refs.rst

@@ -40,7 +40,7 @@ but within one directory. Otherwise, use the external linking.
 External references
 ~~~~~~~~~~~~~~~~~~~
 
-To link to some external locations, format RST source as follows:
+To link to some external locations, format the RST source as follows:
 
 * Do not apply any markups to specify a web link.
 
@@ -48,9 +48,9 @@ To link to some external locations, format RST source as follows:
   format a web link as ``Link text <http://web-link.com>``
   wrapping it in backticks.
 
-* If a source file contains a big number of external references,
-  you can separate a link from its definition for better readability
-  while reviewing as shown in the example.
+* Do not separate a link name from a link itself by defining the link in other
+  place in your document. It prevents translated documents from using different
+  links, for example, corresponding links to translated versions.
 
 **Input**
 
@@ -61,27 +61,9 @@ To link to some external locations, format RST source as follows:
    Here is an external web link with a link title:
   `User guide <http://docs.openstack.org/user-guide/>`_.
 
-   Here is an external web link separated from its definition:
-   This paragraph contains the link to `User guide`_.
-
-   ...
-
-   .. format the link definition at the end of the file as follows:
-   .. _`User guide`: http://docs.openstack.org/user-guide/
-
 **Output**
 
 Here is a link to the User guide: http://docs.openstack.org/user-guide/.
 
 Here is an external web link with a link title:
 `User guide <http://docs.openstack.org/user-guide/>`_.
-
-Here is an external web link separated from its definition:
-This paragraph contains the link to `User guide`_.
-
-...
-
-.. format the link definition at the end of the file as follows:
-.. _`User guide`: http://docs.openstack.org/user-guide/
-
-