You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by am...@apache.org on 2013/07/29 18:39:37 UTC
git commit: Documentation update - fixing warnings and errors.
Updated Branches:
refs/heads/master f651f3cf3 -> 80aa69b33
Documentation update - fixing warnings and errors.
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/80aa69b3
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/80aa69b3
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/80aa69b3
Branch: refs/heads/master
Commit: 80aa69b3324ba4f861e2974b31664ff0e561f24b
Parents: f651f3c
Author: Alan M. Carroll <am...@network-geographics.com>
Authored: Mon Jul 29 11:39:21 2013 -0500
Committer: Alan M. Carroll <am...@network-geographics.com>
Committed: Mon Jul 29 11:39:21 2013 -0500
----------------------------------------------------------------------
doc/admin/getting-started.en.rst | 74 ++++++++++++++---------------------
doc/ext/traffic-server.py | 3 ++
doc/sdk/getting-started.en.rst | 66 +++++++++++++++----------------
3 files changed, 64 insertions(+), 79 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80aa69b3/doc/admin/getting-started.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/getting-started.en.rst b/doc/admin/getting-started.en.rst
index a3e743e..a97c065 100644
--- a/doc/admin/getting-started.en.rst
+++ b/doc/admin/getting-started.en.rst
@@ -3,20 +3,20 @@ Getting Started
.. Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
.. toctree::
@@ -81,55 +81,41 @@ if you're building from a git clone, you'll also need
- autoconf
- automake
-We will show-case a build from git:
+We will show-case a build from git::
-::
-
- git clone https://git-wip-us.apache.org/repos/asf/trafficserver.git
+ git clone https://git-wip-us.apache.org/repos/asf/trafficserver.git
-Next, we ``cd trafficserver`` and run:
-
-::
+Next, we ``cd trafficserver`` and run::
- autoreconf -if
+ autoreconf -if
This will generate a ``configure`` file from ``configure.ac``, so now we
-can run that:
+can run that::
-::
-
- ./configure --prefix=/opt/ats
+ ./configure --prefix=/opt/ats
Note well, that by default Traffic Server uses the user ``nobody``, as
well as user's primary group as Traffic Server user. If you want to
-change that, you can override it here:
-
-::
+change that, you can override it here::
- ./configure --prefix=/opt/ats --with-user=tserver
+ ./configure --prefix=/opt/ats --with-user=tserver
If dependencies are not in standard paths (``/usr/local`` or ``/usr``),
-you need to pass options to ``configure`` to account for that:
-
-::
+you need to pass options to ``configure`` to account for that::
- ./configure --prefix=/opt/ats --with-user=tserver --with-lua=/opt/csw
+ ./configure --prefix=/opt/ats --with-user=tserver --with-lua=/opt/csw
Most ``configure`` path-options accept a format of
-``"INCLUDE_PATH:LIBRARY_PATH"``:
+``"INCLUDE_PATH:LIBRARY_PATH"``::
-::
-
- ./configure --prefix=/opt/ats --with-user=tserver --with-lua=/opt/csw \
- --with-pcre=/opt/csw/include:/opt/csw/lib/amd64
+ ./configure --prefix=/opt/ats --with-user=tserver --with-lua=/opt/csw \
+ --with-pcre=/opt/csw/include:/opt/csw/lib/amd64
We can run ``make`` to build the project. We highly recommend to run
-``make check`` to verify the build's general sanity:
-
-::
+``make check`` to verify the build's general sanity::
- make
- make check
+ make
+ make check
We can finally run ``make install`` to install (you may have to switch
to root to do this):
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80aa69b3/doc/ext/traffic-server.py
----------------------------------------------------------------------
diff --git a/doc/ext/traffic-server.py b/doc/ext/traffic-server.py
index 9105b1e..a99a0cc 100644
--- a/doc/ext/traffic-server.py
+++ b/doc/ext/traffic-server.py
@@ -20,6 +20,9 @@ class TSConfVar(rst.Directive):
Argument is the variable as defined in records.config.
Descriptive text should follow, indented.
+
+ Then the bulk description (if any) undented. This should be considered equivalent to the Doxygen
+ short and long description.
"""
option_spec = {
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80aa69b3/doc/sdk/getting-started.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/getting-started.en.rst b/doc/sdk/getting-started.en.rst
index 81f6e55..aa1535b 100644
--- a/doc/sdk/getting-started.en.rst
+++ b/doc/sdk/getting-started.en.rst
@@ -3,20 +3,20 @@ Getting Started
.. Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
.. toctree::
:maxdepth: 2
@@ -55,13 +55,12 @@ web-related traffic, such as DNS and HTTP requests and responses.
Traffic Server itself consists of an event-driven loop that can be
simplified as follows:
-::
+.. code-block:: c
- :::C
- for (;;) {
- event = get_next_event();
- handle_event (event);
- }
+ for (;;) {
+ event = get_next_event();
+ handle_event (event);
+ }
The Role of Plugins
~~~~~~~~~~~~~~~~~~~
@@ -72,19 +71,21 @@ functions that are registered for specific Traffic Server events. When
Traffic Server needs to process an event, it invokes any and all
call-back functions you've registered for that event type.
-|[Caution]| **Caution**
+.. caution::
-Since plugins add object code to Traffic Server, programming errors in a
-plugin can have serious implications. Bugs in your plugin, such as an
-out-of-range pointer, can cause Traffic Server processes to crash and
-may ultimately result in unpredictable behavior.
+ Since plugins add object code to Traffic Server, programming errors in a
+ plugin can have serious implications. Bugs in your plugin, such as an
+ out-of-range pointer, can cause Traffic Server processes to crash and
+ may ultimately result in unpredictable behavior.
**Plugin Process** {#PluginProcess}
-.. figure:: /images/sdk/plugin_process.jpg
+.. figure:: /static/images/sdk/plugin_process.jpg
+ :align: center
:alt: Plugin Process
Plugin Process
+
Possible Uses for Plugins
~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -125,10 +126,12 @@ Plugins <#possibleTSplugins>`__, illustrates several types of plugins.
**Possible Traffic Server Plugins** {#possibleTSplugins}
-.. figure:: /images/sdk/Uses.jpg
+.. figure:: /static/images/sdk/Uses.jpg
+ :align: center
:alt: Possible Traffic Server Plugins
Possible Traffic Server 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
@@ -161,10 +164,7 @@ The :file:`records.config` file defines the path to each plugin shared
library, as described in `Specify the Plugin's
Location <SpecifyingPluginLocation.html>`__.
-|[Note]| **Note**
-
-The path for each of these files is *``<root_dir>``*\ ``/config/``,
-where *``<root_dir>``* is where you installed Traffic Server.
+.. note:: The path for each of these files is *<root_dir>*\ ``/config/``, where *<root_dir>* is where you installed Traffic Server.
Plugin Configuration
~~~~~~~~~~~~~~~~~~~~
@@ -243,7 +243,3 @@ The ``TSPluginInit`` function has two arguments:
See `TSPluginInit <InitializationFunctions.html#TSPluginInit>`__ for
details about ``TSPluginInit``.
-
-.. |[Caution]| image:: /images/docbook/caution.png
-.. |[Note]| image:: /images/docbook/note.png
-