Relecture, suite et fin

doc/VERSIONS

-$Id: VERSIONS,v 1.141 2003-04-19 04:17:09 geuzaine Exp $
+$Id: VERSIONS,v 1.142 2003-04-21 01:32:54 geuzaine Exp $
 
 New in 1.44: new reference manual; added support for PNG output; fixed
-small configuration bugs;
+small configure script bugs;
 
 New in 1.43: fixed solver interface problem on Mac OS X; new option to
 specify the interactive rotation center (default is now the pseudo

doc/texinfo/command_line.texi

@@ -5,7 +5,10 @@
 parse input files, output unrolled geometry, and exit
 @end ftable
 
+@sp 1 
+
 @noindent Mesh options:
+
 @ftable @code
 @item -1, -2, -3
 perform batch 1D, 2D and 3D mesh generation
@@ -41,7 +44,10 @@ recombine meshes from old extrusion mesh generator
 display 2D mesh construction interactively
 @end ftable
 
+@sp 1 
+
 @noindent Post-processing options:
+
 @ftable @code
 @item -dl
 enable display lists
@@ -55,7 +61,10 @@ smooth views
 convert an ascii view into a binary one
 @end ftable
 
+@sp 1 
+
 @noindent Display options:
+
 @ftable @code
 @item -nodb
 disable double buffering
@@ -73,7 +82,10 @@ specify display
 set projection mode to perspective
 @end ftable
 
+@sp 1
+
 @noindent Other options:
+
 @ftable @code
 @item -a, -g, -m, -s, -p
 start in automatic, geometry, mesh, solver or post-processing mode (default:

doc/texinfo/shortcuts.texi

@@ -48,7 +48,7 @@ save file as
 
 @end table
 
-
+@sp 1
 
 Other shortcuts:
 

tutorial/bgmesh.pos

 /********************************************************************* 
  *
- *  Gmsh tutorial 1 - appendix 3
+ *  Gmsh tutorial 1 - appendix 0
  * 
  *  2D background mesh
  *
  *********************************************************************/
 
 // This post-processing view contains scalar triangles. The values
-// represent the target characteristic mesh sizes to be applied to the
-// first tutorial, t1.geo.
+// represent the target characteristic mesh element sizes to be
+// applied to the first tutorial, t1.geo.
 //
 // There are two ways to use this view as a background mesh:
 //

tutorial/t1.geo

@@ -2,58 +2,46 @@
  *
  *  Gmsh tutorial 1
  * 
- *  Variables, Elementary entities (Points, Lines, Surfaces), Physical
- *  entities (Points, Lines, Surfaces), Background mesh
+ *  Variables, elementary entities (points, lines, surfaces), physical
+ *  entities (points, lines, surfaces), background mesh
  *
  *********************************************************************/
 
-// All geometry description in Gmsh is made by means of a special
-// language (looking somewhat similar to C). The simplest construction
-// of this language is the 'affectation'. 
-
-// The following command (all commands end with a semi colon) defines
-// a variable called 'lc' and affects the value 0.007 to 'lc':
+// The simplest construction of Gmsh's scripting language is the
+// `affectation'. The following command defines a new variable `lc':
 
 lc = 0.007;
 
-// This newly created variable can be used to define the first Gmsh
-// elementary entity, a 'Point'. A Point is defined by a list of four
-// numbers: its three coordinates (x, y and z), and a characteristic
-// length which sets the target mesh size at the point:
+// This variable can then for example be used in the definition of
+// Gmsh's simplest elementary entity, a `Point'. A Point is defined by
+// a list of four numbers: its three coordinates (X, Y and Z), and a
+// characteristic length which sets the target element size at the
+// point:
 
 Point(1) = {0, 0, 0, 9.e-1 * lc};
 
-// The mesh size is defined as the length of the segments for lines,
-// the radii of the circumscribed circles for triangles and the radii
-// of the circumscribed spheres for tetrahedra, respectively. The
-// actual distribution of the mesh sizes is obtained by interpolation
-// of the characteristic lengths prescribed at the points. There are
-// also other possibilities to specify characteristic lengths:
-// attractors (see t7.geo) and background meshes (see bgmesh.pos).
+// The actual distribution of the mesh element sizes is then obtained
+// by interpolation of these characteristic lengths throughout the
+// geometry. There are also other possibilities to specify
+// characteristic lengths: attractors (see `t7.geo') and background
+// meshes (see `bgmesh.pos').
 
 // As can be seen in the previous definition, more complex expressions
-// can be constructed from variables. Here, the product of the
-// variable 'lc' by the constant 9.e-1 is given as the fourth argument
-// of the list defining the point.
-//
-// The following general syntax rule is applied for the definition of
-// all geometrical entities:
-//
-//    "If a number defines a new entity, it is enclosed between
-//    parentheses. If a number refers to a previously defined entity,
-//    it is enclosed between braces."
-//
-// Three additional points are then defined:
+// can be constructed from variables and floating point
+// constants. Here, the product of the variable `lc' by the constant
+// 9.e-1 is given as the fourth argument of the list defining the
+// point.
+
+// We can then define some additional points as well as our first
+// curve.  Curves are Gmsh's second type of elementery entities, and,
+// amongst curves, straight lines are the simplest. A straight line is
+// defined by a list of point numbers. In the commands below, for
+// example, the line 1 starts at point 1 and ends at point 2:
 
 Point(2) = {.1, 0,  0, lc} ;
 Point(3) = {.1, .3, 0, lc} ;
 Point(4) = {0,  .3, 0, lc} ;
 
-// The second elementary geometrical entity in Gmsh is the
-// curve. Amongst curves, straight lines are the simplest. A straight
-// line is defined by a list of point numbers. For example, line 1
-// starts at point 1 and ends at point 2:
-
 Line(1) = {1,2} ;
 Line(2) = {3,2} ;
 Line(3) = {3,4} ;
@@ -63,26 +51,27 @@ Line(4) = {4,1} ;
 // simple rectangular surface from the four lines defined above, a
 // line loop has first to be defined. A line loop is a list of
 // connected lines, a sign being associated with each line (depending
-// on the orientation of the line).
+// on the orientation of the line):
 
 Line Loop(5) = {4,1,-2,3} ;
 
-// The surface is then defined as a list of line loops (only one
-// here):
+// We can then define the surface as a list of line loops (only one
+// here, since there are no holes--see `t4.geo'):
 
 Plane Surface(6) = {5} ;
 
 // At this level, Gmsh knows everything to display the rectangular
 // surface 6 and to mesh it. But a supplementary step is needed in
 // order to assign region numbers to the various elements in the mesh
-// (the points, the lines and the triangles discretizing points 1 to
-// 4, lines 1 to 4 and surface 6). This is achieved by the definition
-// of Physical entities. Physical entities will group elements
-// belonging to several elementary entities by giving them a common
-// number (a region number), and specifying their orientation.
-//
-// For example, the two points 1 and 2 can be grouped into the
-// physical entity 1:
+// (i.e. to the points, the line segments and the triangles
+// discretizing points 1 to 4, lines 1 to 4 and surface 6,
+// respectively). This is achieved by the definition of `physical
+// entities'. Physical entities will group elements belonging to
+// several elementary entities by giving them a common number (a
+// region number), and specifying their orientation.
+
+// We can for example group the points 1 and 2 into the physical
+// entity 1:
 
 Physical Point(1) = {1,2} ;
 
@@ -91,14 +80,16 @@ Physical Point(1) = {1,2} ;
 // for line or surface elements:
 
 Physical Line(10) = {1,2,4} ;
+
 MySurface = 100;
 Physical Surface(MySurface) = {6} ;
 
-// All the line elements which will be created during the mesh of
-// lines 1, 2 and 4 will be saved in the output file with the region
-// number 10; and all the triangular elements resulting from the
-// discretization of surface 6 will be given the region number 100.
-//
-// If no physical groups are defined, all the elements in the mesh are
-// directly saved with their default orientation and with a region
-// number equal to their elementary region number.
+// All the line elements created during the meshing of lines 1, 2 and
+// 4 will be saved in the output file with the region number 10; and
+// all the triangular elements resulting from the discretization of
+// surface 6 will be given the region number 100.
+
+// Note that, if no physical entities are defined, all the elements in
+// the mesh will be directly saved with their default orientation and
+// with a region number equal to the number of the elementary entity
+// they discretize.

tutorial/t2.geo

@@ -2,29 +2,25 @@
  *
  *  Gmsh tutorial 2
  * 
- *  Includes, Geometrical transformations, Extruded geometries,
- *  Elementary entities (Volumes), Physical entities (Volumes)
+ *  Includes, geometrical transformations, extruded geometries,
+ *  elementary entities (volumes), physical entities (volumes)
  *
  *********************************************************************/
 
-// The first tutorial file will serve as a basis to construct this
-// one. It can be included with:
+// We first include the previous tutorial file, in order to use it as
+// a basis for this one:
 
 Include "t1.geo";
 
-// There are several possibilities to build a more complex geometry
-// from the one previously defined in 't1.geo'.
-//
-// New points, lines and surfaces can first be directly defined in the
-// same way as in 't1.geo':
+// We can then add new points and lines and surfaces in the same way
+// as we did in `t1.geo':
 
 Point(5) = {0, .4, 0, lc};
 Line(5) = {4, 5};
 
-// But Gmsh also provides geometrical transformation mechanisms to
-// move (translate, rotate, ...), add (translate, rotate, ...) or
-// extrude (translate, rotate) elementary geometrical entities. For
-// example, the point 3 can be moved by 0.05 units on the left with:
+// But Gmsh also provides tools to tranform (translate, rotate, etc.)
+// elementary entities or copies of elementary entities. For example,
+// the point 3 can be moved by 0.05 units on the left with:
 
 Translate {-0.05,0,0} { Point{3}; }
 
@@ -33,32 +29,33 @@ Translate {-0.05,0,0} { Point{3} ; }
 
 Translate {0,0.1,0} { Duplicata{ Point{3}; } }
 
-// Of course, translation, rotation and extrusion commands not only
-// apply to points, but also to lines and surfaces. The following
-// command extrudes surface 6 defined in 't1.geo', as well as a new
-// surface 11, along the z axis by 'h':
+// Of course, these transformation commands not only apply to points,
+// but also to lines and surfaces. The following command extrudes the
+// surface 6 defined in `t1.geo', as well as a new surface 11, along
+// the z axis:
 
 h = 0.12;
 Extrude Surface { 6, {0, 0, h} };
 
-Line(7) = {3, 6} ; Line(8) = {6,5} ; Line Loop(10) = {5,-8,-7,3};
+Line(7) = {3, 6};
+Line(8) = {6,5};
 
+Line Loop(10) = {5,-8,-7,3};
 Plane Surface(11) = {10};
 
 Extrude Surface { 11, {0, 0, h} };
 
 // All these geometrical transformations automatically generate new
-// elementary entities. The following commands permit to specify
-// manually a characteristic length for some of the automatically
-// created points:
+// elementary entities. The following command permits to specify
+// manually a characteristic length for some of the new points:
 
 Characteristic Length {6, 22, 2, 3, 16, 12} = lc * 2;
 
-// If the transformation tools are handy to create complex geometries,
-// it is sometimes useful to generate the flat geometry, consisting
-// only of the explicit list elementary entities. This can be achieved
-// by selecting the 'File->Save as->Gmsh unrolled geometry' menu or by
-// typing
+// Note that, if the transformation tools are handy to create complex
+// geometries, it is also sometimes useful to generate the `flat'
+// geometry, with an explicit list of all elementary entities. This
+// can be achieved by selecting the `File->Save as->Gmsh unrolled
+// geometry' menu or by typing
 //
 // > gmsh t2.geo -0
 //
@@ -66,9 +63,9 @@ Characteristic Length{6,22,2,3,16,12} = lc * 2 ;
 
 // Volumes are the fourth type of elementary entities in Gmsh. In the
 // same way one defines line loops to build surfaces, one has to
-// define surface loops to build volumes. The following volumes are
-// very simple, without holes (and thus consist of only one surface
-// loop):
+// define surface loops (i.e. `shells') to build volumes. The
+// following volumes don't have holes and thus consist of single
+// surface loops:
 
 Surface Loop(145) = {121,11,131,135,139,144};
 Volume(146) = {145};
@@ -76,11 +73,8 @@ Volume(146) = {145};
 Surface Loop(146) = {121,6,109,113,117,122};
 Volume(147) = {146};
 
-// To save all volumic (tetrahedral) elements of volume 146 and 147
-// with the associate region number 1, a Physical Volume must be
-// defined:
+// To save all the tetrahedra discretizing the volumes 146 and 147
+// with a common region number, we finally define a physical
+// volume:
 
 Physical Volume (1) = {146,147};
-
-// Congratulations! You've created your first fully unstructured
-// tetrahedral 3D mesh!

tutorial/t3.geo

@@ -2,53 +2,55 @@
  *
  *  Gmsh tutorial 3
  * 
- *  Extruded meshes, Options
+ *  Extruded meshes, options
  *
  *********************************************************************/
 
-// Again, the first tutorial example is included:
+// Again, we start by including the first tutorial:
 
 Include "t1.geo";
 
-// As in 't2.geo', an extrusion along the z axis will be performed:
+// As in `t2.geo', we plan to perform an extrusion along the z axis.
+// But here, instead of only extruding the geometry, we also want to
+// extrude the 2D mesh. This is done with the same `Extrude' command,
+// but by specifying the number of layers (4 in this case, with 8, 4,
+// 2 and 1 subdivisions, respectively), with volume numbers 9000 to
+// 9003 and respective heights equal to h/4:
 
 h = 0.1;
 
-// But contrary to 't2.geo', not only the geometry will be extruded,
-// but also the 2D mesh. This is done with the same Extrude command,
-// but by specifying the number of layers (here, there will be four
-// layers, of respectively 8, 4, 2 and 1 elements in depth), with
-// volume numbers 9000 to 9003 and respective heights equal to h/4:
-
 Extrude Surface { 6, {0,0,h} } { 
   Layers { {8,4,2,1}, {9000:9003}, {0.25,0.5,0.75,1} }; 
 };
 
-// The extrusion can also performed with a rotation instead of a
+// The extrusion can also be performed with a rotation instead of a
 // translation, and the resulting mesh can be recombined into prisms
-// (wedges) if the surface elements are triangles, or hexahedra if the
-// surface elements are quadrangles. All rotations are specified by an
-// axis direction ({0,1,0}), an axis point ({-0.1,0,0.1}) and a
-// rotation angle (-Pi/2):
+// (wedges). All rotations are specified by an axis direction
+// ({0,1,0}), an axis point ({-0.1,0,0.1}) and a rotation angle
+// (-Pi/2):
 
 Extrude Surface { 122, {0,1,0} , {-0.1,0,0.1} , -Pi/2 } { 
   Recombine; Layers { 7, 9004, 1 }; 
 };
 
-// A translation ({-2*h,0,0}) and a rotation ({1,0,0} , {0,0.15,0.25},
-// Pi/2) can be combined:
+// Note that a translation ({-2*h,0,0}) and a rotation ({1,0,0},
+// {0,0.15,0.25}, Pi/2) can also be combined:
 
 Extrude Surface {news-1, {-2*h,0,0}, {1,0,0} , {0,0.15,0.25} , Pi/2}{ 
   Layers {10,9004,1}; Recombine; 
 };
 
+// We finally define a new physical volume to save all the tetrahedra
+// with a common region number (101):
+
 Physical Volume(101) = {9000:9004};
 
-// All interactive options can also be set directly in the input file.
-// For example, the following lines define a global characteristic
-// length factor, redefine some background colors, disable the display
-// of the axes, and select an initial viewpoint in XYZ mode (disabling
-// the interactive trackball-like rotation mode):
+// Let us now change some options... Since all interactive options are
+// accessible in Gmsh's scripting language, we can for example define
+// a global characteristic length factor, redefine some background
+// colors, disable the display of the axes, and select an initial
+// viewpoint in XYZ mode (disabling the interactive trackball-like
+// rotation mode) directly in the input file:
 
 Mesh.CharacteristicLengthFactor = 4;
 General.Color.Background = {120,120,120};
@@ -65,19 +67,18 @@ General.RotationX = 10;
 General.RotationY = 70;
 General.TranslationX = -0.2;
 
-// Note: all colors can be defined literally or numerically, i.e.
-// 'General.Color.Background = Red' is equivalent to
-// 'General.Color.Background = {255,0,0}'. As with user-defined
-// variables, the options can be used either as right hand or left
-// hand sides, so that
+// Note that all colors can be defined literally or numerically, i.e.
+// `General.Color.Background = Red' is equivalent to
+// `General.Color.Background = {255,0,0}'; and that, as with
+// user-defined variables, the options can be used either as right or
+// left hand sides, so that the following command will set the
+// surface color to the same color as the points:
 
 Geometry.Color.Surfaces = Geometry.Color.Points;
 
-// will assign the color of the surfaces in the geometry to the same
-// color as the points.
-
-// A click on the '?'  button in the status bar of the graphic window
-// will dump all current options to the terminal. To save all
-// available options to a file, use the 'File->Save as->Gmsh options'
+// You can click on the `?'  button in the status bar of the graphic
+// window to see the current values of all options. To save all the
+// options to a file, you can use the `File->Save as->Gmsh options'
 // menu. To save the current options as the default options for all
-// future Gmsh sessions, use the 'Tools->Options->Save' button.
+// future Gmsh sessions, you should use the `Tools->Options->Save'
+// button.

tutorial/t4.geo

@@ -2,10 +2,13 @@
  *
  *  Gmsh tutorial 4
  * 
- *  Built-in functions, Holes, Strings, Mesh color
+ *  Built-in functions, holes, strings, mesh color
  *
  *********************************************************************/
 
+// As usual, we start by defining some variables, some points and some
+// lines:
+
 cm = 1e-02;
 
 e1 = 4.5*cm; e2 = 6*cm / 2; e3 =  5*cm / 2;
@@ -20,59 +23,6 @@ ssin = Sqrt(1-ccos^2) ;
 Lc1 = 0.01;
 Lc2 = 0.003;
 
-// A whole set of operators can be used, which can be combined in all
-// the expressions. These operators are defined in a similar way to
-// their C or C++ equivalents (with the exception of '^'):
-//
-//   '-' (in both unary and binary versions, i.e. as in '-1' and '1-2')
-//   '!' (the negation)
-//   '+'
-//   '*'
-//   '/'
-//   '%' (the rest of the integer division)
-//   '<'
-//   '>'
-//   '<='
-//   '>='
-//   '=='
-//   '!='
-//   '&&' (and)
-//   '||' (or)
-//   '||' (or)
-//   '^' (power)
-//   '?' ':' (the ternary operator)
-//
-// Grouping is done, as usual, with parentheses.
-//
-// In addition to these operators, all C mathematical functions can
-// also be used (note the first capital letter), i.e.
-// 
-//   Exp(x)
-//   Log(x)
-//   Log10(x)
-//   Sqrt(x)
-//   Sin(x)
-//   Asin(x)
-//   Cos(x)
-//   Acos(x)
-//   Tan(x)
-//   Atan(x)
-//   Atan2(x,y)
-//   Sinh(x)
-//   Cosh(x)
-//   Tanh(x)
-//   Fabs(x)
-//   Floor(x)
-//   Ceil(x)
-//   Fmod(x,y)
-// 
-// as well as a series of other functions:
-//
-//   Hypot(x,y)   computes Sqrt(x^2+y^2)
-//   Rand(x)      generates a random number in [0,x]
-//
-// The only predefined constant in Gmsh is Pi.
-
 Point(1) = { -e1-e2, 0.0  , 0.0 , Lc1};
 Point(2) = { -e1-e2, h1   , 0.0 , Lc1};
 Point(3) = { -e3-r , h1   , 0.0 , Lc2};
@@ -105,15 +55,18 @@ Point(25)= {  0 , h1+h3-R2,    0.0 , Lc2};
 Line(1)  = {1 ,17};
 Line(2)  = {17,16};
 
-// All curves are not straight lines... Circles are defined by a list
-// of three point numbers, which represent the starting point, the
-// center and the end point, respectively. All circles have to be
-// defined in the trigonometric (counter-clockwise) sense.  Note that
-// the 3 points should not be aligned (otherwise the plane in which
-// the circle lies has to be defined, by 'Circle(num) =
-// {start,center,end} Plane {nx,ny,nz}').
+// Since not all curves are straight lines, Gmsh provides many other
+// curve primitives: splines, B-splines, circle arcs, ellipse arcs,
+// etc. Here we define a new circle arc, starting at point 14 and
+// ending at point 16, and with the circle's center being the point
+// 15:
 
 Circle(3) = {14,15,16};
+ 
+// Note that, in Gmsh, circle arcs should always be stricly smaller
+// than Pi. We can then define additional lines and circles, as well
+// as a new surface:
+
 Line(4)  = {14,13};
 Line(5)  = {13,12};
 Line(6)  = {12,11};
@@ -135,33 +88,29 @@ Line(20) = {21,22};
 Line Loop(21) = {17,-15,18,19,-20,16};
 Plane Surface(22) = {21};
 
-// The surface is made of two line loops, i.e. it has one hole:
+// But we still need to define the exterior surface. Since it has a
+// hole, its definition now requires two lines loops:
 
 Line Loop(23) = {11,-12,13,14,1,2,-3,4,5,6,7,-8,9,10};
 Plane Surface(24) = {23,21};
 
-Physical Surface(1) = {22};
-Physical Surface(2) = {24};
-
-// You can add some comments by simply embedding a post-processing
-// view with some strings...
+// Finally, we can add some comments by simply embedding a
+// post-processing view containg some strings, and change the color of
+// some mesh entities:
 
 View "comments" {
+  // 10 pixels from the left and 15 pixels from the top of the graphic
+  // window:
   T2(10,15,0){"File created on Fri Oct 18 23:50:20 2002"};
+
+  // 10 pixels from the left and 10 pixels from the bottom of the
+  // graphic window:
   T2(10,-10,0){"Copyright (C) My Company"};
+
+  // in the model, at (X,Y,Z) = (0.0,0.11,0.0):
   T3(0,0.11,0,0){"Hole"};
 };
 
-// This will put the strings
-// - "File ..." 10 pixels from the left and 15 pixels from the top of
-//   the graphic window;
-// - "Copyright ..." 10 pixels from the left and 10 pixels from the
-//   bottom of the graphic window; and
-// - "Hole" in your model, at (x,y,z)=(0.0,0.11,0.0).
-
-// You can also change the color of the mesh entities for each
-// curve/surface:
-
 Color White{ Surface{ 22 }; }
 Color Purple{ Surface{ 24 }; }
 Color Red{ Line{ 1:14 }; }

tutorial/t5.geo

@@ -2,35 +2,35 @@
  *
  *  Gmsh tutorial 5
  * 
- *  Characteristic lengths, Arrays of variables, Functions, Loops
+ *  Characteristic lengths, arrays of variables, functions, loops
  *
  *********************************************************************/
 
-// This defines some characteristic lengths:
+// Again, we start be defining some characteristic lengths:
 
 lcar1 = .1;
 lcar2 = .0005;
 lcar3 = .055;
 
-// In order to change these lengths globally (without changing the
-// file), a global scaling factor for all characteristic lengths can
-// be specified on the command line with the option '-clscale' (or
-// with the option Mesh.CharacteristicLengthFactor). For example,
-// with:
+// If we wanted to change these lengths globally (without changing the
+// above definitions), we could give a global scaling factor for all
+// characteristic lengths on the command line with the `-clscale'
+// option (or with `Mesh.CharacteristicLengthFactor' in an option
+// file). For example, with:
 //
 // > gmsh t5 -clscale 1
 //
-// this example produces a mesh of approximately 2000 nodes and
-// 10,000 tetrahedra (in 3 seconds on an alpha workstation running at
-// 666MHz). With 
+// this input file produces a mesh of approximately 2,000 nodes and
+// 10,000 tetrahedra (in 3 seconds on a 666MHz alpha
+// workstation). With
 //
 // > gmsh t5 -clscale 0.2
 //
 // (i.e. with all characteristic lengths divided by 5), the mesh
-// counts approximately 170,000 nodes and one million tetrahedra
-// (and the computation takes 16 minutes on the same machine :-( So
-// there is still a lot of work to do to achieve decent performance
-// with Gmsh...)
+// counts approximately 170,000 nodes and one million tetrahedra.
+
+// Let us proceed by defining some elementary entities, describing a
+// truncated cube:
 
 Point(1) = {0.5,0.5,0.5,lcar2}; Point(2) = {0.5,0.5,0,lcar1};
 Point(3) = {0,0.5,0.5,lcar1};   Point(4) = {0,0,0.5,lcar1}; 
@@ -58,18 +58,19 @@ Line Loop(34) = {7,3,8,9};           Plane Surface(35) = {34};
 Line Loop(36) = {10,-18,16,20,-4,8}; Plane Surface(37) = {36};
 Line Loop(38) = {-14,-13,-12,19};    Plane Surface(39) = {38};
 
-// Instead of using included files, one can also define functions. In
-// the following function, the reserved variable 'newp' is used, which
-// automatically selects a new point number. This number is chosen as
-// the highest current point number, plus one. Analogously to 'newp',
-// there exists a variable 'newreg' which selects the highest number
-// of all entities other than points, plus one.
-
-// Note: there are no local variables. This will be changed in a
-// future version of Gmsh.
+// Instead of using included files, let us now use a user-defined
+// function in order to carve some holes in the cube:
 
 Function CheeseHole 
 
+  // In the following commands we use the reserved variable name
+  // `newp', which automatically selects a new point number. This
+  // number is chosen as the highest current point number, plus
+  // one. (Note that, analogously to `newp', there also exists
+  // variables `newc', `news', `newv' and `newreg' which select the
+  // highest number of amongst curves, surfaces, volumes or
+  // any entities other than points, respectively.)
+
   p1 = newp; Point(p1) = {x,  y,  z,  lcar3} ;
   p2 = newp; Point(p2) = {x+r,y,  z,  lcar3} ;
   p3 = newp; Point(p3) = {x,  y+r,z,  lcar3} ;
@@ -91,8 +92,9 @@ Function CheeseHole
   c11 = newreg; Circle(c11) = {p4,p1,p6};
   c12 = newreg; Circle(c12) = {p6,p1,p7};
 
-// All surfaces are not plane... Here is the way to define ruled
-// surfaces (which have 3 or 4 borders):
+  // We need non-plane surfaces to define the spherical cheese
+  // holes. Here we use ruled surfaces, which can have 3 or 4
+  // borders:
 
   l1 = newreg; Line Loop(l1) = {c5,c10,c4};   Ruled Surface(newreg) = {l1};
   l2 = newreg; Line Loop(l2) = {c9,-c5,c1};   Ruled Surface(newreg) = {l2};
@@ -103,15 +105,14 @@ Function CheeseHole
   l7 = newreg; Line Loop(l7) = {c2,c7,c12};   Ruled Surface(newreg) = {l7};
   l8 = newreg; Line Loop(l8) = {-c6,-c9,c2};  Ruled Surface(newreg) = {l8};
 
-// Warning: surface meshes are generated by projecting a 2D mesh in
-// the mean plane of the surface. This gives nice results only if the
-// surface curvature is small enough. Otherwise you will have to cut
-// the surface in pieces.
+  // Please note that all surface meshes are generated by projecting a
+  // 2D planar mesh onto the surface, and that this method gives nice
+  // results only if the surface's curvature is relatively enough.
+  // If not, you will have to cut the surface in pieces. 
 
-// Arrays of variables can be manipulated in the same way as classical
-// variables. Warning: accessing an uninitialized element in an array
-// will produce an unpredictable result. Note that whole arrays can
-// also be instantly initialized (e.g. l[]={1,2,7} is valid).
+  // We then use an array of variables to store the surface loop's
+  // identification numbers for later reference (we will need these to
+  // define the final volume):
 
   theloops[t] = newreg ; 
 
@@ -123,55 +124,47 @@ Function CheeseHole
 
 Return
 
+// We can use a `For' loop to generate five holes in the cube:
 
 x = 0 ; y = 0.75 ; z = 0 ; r = 0.09 ;
 
-// A For loop is used to generate five holes in the cube:
-
 For t In {1:5}
 
   x += 0.166 ; 
   z += 0.166 ; 
 
-// This command calls the function CheeseHole. Note that, instead of
-// defining a function, we could have defined a file containing the
-// same code, and used the Include command to include this file.
-
   Call CheeseHole ;
 
-// A physical volume is defined for each cheese hole
+  // We define a physical volume for each cheese hole:
 
   Physical Volume (t) = thehole ;
  
-// The Printf function permits to print the value of variables on the
-// terminal, in a way similar to the 'printf' C function:
+  // We also print some variables on the terminal (note that, since
+  // all variables are treated internally as floating point numbers,
+  // the format string should only contain valid floating point format
+  // specifiers):
 
   Printf("Hole %g (center = {%g,%g,%g}, radius = %g) has number %g!",
 	 t, x, y, z, r, thehole) ;
 
-// Note: All Gmsh variables are treated internally as double precision
-// numbers. The format string should thus only contain valid double
-// precision number format specifiers (see the C or C++ language
-// reference for more details).
-
 EndFor
 
-// This is the surface loop for the exterior surface of the cube:
+// We can then define the surface loop for the exterior surface of the
+// cube:
 
 theloops[0] = newreg ;
 
 Surface Loop(theloops[0]) = {35,31,29,37,33,23,39,25,27} ;
 
-// The volume of the cube, without the 5 cheese holes, is defined by 6
-// surface loops (the exterior surface and the five interior loops).
-// To reference an array of variables, its identifier is followed by
-// '[]':
+// The volume of the cube, without the 5 cheese holes, is now defined
+// by 6 surface loops (the exterior surface and the five interior
+// loops).  To reference an array of variables, its identifier is
+// followed by '[]':
 
 Volume(186) = {theloops[]} ;
 
-// This physical volume assigns the region number 10 to the tetrahedra
-// paving the cube (but not the holes, whose elements were tagged from
-// 1 to 5 in the 'For' loop)
+// We finally define a physical volume for the elements discretizing
+// the cube, without the holes (whose elements were already tagged
+// with numbers 1 to 5 in the `For' loop):
 
 Physical Volume (10) = 186 ;
-

tutorial/t6.geo

@@ -6,6 +6,9 @@
  *
  *********************************************************************/
 
+// We start by defining a more complex geometry, using the same
+// commands as in the previous examples:
+
 r_int  = 0.05 ;
 r_ext  = 0.051 ;
 r_far  = 0.125 ;
@@ -129,9 +132,12 @@ Volume(143) = {142}; // inf b
 Surface Loop(144) = {89,-119,71,103,115};
 Volume(145) = {144}; // inf h
 
-// Transfinite line commands explicitly specify the number of points
-// and their distribution. 'Progression 2' means that each line
-// element in the series will be twice as long as the preceding one.
+// Once the geometry is defined, we then add transfinite mesh commands
+// in order to explicitly define a structured mesh.
+
+// 1. Transfinite line commands specify the number of points on the
+// curves and their distribution (`Progression 2' means that each line
+// element in the series will be twice as long as the preceding one):
 
 Transfinite Line{35,21,22,23,24,38,17,18,19,20} = nbpt_phi ;
 Transfinite Line{31,26,48,44,42} = nbpt_int Using Progression 0.88;
@@ -141,9 +147,10 @@ Transfinite Line{32,27,49,45,43} = nbpt_shell ;
 Transfinite Line{33,28,46,50,52} = nbpt_far Using Progression 1.2 ;
 Transfinite Line{34,29,51,47,53} = nbpt_inf Using Progression 1.05;
 
-// 2D transfinite entities are defined in respect to points. The
-// ordering of the points defines the ordering of the mesh elements.
-// A transfinite surface can have either 3 or 4 sides.
+// 2. Transfinite surfaces are defined by an ordered list of their
+// vertices (the ordering of these vertices defines the ordering of
+// the mesh elements). Note that a transfinite surface can only have 3
+// or 4 sides:
 
 Transfinite Surface{55} = {1,14,16,18};
 Transfinite Surface{57} = {14,2,19,16};
@@ -183,16 +190,9 @@ Transfinite Surface{103} = {24,23,25,26};
 Transfinite Surface{119} = {9,26,25};
 Transfinite Surface{117} = {13,5,25,26};
 
-// As with Extruded meshes, the Recombine command tells Gmsh to
-// recombine the simplices into quadrangles, prisms or hexahedra when
-// possible. A colon in a list acts as in the 'For' loop: all surfaces
-// having numbers between 55 and 127 are considered.
-
-Recombine Surface {55:127};
-
-// 3D transfinite entities are defined in respect to points. The
-// ordering of the points defines the ordering of the mesh elements.
-// A transfinite volume can have either 6 or 8 faces.
+// 3. Transfinite volumes are also defined by an ordered list of their
+// vertices (the ordering defines the ordering of the mesh elements).
+// A transfinite volume can only have 6 or 8 faces:
 
 Transfinite Volume{129} = {1,14,15,18,16,17};
 Transfinite Volume{131} = {17,16,14,15,20,19,2,10};
@@ -204,27 +204,30 @@ Transfinite Volume{141} = {7,22,21,8,24,23};
 Transfinite Volume{143} = {12,4,5,13,24,23,25,26};
 Transfinite Volume{145} = {8,24,23,9,26,25};
 
+// As with Extruded meshes, the `Recombine' command tells Gmsh to
+// recombine the simplices into quadrangles, prisms or hexahedra when
+// possible:
+
+Recombine Surface {55:127};
+
+// We finish by defing some physical entities:
+
 VolInt           = 1000 ;
-SurfIntPhi0      = 1001 ;
-SurfIntPhi1      = 1002 ;
+SurfIntPhi0      = 1001 ;  SurfIntPhi1      = 1002 ;
 SurfIntZ0        = 1003 ;
 
 VolShell         = 2000 ;
-SurfShellInt     = 2001 ;
-SurfShellExt     = 2002 ;
-SurfShellPhi0    = 2003 ;
-SurfShellPhi1    = 2004 ;
+SurfShellInt     = 2001 ;  SurfShellExt     = 2002 ;
+SurfShellPhi0    = 2003 ;  SurfShellPhi1    = 2004 ;
 SurfShellZ0      = 2005 ;
 LineShellIntPhi0 = 2006 ;
-LineShellIntPhi1 = 2007 ;
-LineShellIntZ0   = 2008 ;
+LineShellIntPhi1 = 2007 ;  LineShellIntZ0   = 2008 ;
 PointShellInt    = 2009 ;
 
 VolExt           = 3000 ;
 VolInf           = 3001 ;
 SurfInf          = 3002 ;
-SurfExtInfPhi0   = 3003 ;
-SurfExtInfPhi1   = 3004 ;
+SurfExtInfPhi0   = 3003 ;  SurfExtInfPhi1   = 3004 ;
 SurfExtInfZ0     = 3005 ;
 SurfInfRight     = 3006 ;
 SurfInfTop       = 3007 ;

tutorial/t7.geo

@@ -2,7 +2,7 @@
  *
  *  Gmsh tutorial 7
  * 
- *  Anisotropic meshes, Attractors
+ *  Anisotropic meshes, attractors
  *
  *********************************************************************/
 

tutorial/t8.geo

@@ -2,21 +2,18 @@
  *
  *  Gmsh tutorial 8
  * 
- *  Post-Processing, Scripting, Animations, Options
+ *  Post-processing, scripting, animations, options
  *
  *********************************************************************/
 
-// The first example is included, as well as some post-processing maps:
+// We first include `t1.geo' as well as some post-processing views:
 
 Include "t1.geo" ;
 Include "view1.pos" ;
 Include "view1.pos" ;
 Include "view4.pos" ;
 
-// Some general options are set (all the options specified
-// interactively can be directly specified in the ascii input
-// files. The current options can be saved into a file by selecting
-// 'File->Save as->Gmsh options').
+// We then set some general options:
 
 General.Trackball = 0 ;
 General.RotationX = 0 ;
@@ -29,7 +26,7 @@ General.Orthographic = 0 ;
 General.Axes = 0 ;
 General.SmallAxes = 0 ;
 
-// Some options are also specified for each post-processing view:
+// We also set some options for each post-processing view:
 
 v0 = PostProcessing.NbViews-4;
 v1 = v0+1;
@@ -71,10 +68,10 @@ View[v3].PositionY = View[v2].PositionY;
 View[v3].Width = View[v2].Width;
 View[v3].Height = View[v2].Height;
 
-// We loop from 1 to 255 with a step of 1 (to use a step different
-// from 1, just add a third argument in the list. For example, 'For
-// num In {0.5:1.5:0.1}' would increment num from 0.5 to 1.5 with a
-// step of 0.1).
+// We then loop from 1 to 255 with a step of 1. (To use a step
+// different from 1, just add a third argument in the list. For
+// example, `For num In {0.5:1.5:0.1}' would increment num from 0.5 to
+// 1.5 with a step of 0.1.)
 
 t = 0 ;
 
@@ -106,10 +103,8 @@ For num In {1:255}
     Draw; // draw the scene
 
     If ((num == 3) && (num2 < 10))
-      // The Sprintf function permits to create complex strings using
-      // variables (since all Gmsh variables are treated internally as
-      // double precision numbers, the format should only contain valid
-      // double precision number format specifiers):
+      // The `Print' command saves the graphical window; the `Sprintf'
+      // function permits to create the file names on the fly:
       Print Sprintf("t8-0%g.gif", num2);
       Print Sprintf("t8-0%g.jpg", num2);
     EndIf
@@ -122,9 +117,9 @@ For num In {1:255}
   EndFor
 
   If(num == 3)
-    // We could make a system call to generate the mpeg (uncomment the
-    // following of mpeg_encode is installed on your computer)
-
+    // We could make a system call here to generate the mpeg animation
+    // (uncomment the following of mpeg_encode is installed on your
+    // computer):
     // System "mpeg_encode t8.par" ;
   EndIf
 

tutorial/t9.geo

@@ -2,7 +2,7 @@
  *
  *  Gmsh tutorial 9
  * 
- *  Post-Processing, Plugins
+ *  Post-processing, plugins
  *
  *********************************************************************/
 
@@ -11,22 +11,23 @@
 // view, or create a new view based on previously loaded
 // views. Several default plugins are statically linked into Gmsh,
 // e.g. CutMap, CutPlane, CutSphere, Skin, Transform or Smooth.
+// Plugins can be controlled in the same way as other options: either
+// from the graphical interface (right click on the view button, then
+// `Plugins'), or from the command file.
 
-// Let's load a three-dimensional scalar view
+// Let us for include a three-dimensional scalar view:
 
 Include "view3.pos" ;
 
-// Plugins can be controlled in the same way as other options in
-// Gmsh. For example, the CutMap plugin (which extracts an isovalue
-// surface from a 3D scalar view) can either be called from the
-// graphical interface (right click on the view button, then
-// Plugins->CutMap), or from the command file:
+// We then set some options for the `CutMap' plugin (which extracts an
+// isovalue surface from a 3D scalar view) and run it:
 
 Plugin(CutMap).A = 0.67 ; // iso-value level
 Plugin(CutMap).iView = 0 ; // source view is View[0]
 Plugin(CutMap).Run ; 
 
-// The following runs the CutPlane plugin:
+// We also set some options for the `CutPlane' plugin (which computes
+// a section of a 3D view) and run it:
 
 Plugin(CutPlane).A = 0 ; 
 Plugin(CutPlane).B = 0.2 ; 
@@ -34,6 +35,8 @@ Plugin(CutPlane).C = 1 ;
 Plugin(CutPlane).D = 0 ; 
 Plugin(CutPlane).Run ; 
 
+// We finish by setting some view options and redrawing the scene:
+
 View[0].Light = 1;
 View[0].IntervalsType = 2;
 View[0].NbIso = 6;
@@ -42,4 +45,5 @@ View[0].SmoothNormals = 1;
 View[1].IntervalsType = 2;
 
 View[2].IntervalsType = 2;
+
 Draw;

tutorial/view1.pos

@@ -2,12 +2,12 @@
  *
  *  Gmsh tutorial 1 - appendix 1
  * 
- *  Scalar view
+ *  Scalar post-processing view
  *
  *********************************************************************/
 
-// In this view, there are only scalar triangles. There are 5 time
-// steps -> 3*5 = 15 values for each triangle.
+// This view contains scalar triangles. There are 5 time steps,
+// i.e. 3*5 = 15 values for each triangle.
 
 View "a scalar map" {
 ST(0.079090117,0.19794942,0,0.06966854,0.20076802,0,0.071449289,0.19423207,0){1206859.6,1570520.4,1594804.6,-2368529.7,-3162888.4,-3019964.8,1073015.3,1636334.6,1103926.4,1335740.9,1503948.1,2033518.7,-2359414.1,-3161601.9,-2921575.1};

tutorial/view2.pos

@@ -2,7 +2,7 @@
  *
  *  Gmsh tutorial 1 - appendix 2
  * 
- *  Vector view
+ *  Vector post-processing view
  *
  *********************************************************************/
 

tutorial/view3.pos

+/********************************************************************* 
+ *
+ *  Gmsh tutorial 1 - appendix 3
+ * 
+ *  Scalar 3D post-processing view
+ *
+ *********************************************************************/
+
 View "a 3D scalar map" {
 SS(-1,-1,-0.25,-0.86742481,-0.86548068,-0.14483364,-1,-0.70523324,-0.21165758,-1,-0.77608598,0.00064487429){2.0422973,1.5085891,1.5222776,1.5844414};
 SS(0.13402468,0.11673163,-0.1460819,0,0,-0.25,0.29173763,0,-0.20843742,0.22032809,0,-9.1119885e-05){0.039337265,0.044304329,0.1134179,0.027339551};

tutorial/view4.pos

+/********************************************************************* 
+ *
+ *  Gmsh tutorial 1 - appendix 4
+ * 
+ *  2D graphs, text annotations
+ *
+ *********************************************************************/
+
 View "e" {
 SP(0.05,0,0){3878262,3878766.4,3880412.5,3882811.2,3885521.1};
 SP(0.05,0.003,0){3881437.5,3877557.5,3870436.7,3859692,3844885.1};