From 8797c6c9965e3d3e443d5faf43dd4a07f6f590b7 Mon Sep 17 00:00:00 2001
From: mertz
Date: Thu, 3 Apr 2003 09:08:16 +0000
Subject: - modification de la description de la section gradient pour prendre
 en   compte le nouveau format des gradient (zinc >> 3.2.6h) - quelques liens
 internes suppl�mentaires dans les descriptions des   attributs -labelxxx des
 items track et waypoint

---
 doc/refman.tex | 100 +++++++++++++++++++++++++++++----------------------------
 1 file changed, 51 insertions(+), 49 deletions(-)

(limited to 'doc/refman.tex')

diff --git a/doc/refman.tex b/doc/refman.tex
index 9aa43be..9c92e35 100644
--- a/doc/refman.tex
+++ b/doc/refman.tex
@@ -36,7 +36,7 @@
     citecolor=webbrightgreen,
     pdftitle={Zinc, an advanced scriptable Canvas.},
     pdfauthor={Patrick Lecoanet, Christophe Mertz, Centre d'�tude de la Navigation A�rienne},
-    pdfsubject={The pre-3.4 Reference Manual.},
+    pdfsubject={The pre-3.2.6i Reference Manual.},
     pdfkeywords={tk tcl perl x11 canvas opengl script gui TkZinc},
     pagebackref,
     pdfpagemode=None,
@@ -208,9 +208,9 @@
 \setlength{\marginparwidth}{20pt}
 \setlength{\textwidth}{480pt}
 
-\title{Zinc, an advanced scriptable Canvas.\\The 3.4 pre-release Reference Manual.\\\small{[CENA technical Note NT03-532]} }
+\title{Zinc, an advanced scriptable Canvas.\\The 3.2.6i Reference Manual.\\\small{[CENA technical Note NT03-532]} }
 \author{Patrick Lecoanet, Christophe Mertz}
-\date{17 March 2003}
+\date{2 April 2003}
 
 
 \begin{document}
@@ -291,7 +291,7 @@ This document is also referenced as CENA technical note NT03-532.
 
 \section{Differences with previous version}
 
-\subsection{Differences between 3.4 pre-release and 3.2.6 release}
+\subsection{Differences between 3.2.6i and 3.2.6 release}
 \begin{itemize}
 \item  bezier items have been suppressed; they can now be easily replaced by curve items.
 \item  curve items support now a higher level of description: they may be composed of line
@@ -305,7 +305,8 @@ if the contour must be taken as counterclockwise, clockwise or unchanged.
 Contours ids are now predictable. The GPC ``not-so-free'' library is no more used.
 It has been replaced by the GLU library. So TkZinc is again fully free software.
 \item  curve item have a new -fillrule attribute. 
-\item  the syntax of radial and path gradient has been changed.
+\item  the syntax of gradient has been changed, mainly to accomodate with any color specification
+defined for X. {\bf Beware that old gradient are no more compatible}
 \item  TkZinc comes now with a Zinctrace.pm module to trace every TkZinc method call
 \item  the hierarchical view in ZincDebug.pm can now display some choosen attributes
 in a choosen format.
@@ -1426,7 +1427,7 @@ reference) and all list parameters are given as array references.
     an empty invisible curve. In the second case, the list must contain lists of 2 or 3
     elements: xi, yi and and an optionnal point type. Currently, the only available point type
     is 'c' for a cubic bezier control point. For example in perl/Tk, the following list
