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 <m4s...@gmail.com> > Authored: Sat Dec 28 01:55:37 2013 +0900 > Committer: James Peach <jpe...@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.ga...@brainsware.org URL: http://brainsware.org/ GPG: 8716 7A9F 989B ABD5 100F 4008 F266 55D6 2998 1641
