--- a/doc/examples/index.rst	Fri Dec 25 06:56:27 2009 -0800
+++ b/doc/examples/index.rst	Thu Dec 31 11:28:49 2009 -0800
@@ -44,4 +44,12 @@
     cohomology
 
 A simple example of computing persistence of a lower-star filtration is in
-:sfile:`examples/lsfiltration.py`.    
+:sfile:`examples/lsfiltration.py`.
+
+A C++-only, but useful example is computation of a vineyard of piecewise
+straight-line homotopy of piecewise-linear functions.
+
+.. toctree::
+    :maxdepth: 1
+
+    pl-vineyard

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/examples/pl-vineyard.rst	Thu Dec 31 11:28:49 2009 -0800
@@ -0,0 +1,72 @@
+.. _pl-vineyard:
+
+Piecewise-Linear Vineyard
+=========================
+
+Given a simplicial complex :math:`K`, and a sequence of values on each one of
+its vertices, one may construct a homotopy of PL functions on the complex that
+interpolates linearly between the values. For any given time in the homotopy, we
+get a function from the simplicial complex to the real line, and we can compute
+its persistence diagram. Stacking all such diagrams together we get a
+persistence vineyard [CEM06]_. An example that computes such a vineyard is in 
+:sfile:`examples/pl-functions/pl-vineyard.cpp`. 
+
+.. program:: pl-vineyard
+
+Once compiled, it takes three files as the input::
+    
+    pl-vineyard complex values output-prefix
+
+``complex`` lists the simplices of the simplicial complex :math:`K`, one
+per-line::
+
+    0
+    1
+    0 1
+    2
+    0 2
+    ...
+
+``values`` lists the vertex values of the consequtive "frames" of the homotopy.
+Each line is a sequence of as many numbers as there are vertices in the complex.
+It describes a single frame. :program:`pl-vineayrd` constructs the homotopy over
+the interval :math:`[0,k-1]`, where :math:`k` is the number of frames. As an
+example of ``values`` input::
+
+    3.3   6    2
+    1.2   3    10
+    7.5   2.1  0
+
+This input means: :math:`f_0(0) = 3.3, f_1(0) = 1.2, f_2(0) = 7.5`. Similarly, 
+:math:`f_0(1) = 6, f_1(1) = 3, f_2(1) = 2.1`; 
+:math:`f_0(2) = 2, f_1(2) = 10, f_2(2) = 0`.
+
+The vineyard is saved to the files prefixed with ``output-prefix``, followed by
+the dimension and extension, e.g. ``myfunction1.vin`` or ``myfunction1.edg``,
+depending on the format. The two formats are vines and edges. The former saves
+one vine per line, listed as a stream of triplets BIRTH DEATH TIME::
+
+    4 5 0 3.4 5.6 0.4 3 6 1 ...
+
+The edge format represents the vine as a sequence of edges, each given as a
+start and end point. So the above vine would appear as::
+
+    4 5 0
+    3.4 5.6 0.4
+    3.4 5.6 0.4
+    3 6 1
+    ...
+
+:program:`pl-vineyard` takes additional options:
+
+.. cmdoption:: -s, --skip-infinite
+
+    Do not output infinite vines.
+
+.. cmdoption:: -v, --save-vines
+
+    Output vines, instead of the default edge format.
+
+.. cmdoption:: -e, --explicit-events
+
+    Go through the events one by one (useful for the debugging).

--- a/doc/get-build-install.rst	Fri Dec 25 06:56:27 2009 -0800
+++ b/doc/get-build-install.rst	Thu Dec 31 11:28:49 2009 -0800
@@ -52,7 +52,7 @@
 
 Optional dependencies:
 
-  :CGAL_:               for alpha shapes    (version :math:`\geq` 3.4)
+  :CGAL_:               for alpha shapes and vineyards   (version :math:`\geq` 3.4)
   :CVXOPT_:             for :ref:`circle-valued parametrization <cohomology-parametrization>` using LSQR
   :PyX_:                :sfile:`tools/draw-diagram/draw.py` uses `PyX`_ to
                         produce a PDF of the diagram

--- a/doc/index.rst	Fri Dec 25 06:56:27 2009 -0800
+++ b/doc/index.rst	Thu Dec 31 11:28:49 2009 -0800
@@ -25,6 +25,7 @@
   * :ref:`Rips complex construction <rips-example>`
   * Cech complex construction       |cpp-only|
   * :ref:`Circle-valued parametrization <cohomology-parametrization>`
+  * :ref:`Piecewise-linear vineyards <pl-vineyard>`
 
 .. todo:: 
    Document more examples.