-    is an example of 2 beziers segments with a straight segment in between:
+    is an example of 2 beziers segments with a straight segment in-between:
 
 \code{
 ( [x0, y0], [x1, y1, 'c'], [x2, y2, 'c'], [x3, y3],
@@ -2728,27 +2729,28 @@ value is the current value of the widget option \optref{forecolor}.}
 default value is {\tt center}.}
 
 \attribute{track}{labelangle}{angle}{The angle in degrees between the label anchor and the
-normal to the speed vector. This attribute works with the {\tt labeldistance} attribute to
+normal to the speed vector. This attribute works with the \attributeref{track}{labeldistance} attribute to
 specify a position for the label anchor with respect to the item origin. There is another
-alternative method for label positioning which is implemented with the {\tt labeldx} and
-{\tt labeldy} methods. Simultaneous use of the two methods should be done with care as
-there is no automatic update of values from the {\tt labeldx}, {\tt labeldy} set to the
-{\tt labeldistance}, {\tt labelangle} set. The default value is {\tt 20}.}
+alternative method for label positioning which is implemented with the \attributeref{track}{labeldx} and
+\attributeref{track}{labeldy} methods. Simultaneous use of the two methods should be done with care as
+there is no automatic update of values from the \attributeref{track}{labeldx},
+\attributeref{track}{labeldy} set to the \attributeref{track}{labeldistance},
+\attributeref{track}{labelangle} set. The default value is {\tt 20}.}
 
 \attribute{track}{labelconvergencestyle}{dimension}{XXX New. To be documented. The default
 value is ??.}
 
 \attribute{track}{labeldistance}{dimension}{The minimum distance in pixels between the
-track position and the label anchor. See the explanation of the {\tt labelangle} attribute
+track position and the label anchor. See the explanation of the \attributeref{track}{labelangle} attribute
 for some more details. The default value is 50.}
 
 \attribute{track}{labeldx}{dimension}{The X offset between the track position and the
-label anchor. The default value is computed from the values in the {\tt labeldistance} and
-{\tt labelangle} attributes.}
+label anchor. The default value is computed from the values in the \attributeref{track}{labeldistance} and
+\attributeref{track}{labelangle} attributes.}
 
 \attribute{track}{labeldy}{dimension}{The Y offset between the track position and the
-label anchor. The default value is computed from the values in the {\tt labeldistance} and
-{\tt labelangle} attributes.}
+label anchor. The default value is computed from the values in the \attributeref{track}{labeldistance} and
+\attributeref{track}{labelangle} attributes.}
 
 \attribute{track}{labelformat}{labelformat}{Geometry of the label fields. The default
 value is {\tt ""} which means that no label will be displayed.}
