X-Git-Url: http://git.vpit.fr/?p=perl%2Fmodules%2FLaTeX-TikZ.git;a=blobdiff_plain;f=README;h=c1bd2e38eb46a94167b70e7e16080f2666c86b7e;hp=fcfafc9fd23ffc65d247bac2477575a1005db145;hb=HEAD;hpb=33d85db00ad089db128ecc4b1aba67dd4bd07954

diff --git a/README b/README
index fcfafc9..c1bd2e3 100644
--- a/README
+++ b/README
@@ -2,14 +2,14 @@ NAME
     LaTeX::TikZ - Perl object model for generating PGF/TikZ code.
 
 VERSION
-    Version 0.01
+    Version 0.03
 
 SYNOPSIS
         use LaTeX::TikZ;
 
         # A couple of lines
         my $hline = Tikz->line(-1 => 1);
-        my $vline = Tikz->line([ 0, -1 ] => [ 0, -1 ]);
+        my $vline = Tikz->line([ 0, -1 ] => [ 0, 1 ]);
 
         # Paint them in red
         $_->mod(Tikz->color('red')) for $hline, $vline;
@@ -27,7 +27,7 @@ SYNOPSIS
         $octo->mod(Tikz->pattern(class => 'Dots'));
 
         # Create a formatter object
-        my $tikz = Tikz->formatter;
+        my $tikz = Tikz->formatter(scale => 5);
 
         # Put those objects all together and print them
         my $seq = Tikz->seq($octo, $hline, $vline);
@@ -35,30 +35,28 @@ SYNOPSIS
         print "$_\n" for map @$_, $head, $decl, $body;
 
 DESCRIPTION
-    This module provides an object model for TikZ, a graphical tookit for
+    This module provides an object model for TikZ, a graphical toolkit for
     LaTeX. It allows you to build structures representing geometrical
     figures, apply a wide set of modifiers on them, transform them globally
     with functors, and print them in the context of an existing TeX
     document.
 
 CONCEPTS
-    Traditionnaly, in TikZ, there are two ways of grouping elements, or
-    *ops*, together :
+    Traditionally, in TikZ, there are two ways of grouping paths together :
 
-    *   either as a *sequence*, where each element is drawn in its own line
-        :
+    *   either as a *sequence*, where each path is drawn in its own line :
 
             \draw (0cm,0cm) -- (0cm,1cm) ;
             \draw (0cm,0cm) -- (1cm,0cm) ;
 
-    *   or as a *path*, where elements are all drawn as one line :
+    *   or as an *union*, where paths are all drawn as one line :
 
             \draw (0cm,0cm) -- (0cm,1cm) (0cm,0cm) -- (1cm,0cm) ;
 
-    This distinction is important because there are some primitves that only
-    apply to paths but not to sequences, and vice versa.
+    This distinction is important because there are some primitives that
+    only apply to paths but not to sequences, and vice versa.
 
-    Figures are made of ops, path or sequence *sets* assembled together in a
+    Figures are made of path or sequence *sets* assembled together in a
     tree.
 
     *Modifiers* can be applied onto any set to alter the way in which it is
@@ -67,11 +65,13 @@ CONCEPTS
 
 INTERFACE
   Containers
-   "Tikz->path(@ops)"
-    Creates a LaTeX::TikZ::Set::Path object out of the ops @ops.
+   "union"
+        Tikz->union(@kids)
+
+    Creates a LaTeX::TikZ::Set::Union object out of the paths @kids.
 
         # A path made of two circles
-        Tikz->path(
+        Tikz->union(
                Tikz->circle(0, 1),
                Tikz->circle(1, 1),
               )
@@ -80,16 +80,48 @@ INTERFACE
                'even odd rule',
               );
 
-   "Tikz->seq(@kids)"
-    Creates a LaTeX::TikZ::Set::Sequence object out of the sequences, paths
-    or ops @kids.
+   "path"
+        Tikz->path(@kids)
+
+    A synonym for "union".
+
+   "join"
+        Tikz->join($connector, @kids)
+
+    Creates a LaTeX::TikZ::Set::Chain object that joins the paths @kinds
+    with the given $connector which can be, according to "connector" in
+    LaTeX::TikZ::Set::Chain, a string, an array reference or a code
+    reference.
+
+        # A stair
+        Tikz->join('-|', map [ $_, $_ ], 0 .. 5);
+
+   "chain"
+        Tikz->chain($kid0, $link0, $kid1, $link1, ... $kidn)
+
+    Creates a LaTeX::TikZ::Set::Chain object that chains $kid0 to $kid1 with
+    the string $link0, $kid1 to $kid2 with $link1, and so on.
+
+        # An heart-like shape
+        Tikz->chain([ 0, 1 ]
+         => '.. controls (-1, 1.5)    and (-0.75, 0.25) ..' => [ 0, 0 ]
+         => '.. controls (0.75, 0.25) and (1, 1.5)      ..' => [ 0, 1 ]
+        );
+
+   "seq"
+        Tikz->seq(@kids)
+
+    Creates a LaTeX::TikZ::Set::Sequence object out of the sequences or
+    paths @kids.
 
         my $bag = Tikz->seq($sequence, $path, $circle, $raw, $point);
 
   Elements
     Those are the building blocks of your geometrical figure.
 
