You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by jp...@apache.org on 2014/01/12 21:14:56 UTC
git commit: Doc: fix broken links and syntax errors
Updated Branches:
refs/heads/master ebb01e5d0 -> 4ced03d3d
Doc: fix broken links and syntax errors
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/4ced03d3
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/4ced03d3
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/4ced03d3
Branch: refs/heads/master
Commit: 4ced03d3de9784ca503d71fa876ffd2aa196c6ee
Parents: ebb01e5
Author: Masakazu Kitajo <m4...@gmail.com>
Authored: Sat Dec 28 01:55:37 2013 +0900
Committer: James Peach <jp...@apache.org>
Committed: Sun Jan 12 12:14:29 2014 -0800
----------------------------------------------------------------------
doc/admin/transparent-proxy.en.rst | 7 ++-
doc/admin/transparent-proxy/bridge.en.rst | 8 +--
.../transparent-proxy/router-inline.en.rst | 5 +-
.../transparent-proxy/wccp-configuration.en.rst | 6 +--
.../configuration/records.config.en.rst | 1 +
doc/sdk/continuations.en.rst | 12 ++---
doc/sdk/getting-started.en.rst | 41 +++++++--------
doc/sdk/getting-started/a-simple-plugin.en.rst | 2 +
...gin-registration-and-version-checking.en.rst | 4 +-
.../blacklist-plugin.en.rst | 11 ++--
.../how-to-create-trafficserver-plugins.en.rst | 45 +++++++++-------
.../roadmap-for-creating-plugins.en.rst | 13 ++---
doc/sdk/http-headers/marshal-buffers.en.rst | 6 +--
doc/sdk/new-protocol-plugins.en.rst | 6 ++-
doc/sdk/preface.en.rst | 2 +-
doc/sdk/preface/how-to-use-this-book.en.rst | 54 ++++++++++----------
doc/sdk/remap-plugin.en.rst | 6 +--
doc/sdk/sample-source-code.en.rst | 2 +-
.../unable-to-load-plugins.en.rst | 4 +-
19 files changed, 119 insertions(+), 116 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/admin/transparent-proxy.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/transparent-proxy.en.rst b/doc/admin/transparent-proxy.en.rst
index 750fdf4..2a2eb5c 100644
--- a/doc/admin/transparent-proxy.en.rst
+++ b/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`
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/admin/transparent-proxy/bridge.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/transparent-proxy/bridge.en.rst b/doc/admin/transparent-proxy/bridge.en.rst
index 266e72c..388a9c8 100644
--- a/doc/admin/transparent-proxy/bridge.en.rst
+++ b/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
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/admin/transparent-proxy/router-inline.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/transparent-proxy/router-inline.en.rst b/doc/admin/transparent-proxy/router-inline.en.rst
index 5e6b64c..f7047b9 100644
--- a/doc/admin/transparent-proxy/router-inline.en.rst
+++ b/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: ``=``
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/admin/transparent-proxy/wccp-configuration.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/transparent-proxy/wccp-configuration.en.rst b/doc/admin/transparent-proxy/wccp-configuration.en.rst
index 4ed7598..5a9a41c 100644
--- a/doc/admin/transparent-proxy/wccp-configuration.en.rst
+++ b/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.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/reference/configuration/records.config.en.rst
----------------------------------------------------------------------
diff --git a/doc/reference/configuration/records.config.en.rst b/doc/reference/configuration/records.config.en.rst
index 1eef625..f0d7f8a 100644
--- a/doc/reference/configuration/records.config.en.rst
+++ b/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:
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/continuations.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/continuations.en.rst b/doc/sdk/continuations.en.rst
index df93565..1981fd7 100644
--- a/doc/sdk/continuations.en.rst
+++ b/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
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/getting-started.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/getting-started.en.rst b/doc/sdk/getting-started.en.rst
index a39d0cf..38c14bb 100644
--- a/doc/sdk/getting-started.en.rst
+++ b/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``.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/getting-started/a-simple-plugin.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/getting-started/a-simple-plugin.en.rst b/doc/sdk/getting-started/a-simple-plugin.en.rst
index 31f4733..18d0f78 100644
--- a/doc/sdk/getting-started/a-simple-plugin.en.rst
+++ b/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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/getting-started/plugin-registration-and-version-checking.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/getting-started/plugin-registration-and-version-checking.en.rst b/doc/sdk/getting-started/plugin-registration-and-version-checking.en.rst
index b7171c7..7b403b8 100644
--- a/doc/sdk/getting-started/plugin-registration-and-version-checking.en.rst
+++ b/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.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/header-based-plugin-examples/blacklist-plugin.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/header-based-plugin-examples/blacklist-plugin.en.rst b/doc/sdk/header-based-plugin-examples/blacklist-plugin.en.rst
index 91c782d..85048e9 100644
--- a/doc/sdk/header-based-plugin-examples/blacklist-plugin.en.rst
+++ b/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
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/how-to-create-trafficserver-plugins.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/how-to-create-trafficserver-plugins.en.rst b/doc/sdk/how-to-create-trafficserver-plugins.en.rst
index 9e7a11c..0c26610 100644
--- a/doc/sdk/how-to-create-trafficserver-plugins.en.rst
+++ b/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
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/how-to-create-trafficserver-plugins/roadmap-for-creating-plugins.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/how-to-create-trafficserver-plugins/roadmap-for-creating-plugins.en.rst b/doc/sdk/how-to-create-trafficserver-plugins/roadmap-for-creating-plugins.en.rst
index c9759e4..7634bfe 100644
--- a/doc/sdk/how-to-create-trafficserver-plugins/roadmap-for-creating-plugins.en.rst
+++ b/doc/sdk/how-to-create-trafficserver-plugins/roadmap-for-creating-plugins.en.rst
@@ -61,21 +61,18 @@ Below are some guidelines for creating a plugin:
These examples are discussed in the next three chapters.
2. Determine where your plugin needs to hook on to Traffic Server's HTTP
- processing (view the `HTTP Transaction State
- Diagram <../http-hoooks-and-transactions#HTTPTransactionStateDiagram>`__
+ processing (view the :ref:`http-txn-state-diagram`
-3. Read `Header-Based Plugin
- Examples <../header-based-plugin-examples>`_ to learn the basics of
+3. Read :doc:`../header-based-plugin-examples.en` to learn the basics of
writing plugins: creating continuations and setting up hooks. If you
- want to write a plugin that transforms data, then read `HTTP
- Transformation Plugins <HTTPTransformationPlugins.html>`_.
+ want to write a plugin that transforms data, then read
+ :doc:`../http-transformation-plugin.en`
4. Figure out what parts of the Traffic Server API you need to use and
then read about the details of those APIs in this manual's reference
chapters.
-5. Compile and load your plugin (see `Getting
- Started <../getting-started>`_
+5. Compile and load your plugin (see :doc:`../getting-started.en`
6. Depending on your plugin's functionality, you might start testing it
by issuing requests by hand and checking for the desired behavior in
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/http-headers/marshal-buffers.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/http-headers/marshal-buffers.en.rst b/doc/sdk/http-headers/marshal-buffers.en.rst
index 28088b7..d3f0664 100644
--- a/doc/sdk/http-headers/marshal-buffers.en.rst
+++ b/doc/sdk/http-headers/marshal-buffers.en.rst
@@ -28,9 +28,9 @@ object (``TSMLoc``) and the marshal buffer containing the object
Routines exist for manipulating the object based on these two pieces of
information. For example, see one of the following:
-- `HTTP Headers <http-headers>`__
-- `URLs <urls>`__
-- `MIME Headers <mime-headers>`__
+- :doc:`http-headers.en`
+- :doc:`urls.en`
+- :doc:`mime-headers.en`
The **marshal buffer functions** enable you to create and destroy
Traffic Server's marshal buffers, which are the data structures that
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/new-protocol-plugins.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/new-protocol-plugins.en.rst b/doc/sdk/new-protocol-plugins.en.rst
index 4ca91e7..195fce8 100644
--- a/doc/sdk/new-protocol-plugins.en.rst
+++ b/doc/sdk/new-protocol-plugins.en.rst
@@ -29,6 +29,8 @@ plugins that support new protocols. It also provides a detailed review
of code for a sample Protocol plugin that supports a very simple
artificial HTTP-like protocol.
+.. _about-the-sample-protocol:
+
About the Sample Protocol
-------------------------
@@ -178,6 +180,8 @@ lookups or cache writes uses ``TSCacheRead``, ``TSCacheWrite``,
Cache Processor and Traffic Server event system. Similarly, any plugin
that does DNS lookups receives events from the Host Database Processor.
+.. _one-way-to-implement-a-transaction-state-machine:
+
One Way to Implement a Transaction State Machine
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -244,7 +248,7 @@ Plugin" <#ImplementTransStMachine>`__.
**How Transaction State Machines are Implemented in the Protocol
Plugin** {#ImplementTransStMachine}
-.. figure:: /images/sdk/txn_sm.jpg
+.. figure:: ../static/images/sdk/txn_sm.jpg
:alt: How Transaction State Machines are Implemented in the Protocol Plugin
How Transaction State Machines are Implemented in the Protocol Plugin
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/preface.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/preface.en.rst b/doc/sdk/preface.en.rst
index 2c18876..c2c6318 100644
--- a/doc/sdk/preface.en.rst
+++ b/doc/sdk/preface.en.rst
@@ -31,7 +31,7 @@ creating plugins. **Plugins** are programs that add services (such as
filtering or content transformation) or entire features (such as new
protocol support) to Traffic Server. If you are new to writing Traffic
Server plugins, then read the first two chapters, :ref:`sdk-getting-started`
-and :ref:`how-to-create-to-create-trafficserver-plugins`, and use the
+and :ref:`how-to-create-trafficserver-plugins`, and use the
remaining chapters as needed. :ref:`header-based-plugin-examples` provides details about
plugins that work on HTTP headers, while :ref:`http-transformation-plugin` explains how to write a
plugin that transforms or scans the body of an HTTP response. If you
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/preface/how-to-use-this-book.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/preface/how-to-use-this-book.en.rst b/doc/sdk/preface/how-to-use-this-book.en.rst
index 764e4ea..6c437fd 100644
--- a/doc/sdk/preface/how-to-use-this-book.en.rst
+++ b/doc/sdk/preface/how-to-use-this-book.en.rst
@@ -29,16 +29,14 @@ This book has the following basic components:
- Reference material
-If you're new to writing Traffic Server plugins, then read `Getting
-Started <../getting-started>`_ and `Creating Traffic Server
-Plugins <../how-to-create-trafficserver-plugins>`_, and use the
-remaining chapters as needed. `Header-Based Plugin
-Examples <../header-based-plugin-examples>`_ provides details about
-plugins that work on HTTP headers, while `HTTP Transformation
-Plugins <../http-transformation-plugin>`_ explains how to write a
-plugin that transforms or scans the body of an HTTP response. `New
-Protocol Plugins <../new-protocol-plugins>`_ provides essential
-information if you want to support your own protocol on Traffic Server.
+If you're new to writing Traffic Server plugins, then read
+:doc:`../getting-started.en` and :doc:`../how-to-create-trafficserver-plugins.en`,
+and use the remaining chapters as needed. :doc:`../header-based-plugin-examples.en`
+provides details about plugins that work on HTTP headers, while
+:doc:`../http-transformation-plugin.en` explains how to write a plugin that
+transforms or scans the body of an HTTP response. :doc:`../new-protocol-plugins.en`
+provides essential information if you want to support your own protocol on
+Traffic Server.
You can look up information in the following reference sections:
@@ -48,36 +46,36 @@ You can look up information in the following reference sections:
Doxygen reference
- `Type
Index <http://ci.apache.org/projects/trafficserver/trunk/doxygen/classes.html>`_
-- `Sample Source Code <../sample-source-code>`_
+- :doc:`Sample Source Code <../sample-source-code.en>`
- `Deprecated
Functions <http://ci.apache.org/projects/trafficserver/trunk/doxygen/deprecated.html>`_
Below is a section-by-section breakdown of this guide:
-- `Getting Started <../getting-started>`_
+- :doc:`Getting Started <../getting-started.en>`
How to compile and load plugins. Walks through a simple "hello
world" example; explains how to initialize and register plugins.
-- `How to Create Traffic Server
- Plugins <../how-to-create-trafficserver-plugins>`_
+- :doc:`How to Create Traffic Server
+ Plugins <../how-to-create-trafficserver-plugins.en>`
Basic structures that all plugins use: events, continuations, and
how to hook on to Traffic Server processes. Detailed explication of a
sample blacklisting plugin.
-- `Remap Plugin <../remap-plugin>`_
+- :doc:`Remap Plugin <../remap-plugin.en>`
This chapter demonstrates on a practical example how you can
exploit the Traffic Server remap API for your plugins.
-- `Header-Based Plugin Examples <../header-based-plugin-examples>`_
+- :doc:`Header-Based Plugin Examples <../header-based-plugin-examples.en>`
Detailed explanation about writing plugins that work on HTTP
headers; discusses sample blacklisting and basic authorization
plugins.
-- `HTTP Transformation Plugins <../http-transformation-plugin>`_
+- :doc:`HTTP Transformation Plugins <../http-transformation-plugin.en>`
Detailed explanation of the null-transform example; also discusses
``VConnections``, ``VIOs``, and IO buffers.
-- `New Protocol Plugins <../new-protocol-plugins>`_
+- :doc:`New Protocol Plugins <../new-protocol-plugins.en>`
Detailed explanation of a sample protocol plugin that supports a
synthetic protocol. Discusses ``VConnections`` and mutexes, as well
as the new ``NetConnection``, DNS lookup, logging, and cache APIs.
@@ -85,44 +83,44 @@ Below is a section-by-section breakdown of this guide:
The remaining sections comprise the API function reference and are
organized by function type:
-- `Miscellaneous Interface Guide <../misc-interface-guide>`_
+- :doc:`Miscellaneous Interface Guide <../misc-interface-guide.en>`
Details error-writing and tracing functions, thread functions, and
Traffic Server API versions of the ``malloc`` and ``fopen`` families.
The Traffic Server API versions overcome various C library
limitations.
-- `HTTP Hooks and Transactions <../http-hoooks-and-transactions>`_
+- :doc:`HTTP Hooks and Transactions <../http-hooks-and-transactions.en>`
Functions in this chapter hook your plugin to Traffic Server HTTP
processes.
-- `HTTP Headers <../http-headers>`_
+- :doc:`HTTP Headers <../http-headers.en>`
Contains instructions for implementing performance enhancements for
all plugins that manipulate HTTP headers. These functions examine and
modify HTTP headers, MIME headers, URLs, and the marshal buffers that
contain header information. If you are working with headers, then be
sure to read this chapter.
-- `Mutex Guide <../mutex-guide>`_
+- :doc:`Mutex Guide <../mutex-guide.en>`
-- `Continuations <../continuations>`_
+- :doc:`Continuations <../continuations.en>`
Continuations provide the basic callback mechanism and data
abstractions used in Traffic Server.
-- `Plugin Configurations <../plugin-configurations>`_
+- :doc:`Plugin Configurations <../plugin-configurations.en>`
-- `Actions Guide <../actions-guide>`_
+- :doc:`Actions Guide <../actions-guide.en>`
Describes how to use ``TSActions`` and the ``TSDNSLookup`` API.
-- `IO Guide <../io-guide>`_
+- :doc:`IO Guide <../io-guide.en>`
Describes how to use the Traffic Server IO interfaces:
``TSVConnection``, ``TSVIO``, ``TSIOBuffer``, ``TSNetVConnection``,
the Cache API.
-- `Plugin Management <../plugin-management>`_
+- :doc:`Plugin Management <../plugin-management.en>`
These functions enable you to set up a configuration interface for
plugins, access installed plugin files, and set up plugin licensing.
-- `Adding Statistics <../adding-statistics>`_
+- :doc:`Adding Statistics <../adding-statistics.en>`
These functions add statistics to your plugin.
- `Function
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/remap-plugin.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/remap-plugin.en.rst b/doc/sdk/remap-plugin.en.rst
index 6506653..9a22cc3 100644
--- a/doc/sdk/remap-plugin.en.rst
+++ b/doc/sdk/remap-plugin.en.rst
@@ -54,16 +54,16 @@ Required Functions
A remap plugin is required to implement the following functions:
-- ```TSRemapInit`` <http://people.apache.org/~amc/ats/doc/html/remap_8h.html#af7e9b1eee1c38c6f8dcc67a65ba02c24>`__:
+- `TSRemapInit <http://people.apache.org/~amc/ats/doc/html/remap_8h.html#af7e9b1eee1c38c6f8dcc67a65ba02c24>`_:
the remap initialization function, called once when the plugin is
loaded
-- ```TSRemapNewInstance`` <http://people.apache.org/~amc/ats/doc/html/remap_8h.html#a963de3eeed2ed7a2da483acf77dc42ca>`__:
+- `TSRemapNewInstance <http://people.apache.org/~amc/ats/doc/html/remap_8h.html#a963de3eeed2ed7a2da483acf77dc42ca>`_:
a new instance is created for each rule associated with the plugin.
Called each time the plugin used in a remap rule (this function is
what processes the pparam values)
-- ```TSRemapDoRemap`` <http://people.apache.org/~amc/ats/doc/html/remap_8h.html#acf73f0355c591e145398211b3c0596fe>`__:
+- `TSRemapDoRemap <http://people.apache.org/~amc/ats/doc/html/remap_8h.html#acf73f0355c591e145398211b3c0596fe>`_:
the entry point used by Traffic Server to find the new URL to which
it remaps; called every time a request comes in
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/sample-source-code.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/sample-source-code.en.rst b/doc/sdk/sample-source-code.en.rst
index 42be2a9..3568f41 100644
--- a/doc/sdk/sample-source-code.en.rst
+++ b/doc/sdk/sample-source-code.en.rst
@@ -22,7 +22,7 @@ This appendix provides several source code examples. In the online
formats of this book, function calls are linked to their references in
the previous chapters. The following sample plugins are provided:
-- `blacklist-1.c <App_SampleSourceCode.html#Sample_blacklist-1.c>`__
+- `blacklist-1.c`_
blacklist-1.c
-------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/troubleshooting-tips/unable-to-load-plugins.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/troubleshooting-tips/unable-to-load-plugins.en.rst b/doc/sdk/troubleshooting-tips/unable-to-load-plugins.en.rst
index 606c144..0d8f7f3 100644
--- a/doc/sdk/troubleshooting-tips/unable-to-load-plugins.en.rst
+++ b/doc/sdk/troubleshooting-tips/unable-to-load-plugins.en.rst
@@ -32,5 +32,5 @@ To load plugins, follow the steps below.
5. Restart Traffic Server.
-For detailed information about each step above, refer to `A Simple
-Plugin <../getting-started/a-simple-plugin>`__.
+For detailed information about each step above, refer to
+:doc:`../getting-started/a-simple-plugin.en`.
Re: git commit: Doc: fix broken links and syntax errors
Posted by Igor Galić <i....@brainsware.org>.
Kudos!
Thanks a lot for that!
----- Original Message -----
> Updated Branches:
> refs/heads/master ebb01e5d0 -> 4ced03d3d
>
>
> Doc: fix broken links and syntax errors
>
>
> Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
> Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/4ced03d3
> Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/4ced03d3
> Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/4ced03d3
>
> Branch: refs/heads/master
> Commit: 4ced03d3de9784ca503d71fa876ffd2aa196c6ee
> Parents: ebb01e5
> Author: Masakazu Kitajo <m4...@gmail.com>
> Authored: Sat Dec 28 01:55:37 2013 +0900
> Committer: James Peach <jp...@apache.org>
> Committed: Sun Jan 12 12:14:29 2014 -0800
>
> ----------------------------------------------------------------------
> doc/admin/transparent-proxy.en.rst | 7 ++-
> doc/admin/transparent-proxy/bridge.en.rst | 8 +--
> .../transparent-proxy/router-inline.en.rst | 5 +-
> .../transparent-proxy/wccp-configuration.en.rst | 6 +--
> .../configuration/records.config.en.rst | 1 +
> doc/sdk/continuations.en.rst | 12 ++---
> doc/sdk/getting-started.en.rst | 41 +++++++--------
> doc/sdk/getting-started/a-simple-plugin.en.rst | 2 +
> ...gin-registration-and-version-checking.en.rst | 4 +-
> .../blacklist-plugin.en.rst | 11 ++--
> .../how-to-create-trafficserver-plugins.en.rst | 45 +++++++++-------
> .../roadmap-for-creating-plugins.en.rst | 13 ++---
> doc/sdk/http-headers/marshal-buffers.en.rst | 6 +--
> doc/sdk/new-protocol-plugins.en.rst | 6 ++-
> doc/sdk/preface.en.rst | 2 +-
> doc/sdk/preface/how-to-use-this-book.en.rst | 54 ++++++++++----------
> doc/sdk/remap-plugin.en.rst | 6 +--
> doc/sdk/sample-source-code.en.rst | 2 +-
> .../unable-to-load-plugins.en.rst | 4 +-
> 19 files changed, 119 insertions(+), 116 deletions(-)
> ----------------------------------------------------------------------
>
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/admin/transparent-proxy.en.rst
> ----------------------------------------------------------------------
> diff --git a/doc/admin/transparent-proxy.en.rst
> b/doc/admin/transparent-proxy.en.rst
> index 750fdf4..2a2eb5c 100644
> --- a/doc/admin/transparent-proxy.en.rst
> +++ b/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`
>
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/admin/transparent-proxy/bridge.en.rst
> ----------------------------------------------------------------------
> diff --git a/doc/admin/transparent-proxy/bridge.en.rst
> b/doc/admin/transparent-proxy/bridge.en.rst
> index 266e72c..388a9c8 100644
> --- a/doc/admin/transparent-proxy/bridge.en.rst
> +++ b/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
>
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/admin/transparent-proxy/router-inline.en.rst
> ----------------------------------------------------------------------
> diff --git a/doc/admin/transparent-proxy/router-inline.en.rst
> b/doc/admin/transparent-proxy/router-inline.en.rst
> index 5e6b64c..f7047b9 100644
> --- a/doc/admin/transparent-proxy/router-inline.en.rst
> +++ b/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: ``=``
>
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/admin/transparent-proxy/wccp-configuration.en.rst
> ----------------------------------------------------------------------
> diff --git a/doc/admin/transparent-proxy/wccp-configuration.en.rst
> b/doc/admin/transparent-proxy/wccp-configuration.en.rst
> index 4ed7598..5a9a41c 100644
> --- a/doc/admin/transparent-proxy/wccp-configuration.en.rst
> +++ b/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.
>
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/reference/configuration/records.config.en.rst
> ----------------------------------------------------------------------
> diff --git a/doc/reference/configuration/records.config.en.rst
> b/doc/reference/configuration/records.config.en.rst
> index 1eef625..f0d7f8a 100644
> --- a/doc/reference/configuration/records.config.en.rst
> +++ b/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:
>
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/continuations.en.rst
> ----------------------------------------------------------------------
> diff --git a/doc/sdk/continuations.en.rst b/doc/sdk/continuations.en.rst
> index df93565..1981fd7 100644
> --- a/doc/sdk/continuations.en.rst
> +++ b/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
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/getting-started.en.rst
> ----------------------------------------------------------------------
> diff --git a/doc/sdk/getting-started.en.rst b/doc/sdk/getting-started.en.rst
> index a39d0cf..38c14bb 100644
> --- a/doc/sdk/getting-started.en.rst
> +++ b/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``.
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/getting-started/a-simple-plugin.en.rst
> ----------------------------------------------------------------------
> diff --git a/doc/sdk/getting-started/a-simple-plugin.en.rst
> b/doc/sdk/getting-started/a-simple-plugin.en.rst
> index 31f4733..18d0f78 100644
> --- a/doc/sdk/getting-started/a-simple-plugin.en.rst
> +++ b/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
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/getting-started/plugin-registration-and-version-checking.en.rst
> ----------------------------------------------------------------------
> diff --git
> a/doc/sdk/getting-started/plugin-registration-and-version-checking.en.rst
> b/doc/sdk/getting-started/plugin-registration-and-version-checking.en.rst
> index b7171c7..7b403b8 100644
> --- a/doc/sdk/getting-started/plugin-registration-and-version-checking.en.rst
> +++ b/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.
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/header-based-plugin-examples/blacklist-plugin.en.rst
> ----------------------------------------------------------------------
> diff --git a/doc/sdk/header-based-plugin-examples/blacklist-plugin.en.rst
> b/doc/sdk/header-based-plugin-examples/blacklist-plugin.en.rst
> index 91c782d..85048e9 100644
> --- a/doc/sdk/header-based-plugin-examples/blacklist-plugin.en.rst
> +++ b/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
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/how-to-create-trafficserver-plugins.en.rst
> ----------------------------------------------------------------------
> diff --git a/doc/sdk/how-to-create-trafficserver-plugins.en.rst
> b/doc/sdk/how-to-create-trafficserver-plugins.en.rst
> index 9e7a11c..0c26610 100644
> --- a/doc/sdk/how-to-create-trafficserver-plugins.en.rst
> +++ b/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
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/how-to-create-trafficserver-plugins/roadmap-for-creating-plugins.en.rst
> ----------------------------------------------------------------------
> diff --git
> a/doc/sdk/how-to-create-trafficserver-plugins/roadmap-for-creating-plugins.en.rst
> b/doc/sdk/how-to-create-trafficserver-plugins/roadmap-for-creating-plugins.en.rst
> index c9759e4..7634bfe 100644
> ---
> a/doc/sdk/how-to-create-trafficserver-plugins/roadmap-for-creating-plugins.en.rst
> +++
> b/doc/sdk/how-to-create-trafficserver-plugins/roadmap-for-creating-plugins.en.rst
> @@ -61,21 +61,18 @@ Below are some guidelines for creating a plugin:
> These examples are discussed in the next three chapters.
>
> 2. Determine where your plugin needs to hook on to Traffic Server's HTTP
> - processing (view the `HTTP Transaction State
> - Diagram <../http-hoooks-and-transactions#HTTPTransactionStateDiagram>`__
> + processing (view the :ref:`http-txn-state-diagram`
>
> -3. Read `Header-Based Plugin
> - Examples <../header-based-plugin-examples>`_ to learn the basics of
> +3. Read :doc:`../header-based-plugin-examples.en` to learn the basics of
> writing plugins: creating continuations and setting up hooks. If you
> - want to write a plugin that transforms data, then read `HTTP
> - Transformation Plugins <HTTPTransformationPlugins.html>`_.
> + want to write a plugin that transforms data, then read
> + :doc:`../http-transformation-plugin.en`
>
> 4. Figure out what parts of the Traffic Server API you need to use and
> then read about the details of those APIs in this manual's reference
> chapters.
>
> -5. Compile and load your plugin (see `Getting
> - Started <../getting-started>`_
> +5. Compile and load your plugin (see :doc:`../getting-started.en`
>
> 6. Depending on your plugin's functionality, you might start testing it
> by issuing requests by hand and checking for the desired behavior in
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/http-headers/marshal-buffers.en.rst
> ----------------------------------------------------------------------
> diff --git a/doc/sdk/http-headers/marshal-buffers.en.rst
> b/doc/sdk/http-headers/marshal-buffers.en.rst
> index 28088b7..d3f0664 100644
> --- a/doc/sdk/http-headers/marshal-buffers.en.rst
> +++ b/doc/sdk/http-headers/marshal-buffers.en.rst
> @@ -28,9 +28,9 @@ object (``TSMLoc``) and the marshal buffer containing the
> object
> Routines exist for manipulating the object based on these two pieces of
> information. For example, see one of the following:
>
> -- `HTTP Headers <http-headers>`__
> -- `URLs <urls>`__
> -- `MIME Headers <mime-headers>`__
> +- :doc:`http-headers.en`
> +- :doc:`urls.en`
> +- :doc:`mime-headers.en`
>
> The **marshal buffer functions** enable you to create and destroy
> Traffic Server's marshal buffers, which are the data structures that
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/new-protocol-plugins.en.rst
> ----------------------------------------------------------------------
> diff --git a/doc/sdk/new-protocol-plugins.en.rst
> b/doc/sdk/new-protocol-plugins.en.rst
> index 4ca91e7..195fce8 100644
> --- a/doc/sdk/new-protocol-plugins.en.rst
> +++ b/doc/sdk/new-protocol-plugins.en.rst
> @@ -29,6 +29,8 @@ plugins that support new protocols. It also provides a
> detailed review
> of code for a sample Protocol plugin that supports a very simple
> artificial HTTP-like protocol.
>
> +.. _about-the-sample-protocol:
> +
> About the Sample Protocol
> -------------------------
>
> @@ -178,6 +180,8 @@ lookups or cache writes uses ``TSCacheRead``,
> ``TSCacheWrite``,
> Cache Processor and Traffic Server event system. Similarly, any plugin
> that does DNS lookups receives events from the Host Database Processor.
>
> +.. _one-way-to-implement-a-transaction-state-machine:
> +
> One Way to Implement a Transaction State Machine
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> @@ -244,7 +248,7 @@ Plugin" <#ImplementTransStMachine>`__.
> **How Transaction State Machines are Implemented in the Protocol
> Plugin** {#ImplementTransStMachine}
>
> -.. figure:: /images/sdk/txn_sm.jpg
> +.. figure:: ../static/images/sdk/txn_sm.jpg
> :alt: How Transaction State Machines are Implemented in the Protocol
> Plugin
>
> How Transaction State Machines are Implemented in the Protocol Plugin
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/preface.en.rst
> ----------------------------------------------------------------------
> diff --git a/doc/sdk/preface.en.rst b/doc/sdk/preface.en.rst
> index 2c18876..c2c6318 100644
> --- a/doc/sdk/preface.en.rst
> +++ b/doc/sdk/preface.en.rst
> @@ -31,7 +31,7 @@ creating plugins. **Plugins** are programs that add
> services (such as
> filtering or content transformation) or entire features (such as new
> protocol support) to Traffic Server. If you are new to writing Traffic
> Server plugins, then read the first two chapters, :ref:`sdk-getting-started`
> -and :ref:`how-to-create-to-create-trafficserver-plugins`, and use the
> +and :ref:`how-to-create-trafficserver-plugins`, and use the
> remaining chapters as needed. :ref:`header-based-plugin-examples` provides
> details about
> plugins that work on HTTP headers, while :ref:`http-transformation-plugin`
> explains how to write a
> plugin that transforms or scans the body of an HTTP response. If you
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/preface/how-to-use-this-book.en.rst
> ----------------------------------------------------------------------
> diff --git a/doc/sdk/preface/how-to-use-this-book.en.rst
> b/doc/sdk/preface/how-to-use-this-book.en.rst
> index 764e4ea..6c437fd 100644
> --- a/doc/sdk/preface/how-to-use-this-book.en.rst
> +++ b/doc/sdk/preface/how-to-use-this-book.en.rst
> @@ -29,16 +29,14 @@ This book has the following basic components:
>
> - Reference material
>
> -If you're new to writing Traffic Server plugins, then read `Getting
> -Started <../getting-started>`_ and `Creating Traffic Server
> -Plugins <../how-to-create-trafficserver-plugins>`_, and use the
> -remaining chapters as needed. `Header-Based Plugin
> -Examples <../header-based-plugin-examples>`_ provides details about
> -plugins that work on HTTP headers, while `HTTP Transformation
> -Plugins <../http-transformation-plugin>`_ explains how to write a
> -plugin that transforms or scans the body of an HTTP response. `New
> -Protocol Plugins <../new-protocol-plugins>`_ provides essential
> -information if you want to support your own protocol on Traffic Server.
> +If you're new to writing Traffic Server plugins, then read
> +:doc:`../getting-started.en` and
> :doc:`../how-to-create-trafficserver-plugins.en`,
> +and use the remaining chapters as needed.
> :doc:`../header-based-plugin-examples.en`
> +provides details about plugins that work on HTTP headers, while
> +:doc:`../http-transformation-plugin.en` explains how to write a plugin that
> +transforms or scans the body of an HTTP response.
> :doc:`../new-protocol-plugins.en`
> +provides essential information if you want to support your own protocol on
> +Traffic Server.
>
> You can look up information in the following reference sections:
>
> @@ -48,36 +46,36 @@ You can look up information in the following reference
> sections:
> Doxygen reference
> - `Type
> Index
> <http://ci.apache.org/projects/trafficserver/trunk/doxygen/classes.html>`_
> -- `Sample Source Code <../sample-source-code>`_
> +- :doc:`Sample Source Code <../sample-source-code.en>`
> - `Deprecated
> Functions
> <http://ci.apache.org/projects/trafficserver/trunk/doxygen/deprecated.html>`_
>
> Below is a section-by-section breakdown of this guide:
>
> -- `Getting Started <../getting-started>`_
> +- :doc:`Getting Started <../getting-started.en>`
> How to compile and load plugins. Walks through a simple "hello
> world" example; explains how to initialize and register plugins.
>
> -- `How to Create Traffic Server
> - Plugins <../how-to-create-trafficserver-plugins>`_
> +- :doc:`How to Create Traffic Server
> + Plugins <../how-to-create-trafficserver-plugins.en>`
> Basic structures that all plugins use: events, continuations, and
> how to hook on to Traffic Server processes. Detailed explication of a
> sample blacklisting plugin.
>
> -- `Remap Plugin <../remap-plugin>`_
> +- :doc:`Remap Plugin <../remap-plugin.en>`
> This chapter demonstrates on a practical example how you can
> exploit the Traffic Server remap API for your plugins.
>
> -- `Header-Based Plugin Examples <../header-based-plugin-examples>`_
> +- :doc:`Header-Based Plugin Examples <../header-based-plugin-examples.en>`
> Detailed explanation about writing plugins that work on HTTP
> headers; discusses sample blacklisting and basic authorization
> plugins.
>
> -- `HTTP Transformation Plugins <../http-transformation-plugin>`_
> +- :doc:`HTTP Transformation Plugins <../http-transformation-plugin.en>`
> Detailed explanation of the null-transform example; also discusses
> ``VConnections``, ``VIOs``, and IO buffers.
>
> -- `New Protocol Plugins <../new-protocol-plugins>`_
> +- :doc:`New Protocol Plugins <../new-protocol-plugins.en>`
> Detailed explanation of a sample protocol plugin that supports a
> synthetic protocol. Discusses ``VConnections`` and mutexes, as well
> as the new ``NetConnection``, DNS lookup, logging, and cache APIs.
> @@ -85,44 +83,44 @@ Below is a section-by-section breakdown of this guide:
> The remaining sections comprise the API function reference and are
> organized by function type:
>
> -- `Miscellaneous Interface Guide <../misc-interface-guide>`_
> +- :doc:`Miscellaneous Interface Guide <../misc-interface-guide.en>`
> Details error-writing and tracing functions, thread functions, and
> Traffic Server API versions of the ``malloc`` and ``fopen`` families.
> The Traffic Server API versions overcome various C library
> limitations.
>
> -- `HTTP Hooks and Transactions <../http-hoooks-and-transactions>`_
> +- :doc:`HTTP Hooks and Transactions <../http-hooks-and-transactions.en>`
> Functions in this chapter hook your plugin to Traffic Server HTTP
> processes.
>
> -- `HTTP Headers <../http-headers>`_
> +- :doc:`HTTP Headers <../http-headers.en>`
> Contains instructions for implementing performance enhancements for
> all plugins that manipulate HTTP headers. These functions examine and
> modify HTTP headers, MIME headers, URLs, and the marshal buffers that
> contain header information. If you are working with headers, then be
> sure to read this chapter.
>
> -- `Mutex Guide <../mutex-guide>`_
> +- :doc:`Mutex Guide <../mutex-guide.en>`
>
> -- `Continuations <../continuations>`_
> +- :doc:`Continuations <../continuations.en>`
> Continuations provide the basic callback mechanism and data
> abstractions used in Traffic Server.
>
> -- `Plugin Configurations <../plugin-configurations>`_
> +- :doc:`Plugin Configurations <../plugin-configurations.en>`
>
> -- `Actions Guide <../actions-guide>`_
> +- :doc:`Actions Guide <../actions-guide.en>`
> Describes how to use ``TSActions`` and the ``TSDNSLookup`` API.
>
> -- `IO Guide <../io-guide>`_
> +- :doc:`IO Guide <../io-guide.en>`
> Describes how to use the Traffic Server IO interfaces:
> ``TSVConnection``, ``TSVIO``, ``TSIOBuffer``, ``TSNetVConnection``,
> the Cache API.
>
> -- `Plugin Management <../plugin-management>`_
> +- :doc:`Plugin Management <../plugin-management.en>`
> These functions enable you to set up a configuration interface for
> plugins, access installed plugin files, and set up plugin licensing.
>
> -- `Adding Statistics <../adding-statistics>`_
> +- :doc:`Adding Statistics <../adding-statistics.en>`
> These functions add statistics to your plugin.
>
> - `Function
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/remap-plugin.en.rst
> ----------------------------------------------------------------------
> diff --git a/doc/sdk/remap-plugin.en.rst b/doc/sdk/remap-plugin.en.rst
> index 6506653..9a22cc3 100644
> --- a/doc/sdk/remap-plugin.en.rst
> +++ b/doc/sdk/remap-plugin.en.rst
> @@ -54,16 +54,16 @@ Required Functions
>
> A remap plugin is required to implement the following functions:
>
> -- ```TSRemapInit``
> <http://people.apache.org/~amc/ats/doc/html/remap_8h.html#af7e9b1eee1c38c6f8dcc67a65ba02c24>`__:
> +- `TSRemapInit
> <http://people.apache.org/~amc/ats/doc/html/remap_8h.html#af7e9b1eee1c38c6f8dcc67a65ba02c24>`_:
> the remap initialization function, called once when the plugin is
> loaded
>
> -- ```TSRemapNewInstance``
> <http://people.apache.org/~amc/ats/doc/html/remap_8h.html#a963de3eeed2ed7a2da483acf77dc42ca>`__:
> +- `TSRemapNewInstance
> <http://people.apache.org/~amc/ats/doc/html/remap_8h.html#a963de3eeed2ed7a2da483acf77dc42ca>`_:
> a new instance is created for each rule associated with the plugin.
> Called each time the plugin used in a remap rule (this function is
> what processes the pparam values)
>
> -- ```TSRemapDoRemap``
> <http://people.apache.org/~amc/ats/doc/html/remap_8h.html#acf73f0355c591e145398211b3c0596fe>`__:
> +- `TSRemapDoRemap
> <http://people.apache.org/~amc/ats/doc/html/remap_8h.html#acf73f0355c591e145398211b3c0596fe>`_:
> the entry point used by Traffic Server to find the new URL to which
> it remaps; called every time a request comes in
>
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/sample-source-code.en.rst
> ----------------------------------------------------------------------
> diff --git a/doc/sdk/sample-source-code.en.rst
> b/doc/sdk/sample-source-code.en.rst
> index 42be2a9..3568f41 100644
> --- a/doc/sdk/sample-source-code.en.rst
> +++ b/doc/sdk/sample-source-code.en.rst
> @@ -22,7 +22,7 @@ This appendix provides several source code examples. In the
> online
> formats of this book, function calls are linked to their references in
> the previous chapters. The following sample plugins are provided:
>
> -- `blacklist-1.c <App_SampleSourceCode.html#Sample_blacklist-1.c>`__
> +- `blacklist-1.c`_
>
> blacklist-1.c
> -------------
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ced03d3/doc/sdk/troubleshooting-tips/unable-to-load-plugins.en.rst
> ----------------------------------------------------------------------
> diff --git a/doc/sdk/troubleshooting-tips/unable-to-load-plugins.en.rst
> b/doc/sdk/troubleshooting-tips/unable-to-load-plugins.en.rst
> index 606c144..0d8f7f3 100644
> --- a/doc/sdk/troubleshooting-tips/unable-to-load-plugins.en.rst
> +++ b/doc/sdk/troubleshooting-tips/unable-to-load-plugins.en.rst
> @@ -32,5 +32,5 @@ To load plugins, follow the steps below.
>
> 5. Restart Traffic Server.
>
> -For detailed information about each step above, refer to `A Simple
> -Plugin <../getting-started/a-simple-plugin>`__.
> +For detailed information about each step above, refer to
> +:doc:`../getting-started/a-simple-plugin.en`.
>
>
>
--
Igor Galić
Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/
GPG: 8716 7A9F 989B ABD5 100F 4008 F266 55D6 2998 1641