@@ -2924,16 +2926,17 @@ filled otherwise it will be outlined. The default value is {\tt false}.}
 default value is {\tt center}.}
 
 \attribute{waypoint}{labelangle}{angle}{The angle in degrees between the label anchor and
-the normal to the speed vector. This attribute works with the {\tt labeldistance}
+the normal to the speed vector. This attribute works with the \attributeref{track}{labeldistance}
 attribute to specify a position for the label anchor with respect to the item origin.
 There is another alternative method for label positioning which is implemented with the
-{\tt labeldx} and {\tt labeldy} methods. Simultaneous use of the two methods should be
-done with care as there is no automatic update of values from the {\tt labeldx}, {\tt
-labeldy} set to the {\tt labeldistance}, {\tt labelangle} set. The default value is {\tt
+\attributeref{track}{labeldx} and \attributeref{track}{labeldy} methods. Simultaneous use
+of the two methods should be done with care as there is no automatic update of values from the
+\attributeref{track}{labeldx}, \attributeref{track}{labeldy} set to the
+\attributeref{track}{labeldistance}, \attributeref{track}{labelangle} set. The default value is {\tt
 20}.}
 
 \attribute{waypoint}{labeldistance}{dimension}{The minimum distance in pixels between the
-way point position and the label anchor. See the explanation of the {\tt labelangle}
+way point position and the label anchor. See the explanation of the \attributeref{waypoint}{labelangle}
 attribute for some more details. The default value is {\tt 50}.}
 
 \attribute{waypoint}{labeldx}{dimension}{The X offset between the way point position and
@@ -4052,46 +4055,45 @@ The following figure shows the effect of fillrule value on curves with multiple
 \begin{blockindent}
   This is a string describing a color gradient to be used for example to fill a surface.
   Gradient are also used to describe color of lines, even if in this case the lines are
-  limited to one color with and additionnal alpha percentage.
+  limited to one color with and optionnal alpha percentage.
 
-  The string may consist in a single color name that will be used to paint a solid surface
-  or a simple color with an alpha valuecan be a list of gradient steps separated by \verb+|+ characters.
+  The string may consist in a single color specification that will be used to paint a solid surface
+  or a color with an alpha value or a list of gradient steps separated by \verb+|+ characters.
 
   The general pattern is:
   
-  \verb+gradient_step1|...|gradient_stepn/angle+ for an axial gradient,
+  \verb+"=axial degre | gradient_step1 | ... | gradient_stepn"+ for an axial gradient,
 
-  \verb+gradient_step1|...|gradient_stepn(x y+ for a radial gradient and
+  \verb+"=radial x y | gradient_step1 | ... | gradient_stepn"+ for a radial gradient,
 
-  \verb+gradient_step1|...|gradient_stepn[x y+ for a path gradient.
+  \verb+"=path x y | gradient_step1 | ... | gradient_stepn"+ for a path gradient.
 
-  The \verb+/angle+ section tells that the gradient is an axial gradient and give the
-  angle of the gradient in degres.
+  The \verb+degre+ parameter of an axial gradient defines the angle of the gradient in degres
+  in the usual trigonometric sense. It defaults to 0 degre.
 
-  The \verb+(x y+ section tells that the gradient is a radial gradient and give the center
-  of the gradient. The center is expressed in percentage of the bounding box, centered on the middle.
-  so \verb+(0 0+ means the center point of the bounding box, and \verb+(-50 -50+ means
-  the lower left corner of the bounding box.
-
-  The \verb+[x y+ section tells that the gradient is a path gradient and give the center
-  of the gradient. The center is expressed in % of the bounding box, centered on the middle.
-  See just above for more explanation.
+  The \verb+x y+ parameters of radial or path gradient define the center of the gradient.
+  The center is expressed in percentage of the bounding box, relatively to the center of
+  the bounding box. So \verb+0 0+ means the center while \verb+-50 -50+ means the lower
+  left corner of the bounding box.
 
   If none of the above gradient type specification is given, the gradient will be drawn as
   an axial gradient with a null angle.
 
   Each gradient segment section has the general form:
   
-    \verb+color_name:alpha color_position mid_span_position+
+    \verb+color;alpha color_position mid_span_position+
 
-  Each color can be specified as a valid X color (either name or \#value). An alpha value
-  can be applied to the color using the optional \verb+:alpha+ parameter.
+  Each color can be specified as a valid X color : either a named color or \#rrggbb value
+  or any valid X color specification such as  standard device-independent color specification
+  (e.g. \verb+CIEuvY:<u>/<v>/<Y>+ as defined in the X man page). An alpha value
+  can be applied to the color using the optional \verb+;alpha+ parameter whose value should be in the
+  0..100 intervalle.
 
   The color position tells where in the gradient surface, measured as a percentage of the
   total gradient distance, the color should start. The first gradient segment has its
   position set to 0 and the last segment has its position set to 100, regardless of the
   specification. The position can thus be safely omitted for these segments. The in
-  between segments must have a position explicitly set. If not given, a position will
+  between segments must have a position explicitly set. If not given, the position will
   default to 0.
 
   The mid span position tells where in the current gradient segment should be the median
@@ -4105,21 +4107,21 @@ The following figure shows the effect of fillrule value on curves with multiple
 
   The following picture gives many examples of gradients. They correspond to the following values:
 
-\verb+axial 1 :  'black|white/0'  :=  'black|white'+
+\verb+axial 1 :  '=axial 0 | black|white'  :=  'black|white'+
 
-\verb+axial 2 :  'black|white/90'+
+\verb+axial 2 :  '=axial 90 | black|white'+
 
-\verb+axial 3 :  'black|white/30'+
+\verb+axial 3 :  '=axial 30 |black|white'+
 
-\verb+axial 4 :  'black|black:0/30'+
+\verb+axial 4 :  '=axial 30|black|black:0'+
 
-\verb+radial 1 : 'white|black(-14 -20'+
+\verb+radial 1 : '=radial -14 -20|white|black'+
 
-\verb+radial 2 : 'white:50 0 70|black 50|white 100(0 0'+
+\verb+radial 2 : '=radial 0 0 | white:50 0 70|black 50|white 100'+
 
-\verb+path 1 :   'white|black:80[-14 -20'+
+\verb+path 1 :   '=path -14 -20|white|black:80'+
 
-\verb+path 2 :   'white|white 30|black:80[-14 -20'+
+\verb+path 2 :   '=path -14 -20 |white|white 30|black:80'+
 
 \fig{allgradients}{Examples of axial, radial and path gradients}{0.5}
 
-- 
cgit v1.1

