You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@trafficserver.apache.org by Igor Galić <i....@brainsware.org> on 2014/01/13 22:35:14 UTC
Re: git commit: Doc: fix broken links and syntax errors
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