-   "Tikz->point($point)"
+   "point"
+        Tikz->point($point)
+
     Creates a LaTeX::TikZ::Set::Point object by coercing $point into a
     LaTeX::TikZ::Point. The following rules are available :
 
@@ -119,18 +151,22 @@ INTERFACE
 
     You can define automatic coercions from your user point types to
     LaTeX::TikZ::Point by writing your own
-    LaTeX::TikZ::Point::My::User::Point class. See
+    "LaTeX::TikZ::Point::My::User::Point" class. See
     LaTeX::TikZ::Meta::TypeConstraint::Autocoerce for the rationale and
     LaTeX::TikZ::Point::Math::Complex for an example.
 
-   "Tikz->line($from => $to)"
+   "line"
+        Tikz->line($from => $to)
+
     Creates a LaTeX::TikZ::Set::Line object between the points $from and
     $to.
 
         my $x_axis = Tikz->line(-5 => 5);
         my $y_axis = Tikz->line([ 0, -5 ] => [ 0, 5 ]);
 
-   "Tikz->polyline(@points)"
+   "polyline"
+        Tikz->polyline(@points)
+
     Creates a LaTeX::TikZ::Set::Polyline object that links the successive
     elements of @points by segments.
 
@@ -141,9 +177,11 @@ INTERFACE
          Tikz->point(1, 1),
         );
 
-   "Tikz->closed_polyline(@points)"
+   "closed_polyline"
+        Tikz->closed_polyline(@points)
+
     Creates a LaTeX::TikZ::Set::Polyline object that cycles through
-    successive eleemnts of @points.
+    successive elements of @points.
 
         my $diamond = Tikz->closed_polyline(
          Tikz->point(0, 1),
@@ -152,7 +190,10 @@ INTERFACE
          Tikz->point(1, 0),
         );
 
-   "Tikz->rectangle($from => $to), Tikz->rectangle($from => { width => $width, height => $height })"
+   "rectangle"
+        Tikz->rectangle($from => $to)
+        Tikz->rectangle($from => { width => $width, height => $height })
+
     Creates a LaTeX::TikZ::Set::Rectangle object with opposite corners $from
     and $to, or with anchor point $from and dimensions $width and $height.
 
@@ -161,13 +202,17 @@ INTERFACE
          Tikz->point(2, 1),
         );
 
-   "Tikz->circle($center, $radius)"
+   "circle"
+        Tikz->circle($center, $radius)
+
     Creates a LaTeX::TikZ::Set::Circle object of center $center and radius
     $radius.
 
         my $unit_circle = Tikz->circle(0, 1);
 
-   "Tikz->arc($from => $to, $center)"
+   "arc"
+        Tikz->arc($from => $to, $center)
+
     Creates a LaTeX::TikZ::Set structure that represents an arc going from
     $from to $to with center $center.
 
@@ -177,14 +222,19 @@ INTERFACE
          [ 0, 0 ]
         );
 
-   "Tikz->arrow($from => $to), Tikz->arrow($from => dir => $dir)"
+   "arrow"
+        Tikz->arrow($from => $to)
+        Tikz->arrow($from => dir => $dir)
+
     Creates a LaTeX::TikZ::Set structure that represents an arrow going from
     $from towards $to, or starting at $from in direction $dir.
 
         # An horizontal arrow
         my $arrow = Tikz->arrow(0 => 1);
 
-   "Tikz->raw($content)"
+   "raw"
+        Tikz->raw($content)
+
     Creates a LaTeX::TikZ::Set::Raw object that will instantiate to the raw
     TikZ code $content.
 
@@ -193,7 +243,9 @@ INTERFACE
     "$set->mod($mod)". This method returns the $set object, so it can be
     chained.
 
-   "Tikz->clip($path)"
+   "clip"
+        Tikz->clip($path)
+
     Creates a LaTeX::TikZ::Mod::Clip object that can be used to clip a given
     sequence by the (closed) path $path.
 
@@ -206,7 +258,9 @@ INTERFACE
         my $set = Tikz->circle(0, 1.5)
                       ->clip(Tikz->rectangle([-1, -1] => [1, 1]));
 
