Doc: fix broken links and syntax errors

doc/admin/transparent-proxy.en.rst

@@ -27,7 +27,6 @@ Transparent Proxying
    transparent-proxy/build.en
    transparent-proxy/bridge.en
    transparent-proxy/router-inline.en
-   transparent-proxy/router-inline.en
    transparent-proxy/wccp-configuration.en
 
 Transparent Proxying is the ability of a proxy (such as ATS) to
@@ -108,7 +107,7 @@ address of the ATS server via DNS as the origin server address.
 
 Some tested scenarios --
 
--  `Transparent bridging <bridge>`_
--  `Inline router <router-inline>`_
--  `WCCP Configuration <wccp-configuration>`_
+-  :doc:`transparent-proxy/bridge.en`
+-  :doc:`transparent-proxy/router-inline.en`
+-  :doc:`transparent-proxy/wccp-configuration.en`
 

doc/admin/transparent-proxy/bridge.en.rst

@@ -78,7 +78,7 @@ Although it looks like this will intercept all port 80 traffic it will
 only affect the two flows described above. ``-j redirect`` marks the
 packet as being diverted to the bridge and not forwarded, and the
 ``DROP`` target puts the packets in the normal ``iptables`` routing so
-that we can use standard device tests on them [1]_(#1). Although this
+that we can use standard device tests on them [1]_. Although this
 example handles only port 80, other ports are the same except for the
 port value. Note also the port here is the port from the point of view
 of the clients and origin servers, not the Traffic Server server port. ::
@@ -138,7 +138,7 @@ Additional troubleshooting
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * Check to make sure that ``iptables`` is not filtering (blocking)
-incoming HTTP connections.
+  incoming HTTP connections.
 
    It is frequently the case that the default tables prevent incoming HTTP. You can clear all filters with the
    commands::
@@ -154,7 +154,9 @@ incoming HTTP connections.
    Note that this problem will prevent the basic bridge (without ATS) from
    allowing HTTP traffic through.
 
-* Verify that IP packet forwarding is enabled. You can check this with::
+* Verify that IP packet forwarding is enabled.
+
+   You can check this with::
 
       cat /proc/sys/net/ipv4/ip_forward
 

doc/admin/transparent-proxy/router-inline.en.rst

@@ -75,10 +75,9 @@ To configure Traffic Server set the following values in
 
 ``proxy.config.http.server_port``
     ``STRING``
-    Default: *value from* ```--on-port`` <#on_port>`_
+    Default: *value from* ``--on-port``
 
-proxy.config.http.server_port_attr
-{#proxy.config.http.server_port_attr}
+``proxy.config.http.server_port_attr``
     ``STRING``
     Default: ``=``
 

doc/admin/transparent-proxy/wccp-configuration.en.rst

@@ -33,7 +33,7 @@ are
 -  WCCP fails open so that if the Traffic Server machine fails, it is
    bypassed and users continue to have Internet access.
 
-Use of WCCP only makes sense for client side transparency [1]_(#1)
+Use of WCCP only makes sense for client side transparency [1]_
 because if the clients are explicitly proxied by Traffic Server there's
 no benefit to WCCP fail open, as the clients will continue to directly
 access the unresponsive Traffic Server host. It would be better to
@@ -85,7 +85,7 @@ are to be used.
 
 In general the dedicated topology is preferred. However, if the router
 has only two interfaces one of the shared topologies will be
-required [2]_(#2). Click the links above for more detailed configuration
+required [2]_ Click the links above for more detailed configuration
 information on a specific topology.
 
 Shared interface issues
@@ -102,7 +102,7 @@ the dedicated interface case. This enables the packets to be
 distinguished at layer 3. For this reason, layer 2 redirection cannot be
 used because the WCCP configuration cannot distinguish between packets
 returning from the origin server and packets returning from Traffic
-Server as they are distinguished only by layer 2 addressing [3]_(#3).
+Server as they are distinguished only by layer 2 addressing [3]_.
 Fortunately the GRE tunnel used for packet forwarding and return can be
 used as the simulated interface for Traffic Server.
 

doc/reference/configuration/records.config.en.rst

@@ -1313,6 +1313,7 @@ Customizable User Response Pages
 ================================
 
 .. ts:cv:: CONFIG proxy.config.body_factory.enable_customizations INT 1
+
    Specifies whether customizable response pages are language specific
    or not:
 

doc/sdk/continuations.en.rst

@@ -31,11 +31,11 @@ mutex.
 
 This chapter covers the following topics:
 
--  `Mutexes and Data <MutexesData>`__
+-  `Mutexes and Data`_
 
--  `How to Activate Continuations <ActivateContinuations.html>`__
+-  :doc:`continuations/how-to-activate-continuations.en`
 
--  `Writing Handler Functions <WritingHandlerFunctions.html>`__
+-  :doc:`continuations/writing-handler-functions.en`
 
 Mutexes and Data
 ----------------
@@ -55,15 +55,13 @@ one of the following:
 Before being activated, a caller must grab the continuation's mutex.
 This requirement makes it possible for a continuation's handler function
 to safely access its data and to prevent multiple callers from running
-it at the same time (see the `sample Protocol
-plugin <../new-protocol-plugins#AboutSampleProtocol>`__ for usage). The
+it at the same time (see the :ref:`about-the-sample-protocol` for usage). The
 data protected by the mutex is any global or continuation data
 associated to the continuation by ``TSContDataSet``. This does not
 include the local data created by the continuation handler function. A
 typical example of continuations created with associated data structures
 and mutexes is the transaction state machine created in the sample
-Protocol plugin (see `One Way to Implement a Transaction State
-Machine <../new-protocol-plugins#OneWayImplementaTransactionStateMachine>`__).
+Protocol plugin (see :ref:`one-way-to-implement-a-transaction-state-machine`).
 
 A reentrant call occurs when the continuation passed as an argument to
 the API can be called in the same stack trace as the function calling

doc/sdk/getting-started.en.rst

@@ -31,22 +31,19 @@ The Traffic Server API enables you to create plugins, using the C
 programming language, that customize the behavior of your Traffic Server
 installation. This chapter contains the following sections:
 
--  `Understanding Traffic Server Plugins <#UnderstandingTSPlugins>`__ --
-   a brief introduction to plugins. For more details, see `How to Create
-   Traffic Server Plugins <../how-to-create-trafficserver-plugins>`__
+-  `Understanding Traffic Server Plugins`_ -- a brief introduction to plugins.
+   For more details, see :doc:`how-to-create-trafficserver-plugins.en`
 
--  `A Simple Plugin <a-simple-plugin>`__ -- walks through compiling and
+-  :doc:`getting-started/a-simple-plugin.en` -- walks through compiling and
    loading an example ``hello world`` plugin.
 
--  `Plugin Registration and Version
-   Checking <plugin-registration-and-version-checking>`__ -- shows you
-   how to register your plugin and make sure it's compatible with the
+-  :doc:`getting-started/plugin-registration-and-version-checking.en` -- shows
+   you how to register your plugin and make sure it's compatible with the
    version of Traffic Server you're using.
 
--  `Naming Conventions <NamingConventions.html>`__ -- outlines Traffic
+-  :doc:`getting-started/naming-conventions.en` -- outlines Traffic
    Server API naming conventions. For guidelines on creating plugin
-   source code, see `How to Create Traffic Server
-   Plugins <../how-to-create-trafficserver-plugins>`__
+   source code, see :doc:`how-to-create-trafficserver-plugins.en`
 
 Understanding Traffic Server Plugins
 ------------------------------------
@@ -80,7 +77,9 @@ call-back functions you've registered for that event type.
    out-of-range pointer, can cause Traffic Server processes to crash and
    may ultimately result in unpredictable behavior.
 
-**Plugin Process** {#PluginProcess}
+**Plugin Process**
+
+.. _PluginProcess:
 
 .. figure:: /static/images/sdk/plugin_process.jpg
    :align: center
@@ -123,10 +122,11 @@ Some examples of plugins include:
    designated port and then uses Traffic Server's proxy server & cache
    to serve client requests.
 
-The figure below, `Possible Traffic Server
-Plugins <#possibleTSplugins>`__, illustrates several types of plugins.
+The figure below, :ref:`possibleTSplugins`, illustrates several types of plugins.
+
+**Possible Traffic Server Plugins**
 
-**Possible Traffic Server Plugins** {#possibleTSplugins}
+.. _possibleTSplugins:
 
 .. figure:: /static/images/sdk/Uses.jpg
    :align: center
@@ -137,8 +137,8 @@ Plugins <#possibleTSplugins>`__, illustrates several types of plugins.
 You can find basic examples for many plugins in the SDK sample code:
 
 -  ``append-transform.c`` adds text from a specified file to HTTP/text
-   responses. This plugin is explained in `The Append-Transform
-   Plugin <../http-transformation-plugin/append-transform-plugin>`__
+   responses. This plugin is explained in
+   :doc:`http-transformation-plugin/append-transform-plugin.en`
 
 -  The compression plugin in the figure communicates with the server
    that actually does the compression. The ``server-transform.c`` plugin
@@ -152,8 +152,7 @@ You can find basic examples for many plugins in the SDK sample code:
 
 -  ``blacklist-1.c`` reads blacklisted servers from a configuration file
    and denies client access to these servers. This plugin is explained
-   in `The Blacklist
-   Plugin <../header-based-plugin-examples/blacklist-plugin>`__.
+   in :doc:`header-based-plugin-examples/blacklist-plugin.en`.
 
 Plugin Loading
 ~~~~~~~~~~~~~~
@@ -163,8 +162,7 @@ file to determine the names of all shared plugin libraries that need to
 be loaded. The ``plugin.config`` file also defines arguments that are to
 be passed to each plugin's initialization function, ``TSPluginInit``.
 The :file:`records.config` file defines the path to each plugin shared
-library, as described in `Specify the Plugin's
-Location <SpecifyingPluginLocation.html>`__.
+library, as described in :ref:`specify-the-plugins-location`.
 
 .. note:: The path for each of these files is *<root_dir>*\ ``/config/``, where *<root_dir>* is where you installed Traffic Server.
 
@@ -243,5 +241,4 @@ The ``TSPluginInit`` function has two arguments:
 -  The ``argv`` argument is an array of pointers to the actual arguments
    defined in the ``plugin.config`` file for that plugin
 
-See `TSPluginInit <InitializationFunctions.html#TSPluginInit>`__ for
-details about ``TSPluginInit``.
+See :c:func:`TSPluginInit` for details about ``TSPluginInit``.

doc/sdk/getting-started/a-simple-plugin.en.rst

@@ -77,6 +77,8 @@ functions are triggered by the same event, then Traffic Server invokes
 each plugin's function in the order each was defined in the
 ``plugin.config`` file.
 
+.. _specify-the-plugins-location:
+
 Specify the Plugin's Location
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/sdk/getting-started/plugin-registration-and-version-checking.en.rst

@@ -23,8 +23,8 @@ version of Traffic Server.
 
 Use the following interfaces:
 
--  ```TSPluginRegister`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a6d7f514e70abaf097c4a3f1ba01f6df8>`__
--  ```TSTrafficServerVersionGet`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a3ef91e01612ffdce6dd040f836db08e8>`__
+-  `TSPluginRegister <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a6d7f514e70abaf097c4a3f1ba01f6df8>`_
+-  `TSTrafficServerVersionGet <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a3ef91e01612ffdce6dd040f836db08e8>`_
 
 The following version of ``hello-world`` registers the plugin and
 ensures it's running with a compatible version of Traffic Server.

doc/sdk/header-based-plugin-examples/blacklist-plugin.en.rst

@@ -25,8 +25,7 @@ blacklisted site, then the plugin returns an ``Access forbidden``
 message to the client.
 
 The flow of HTTP processing with the blacklist plugin is illustrated in
-the figure titled `"Blacklist
-Plugin" <../../how-to-create-trafficserver-plugins#BlacklistPlugin>`__.
+the figure titled :ref:`BlackListPlugin`.
 This example also contains a simple configuration management interface.
 It can read a list of blacklisted sites from a file (``blacklist.txt``)
 that can be updated by a Traffic Server administrator. When the
@@ -49,7 +48,7 @@ Traffic Server has a multi-threaded design, race conditions can occur if
 several threads try to access the same continuation's data.
 
 Here is how the static parent continuation is created in
-:file:blacklist-1.c`:
+``blacklist-1.c``:
 
 .. code-block:: c
 
@@ -93,9 +92,9 @@ When you write handler functions, you have to anticipate any events that
 might be sent to the handler by hooks or by other functions. In the
 Blacklist plugin, ``TS_EVENT_OS_DNS`` is sent because of the global hook
 established in ``TSPluginInit``, ``TS_EVENT_HTTP_SEND_RESPONSE_HDR`` is
-sent because the plugin contains a transaction hook (see `Setting Up a
-Transaction Hook <setting-a-transaction-hook.html>`__). It is good
-practice to have a default case in your switch statements.
+sent because the plugin contains a transaction hook
+(see :doc:`blacklist-plugin/setting-up-a-transaction-hook.en`).
+It is good practice to have a default case in your switch statements.
 
 .. toctree::
    :maxdepth: 2

doc/sdk/how-to-create-trafficserver-plugins.en.rst

@@ -1,4 +1,4 @@
-.. _how-to-create-traffic-server-plugins:
+.. _how-to-create-trafficserver-plugins:
 
 How to Create Traffic Server Plugins
 ************************************
@@ -39,7 +39,7 @@ Reading this chapter will help you to understand:
 -  How plugins can hook onto and modify/extend Traffic Server's HTTP
    processing.
 
--  A `roadmap for writing plugins <roadmap-for-creating-plugins>`__,
+-  A :doc:`roadmap for writing plugins <how-to-create-trafficserver-plugins/roadmap-for-creating-plugins.en>`,
    with an overview of the functionality provided by the Traffic Server
    API.
 
@@ -74,7 +74,7 @@ implemented as continuations.
 Continuation objects are used throughout Traffic Server. Some might live
 for the duration of the Traffic Server process, while others are created
 (perhaps by other continuations) for specific needs and then destroyed.
-`Traffic Server Internals <#TSInternals>`__ (below) shows how the major
+:ref:`TSInternals` (below) shows how the major
 components of Traffic Server interact. Traffic Server has several
 **processors**, such as *cache processor* and *net processor*, that
 consolidate cache or network I/O tasks. Processors talk to the event
@@ -83,7 +83,9 @@ continuation by sending it an event. When a continuation receives an
 event, it wakes up, does some work, and either destroys itself or goes
 back to sleep & waits for the next event.
 
-**Traffic Server Internals** {#TSInternals}
+**Traffic Server Internals**
+
+.. _TSInternals:
 
 .. figure:: /static/images/sdk/event_sys80.jpg
    :alt: Traffic Server Internals
@@ -95,7 +97,9 @@ code plugins (except ``hello-world``) are continuations that are created
 when Traffic Server starts up; they then wait for events that trigger
 them into activity.
 
-**Traffic Server with Plugins** {#TSwithPlugins}
+**Traffic Server with Plugins**
+
+.. _TSwithPlugins:
 
 .. figure:: /static/images/sdk/evt_plugin120.jpg
    :alt: Traffic Server with Plugins
@@ -135,15 +139,13 @@ is handled by an HTTP state machine. These machines follow a complex
 state diagram that includes all of the states required to support
 Traffic Server's features. The Traffic Server API provides hooks to a
 subset of these states, chosen for their relevance to plugins. You can
-view the API hooks and corresponding HTTP states in the `HTTP
-Transaction State
-Diagram <../http-hoooks-and-transactions#HHTTPTransactionStateDiagram>`__.
+view the API hooks and corresponding HTTP states in the
+:ref:`http-txn-state-diagram`.
 
 The example in this section (below) explains how a plugin typically
 intervenes and extends Traffic Server's processing of an HTTP
 transaction. Complete details about hooking on to Traffic Server
-processes are provided in `HTTP Hooks and
-Transactions <HTTPHooksAndTransactions.html>`__.
+processes are provided in :doc:`http-hooks-and-transactions.en`.
 
 HTTP Transaction
 ^^^^^^^^^^^^^^^^
@@ -156,7 +158,9 @@ origin server. The following diagram shows some states in a typical
 transaction - specifically, the scenario wherein content is served from
 cache.
 
-**Simplified HTTP Transaction** {#SimplifiedHTTPTransaction}
+**Simplified HTTP Transaction**
+
+.. _SimplifiedHTTPTransaction:
 
 .. figure:: /static/images/sdk/transact75.jpg
    :alt: Simplified HTTP Transaction
@@ -173,14 +177,16 @@ the cache (a "hit"), then Traffic Server checks it for freshness.
 If the content is fresh, then Traffic Server sends a reply header to the
 client. If the content is stale, then Traffic Server opens a connection
 to the origin server and requests the content. The figure above,
-`Simplified HTTP Transaction <#SimplifiedHTTPTransaction>`__, does *not*
+:ref:`SimplifiedHTTPTransaction`, does *not*
 show behavior in the event of an error. If there is an error at a any
 stage, then the HTTP state machine jumps to the "send reply header"
 state and sends a reply. If the reply is an error, then the transaction
 closes. If the reply is not an error, then Traffic Server first sends
 the response content before it closes the transaction.
 
-**API Hooks Corresponding to States** {#APIHooksCorrespondingtoStates}
+**API Hooks Corresponding to States**
+
+.. _APIHooksCorrespondingtoStates:
 
 .. figure:: /static/images/sdk/transact_hook75.jpg
    :alt: API Hooks Corresponding to States Listed in
@@ -192,10 +198,12 @@ reflects the Traffic Server state that was *just completed*. For
 example, the "OS DNS lookup" hook wakes up a plugin right *after* the
 origin server DNS lookup. For a plugin that requires the IP address of
 the requested origin server, this hook is the right one to use. The
-Blacklist plugin works in this manner, as shown in the `Blacklist
-Plugin <#BlacklistPlugin>`__ diagram below.
+Blacklist plugin works in this manner, as shown in the :ref:`BlackListPlugin`
+diagram below.
+
+**Blacklist Plugin**
 
-**Blacklist Plugin** {#BlacklistPlugin}
+.. _BlackListPlugin:
 
 .. figure:: /static/images/sdk/blacklist75.jpg
    :alt: Blacklist Plugin
@@ -220,9 +228,8 @@ to the "send reply header" state is a **tr**\ ***ansaction hook***,
 meaning that this hook is only invoked for *specified transactions* (in
 the Blacklist example, it's only used for requests to blacklisted
 servers). Several examples of setting up hooks are provided in the code
-example chapters: `Header-Based Plugin
-Examples <../header-based-plugin-examples>`__ and `HTTP Transformation
-Plugins <../http-transformation-plugin>`__
+example chapters: :doc:`header-based-plugin-examples.en` and
+:doc:`http-transformation-plugin.en`
 
 **Header manipulation plugins**, such as filtering, basic authorization,
 or redirects, usually have a global hook to the DNS lookup or the read