-   "Tikz->layer($name, above => \@above, below => \@below)"
+   "layer"
+        Tikz->layer($name, above => \@above, below => \@below)
+
     Creates a LaTeX::TikZ::Mod::Layer object with name $name and optional
     relative positions @above and @below.
 
@@ -226,28 +280,45 @@ INTERFACE
                        ->mod(Tikz->pattern(class => 'Dots'))
                        ->layer('top');
 
-   "Tikz->width($line_width)"
+   "scale"
+        Tikz->scale($factor)
+
+    Creates a LaTeX::TikZ::Mod::Scale object that scales the sets onto which
+    it apply by the given $factor.
+
+        my $circle_of_radius_2 = Tikz->circle(0 => 1)
+                                     ->mod(Tikz->scale(2));
+
+   "width"
+        Tikz->width($line_width)
+
     Creates a LaTeX::TikZ::Mod::Width object that sets the line width to
     $line_width when applied.
 
         my $thick_arrow = Tikz->arrow(0 => 1)
                               ->mod(Tikz->width(5));
 
-   "Tikz->color($color)"
-    Creates a LaTeX::TikZ::Mod::Colorobject that sets the line color to
+   "color"
+        Tikz->color($color)
+
+    Creates a LaTeX::TikZ::Mod::Color object that sets the line color to
     $color (given in the "xcolor" syntax).
 
         # Paint the previous $thick_arrow in red.
         $thick_arrow->mod(Tikz->color('red'));
 
-   "Tikz->fill($color)"
+   "fill"
+        Tikz->fill($color)
+
     Creates a LaTeX::TikZ::Mod::Fill object that fills the interior of a
     path with the solid color $color (given in the "xcolor" syntax).
 
         my $red_box = Tikz->rectangle(0 => { width => 1, height => 1 })
                           ->mod(Tikz->fill('red'));
 
-   "Tikz->pattern(class => $class, %args)"
+   "pattern"
+        Tikz->pattern(class => $class, %args)
+
     Creates a LaTeX::TikZ::Mod::Pattern object of class $class and arguments
     %args that fills the interior of a path with the specified pattern.
     $class is prepended with "LaTeX::TikZ::Mod::Pattern" when it doesn't
@@ -257,7 +328,9 @@ INTERFACE
         my $hatched_circle = Tikz->circle(0 => 1)
                                  ->mod(Tikz->pattern(class => 'Lines'));
 
-   "Tikz->raw_mod($content)"
+   "raw_mod"
+        Tikz->raw_mod($content)
+
     Creates a LaTeX::TikZ::Mod::Raw object that will instantiate to the raw
     TikZ mod code $content.
 
@@ -265,18 +338,23 @@ INTERFACE
                                  ->mod(Tikz->raw_mod('->')) # or just ->mod('->')
 
   Helpers
-   "Tikz->formatter(%args)"
+   "formatter"
+        Tikz->formatter(%args)
+
     Creates a LaTeX::TikZ::Formatter object that can render a
     LaTeX::TikZ::Set tree.
 
         my $tikz = Tikz->formatter;
         my ($header, $declarations, $seq1_body, $seq2_body) = $tikz->render($set1, $set2);
 
-   "Tikz->functor(@rules)"
+   "functor"
+        Tikz->functor(@rules)
+
     Creates a LaTeX::TikZ::Functor anonymous subroutine that can be called
     against LaTeX::TikZ::Set trees to clone them according to the given
-    rules. @rules should be made of array references whose first element is
-    the class/role to match against and the second the handler to run.
+    rules. @rules should be a list of array references whose first element
+    is the class/role to match against and the second the handler to
+    execute.
 
         # The default is a clone method
         my $clone = Tikz->functor;
@@ -301,17 +379,15 @@ INTERFACE
 
         # A mod stripper
         my $strip = Tikz->functor(
-         'LaTeX::TikZ::Mod' => sub { return },
+         '+LaTeX::TikZ::Mod' => sub { return },
         );
         my $naked = $set->$strip;
 
 DEPENDENCIES
-    Any::Moose with Mouse 0.63 or greater.
+    Mouse 0.80 or greater.
 
     Sub::Name.
 
-    Scope::Guard.
-
     Math::Complex, Math::Trig.
 
     Scalar::Util, List::Util, Task::Weaken.
@@ -337,7 +413,8 @@ SUPPORT
         perldoc LaTeX::TikZ
 
 COPYRIGHT & LICENSE
-    Copyright 2010 Vincent Pit, all rights reserved.
+    Copyright 2010,2011,2012,2013,2014,2015 Vincent Pit, all rights
+    reserved.
 
     This program is free software; you can redistribute it and/or modify it
     under the same terms as Perl itself.