From c21c28112ae549b917b8342fbfade47b49e0320a Mon Sep 17 00:00:00 2001
From: Christophe Geuzaine <cgeuzaine@ulg.ac.be>
Date: Mon, 5 Jan 2009 17:23:22 +0000
Subject: [PATCH] clarify file formats

---
 doc/texinfo/gmsh.texi | 424 ++++++++++++++++++++++++------------------
 tutorial/view1.pos    |   2 +-
 tutorial/view2.pos    |   2 +-
 tutorial/view3.pos    |   2 +-
 tutorial/view5.msh    |  48 +++--
 5 files changed, 269 insertions(+), 209 deletions(-)

diff --git a/doc/texinfo/gmsh.texi b/doc/texinfo/gmsh.texi
index 82f9b8b232..dd4e3a670a 100644
--- a/doc/texinfo/gmsh.texi
+++ b/doc/texinfo/gmsh.texi
@@ -108,6 +108,7 @@ for Gmsh @value{GMSH-VERSION} (@today{}).
 @menu
 * Copying conditions::          Terms and conditions of use.
 * Overview::                    What is Gmsh?
+* How to read this manual?::    Which parts of this manual should you read (if any)?
 * General tools::               Description of general commands and options.
 * Geometry module::             Description of all Geometry commands.
 * Mesh module::                 Description of all Mesh commands.
@@ -135,11 +136,14 @@ Overview
 * Post-processing::             
 * What Gmsh is pretty good at::  
 * and what Gmsh is not so good at::  
+
+How to read this reference manual?
+
 * Syntactic rules::             
-* Comments::                    
 
 General tools
 
+* Comments::                    
 * Expressions::                 
 * Operators::                   
 * Built-in functions::          
@@ -256,7 +260,7 @@ Bugs, versions and credits
 @c Overview
 @c =========================================================================
 
-@node Overview, General tools, Copying conditions, Top
+@node Overview, How to read this manual?, Copying conditions, Top
 @chapter Overview
 
 @cindex Introduction
@@ -269,12 +273,12 @@ input and advanced visualization capabilities.
 
 Gmsh is built around four modules: geometry, mesh, solver and
 post-processing. All geometrical, mesh, solver and post-processing
-instructions are prescribed either interactively using the graphical user
-interface (GUI) or in ASCII data files using Gmsh's own scripting language.
-Interactive actions generate language bits in the input files, and vice
-versa. This makes it possible to automate all treatments, using loops,
-conditionals and external system calls. A brief description of the four
-modules is given hereafter.
+instructions are prescribed either interactively using the graphical
+user interface (GUI) or in text files using Gmsh's own scripting
+language.  Interactive actions generate language bits in the input
+files, and vice versa. This makes it possible to automate all
+treatments, using loops, conditionals and external system calls. A brief
+description of the four modules is given hereafter.
 
 @menu
 * Geometry::                    
@@ -283,8 +287,6 @@ modules is given hereafter.
 * Post-processing::             
 * What Gmsh is pretty good at::  
 * and what Gmsh is not so good at::  
-* Syntactic rules::             
-* Comments::                    
 @end menu
 
 @c -------------------------------------------------------------------------
@@ -392,7 +394,7 @@ maps. Post-processing functions include section computation, offset,
 elevation, boundary and component extraction, color map and range
 modification, animation, vector graphic output, etc. All the
 post-processing options can be accessed either interactively or through
-the input ASCII text files. Scripting permits to automate all
+the input script files. Scripting permits to automate all
 post-processing operations, as for example to create
 animations. User-defined operations can also be performed on
 post-processing views through dynamically loadable plugins.
@@ -439,7 +441,7 @@ interact with external solvers. Gmsh provides C, C++, Perl and Python
 interfaces, and others can be easily added (@pxref{Solver module});
 @item
 visualize computational results in a great variety of ways. Gmsh can display
-scalar, vector and tensor data sets, and can perform various operations on
+scalar, vector and tensor datasets, and can perform various operations on
 the resulting post-processing views (@pxref{Post-processing module});
 @item
 export plots in many different formats: vector PostScript or encapsulated
@@ -459,16 +461,16 @@ files, or specified on the command-line (see @ref{General options},
 @ref{Geometry options}, @ref{Mesh options}, @ref{Post-processing options},
 and @ref{Running Gmsh});
 @item
-and do all the above on various platforms (Windows, Mac and Unix), for free
-(@pxref{Copying conditions}), using clear-text ASCII files and/or a small
-but powerful graphical user interface.
+and do all the above on various platforms (Windows, Mac and Unix), for
+free (@pxref{Copying conditions}), using simple script files and/or a
+small but powerful GUI.
 @end itemize
 
 @c -------------------------------------------------------------------------
 @c ... and what Gmsh is not so good at
 @c -------------------------------------------------------------------------
 
-@node and what Gmsh is not so good at, Syntactic rules, What Gmsh is pretty good at, Overview
+@node and what Gmsh is not so good at,  , What Gmsh is pretty good at, Overview
 @section @dots{} and what Gmsh is not so good at
 
 Due to its historical background and limited developer manpower, Gmsh has
@@ -503,20 +505,78 @@ If you have the skills and some free time, feel free to join the project! We
 gladly accept any code contributions (@pxref{Programming notes}) to remedy
 the aforementioned (and all other) shortcomings...
 
+@c =========================================================================
+@c How to read this manual?
+@c =========================================================================
+
+@node How to read this manual?, General tools, Overview, Top
+@chapter How to read this reference manual?
+
+Gmsh can be used at three levels:
+
+@enumerate
+@item
+as a stand-alone graphical program, driven by an interactive graphical
+user interface (GUI);
+@item 
+as a stand-alone script-driven program;
+@item
+as a library.
+@end enumerate
+
+You don't need to read the rest of this reference manual in order to use
+Gmsh at the first level (i.e., interactively with the GUI). Just skip
+the next chapters and have a quick look at @ref{Running Gmsh}, then go
+play with the GUI and run the tutorials files (@pxref{Tutorial}) bundled
+in the distribution.  Screencasts that show how to use the GUI are
+available here: @uref{http://www.geuz.org/gmsh/screencasts/}.
+
+The aim of the reference manual is to explain everything you need to use
+Gmsh at the second level, i.e., using the built-in scripting language.
+A Gmsh script file is an ASCII text file that contains instructions in
+Gmsh's built-in scripting language. Such a file is interpreted by Gmsh's
+parser, and can be given any extension (or no extension at all). By
+convention, Gmsh uses the @file{.geo} extension for geometry scripts,
+and the @file{.pos} extension for parsed post-processing datasets. Once
+you master the tutorial (read the source files: they are heavily
+commented!), start reading chapter @ref{General tools}, then proceed
+with the next four chapters, which detail the syntax of the geometry,
+mesh, solver and post-processing scripting commands. You will see that
+most of the interactive actions in the GUI have a direct equivalent in
+the scripting language. If you want to use Gmsh as a pre- or
+post-processor for your own software, you will also want to learn about
+the non-scripting input/output files that Gmsh can read/write. In
+addition to Gmsh's native ``MSH'' file format (@pxref{File formats}),
+Gmsh can read/write many standard mesh files, depending on how it was
+built: check the `File->Save As' menu for a list of available formats.
+
+Finally, to use Gmsh at the third level (i.e., to link the Gmsh library
+with your own code), you will need to learn the internal Gmsh
+Application Programming Interface (API). No complete documentation of
+this API is available yet; a good starting point is @ref{Programming
+notes}, which gives a short introduction to Gmsh's internal source code
+structure. Then have a look e.g. at @file{utils/misc/driver.cpp} in the
+source code.
+
 @c -------------------------------------------------------------------------
-@c Syntactic Rules Used in this Document
+@c Syntactic rules used in the reference manual
 @c -------------------------------------------------------------------------
 
-@node Syntactic rules, Comments, and what Gmsh is not so good at, Overview
-@section Syntactic rules used in this document
+@menu
+* Syntactic rules::             
+@end menu
+
+@node Syntactic rules,  , How to read this manual?, How to read this manual?
+@section Syntactic rules used in the manual
 
 @cindex Syntax, rules
 @cindex Rules, syntactic
 @cindex Document syntax
 
-Here are the rules we tried to follow when writing this user's guide. Note
-that metasyntactic variable definitions stay valid throughout the manual
-(and not only in the sections where the definitions appear).
+Here are the rules we tried to follow when writing this reference
+manual. Note that metasyntactic variable definitions stay valid
+throughout the manual (and not only in the sections where the
+definitions appear).
 
 @enumerate
 @item 
@@ -536,11 +596,43 @@ Three dots (@dots{}) indicate a possible (multiple) repetition of the
 preceding rule.
 @end enumerate
 
+@c =========================================================================
+@c General tools
+@c =========================================================================
+
+@node General tools, Geometry module, How to read this manual?, Top
+@chapter General tools
+
+This chapter describes the general commands and options that can be used
+in Gmsh's script files. By ``general'', we mean ``not specifically
+related to one of the geometry, mesh, solver or post-processing
+modules''. Commands peculiar to these modules will be introduced in
+@ref{Geometry module}, @ref{Mesh module}, @ref{Solver module}, and
+@ref{Post-processing module}, respectively.
+
+Note that, if you are just beginning to use Gmsh, or just want to see
+what Gmsh is all about, you really don't need to read this chapter and
+the four next ones. Just have a quick look at @ref{Running Gmsh}, and go
+play with the GUI, running the tutorials and demonstration files bundled
+in the distribution (@pxref{Tutorial}). Screencasts that show how to use
+the GUI are available here: @uref{http://www.geuz.org/gmsh/screencasts/}.
+
+@menu
+* Comments::                    
+* Expressions::                 
+* Operators::                   
+* Built-in functions::          
+* User-defined functions::      
+* Loops and conditionals::      
+* General commands::            
+* General options::             
+@end menu
+
 @c -------------------------------------------------------------------------
 @c Comments
 @c -------------------------------------------------------------------------
 
-@node Comments,  , Syntactic rules, Overview
+@node Comments, Expressions, General tools, General tools
 @section Comments
 
 @cindex Comments
@@ -549,8 +641,7 @@ preceding rule.
 @findex /*, */
 @findex //
 
-All parsed input files (@file{.geo}) support both C and C++ style
-comments:
+Gmsh script files support both C and C++ style comments:
 
 @enumerate
 @item
@@ -563,60 +654,19 @@ These commands won't have the described effects inside double quotes or
 inside keywords. Also note that `white space' (spaces, tabs, new line
 characters) is ignored inside all expressions.
 
-You can add comments in a mesh file (@file{.msh}) by adding a section
-with an unrecognized label (e.g., @code{$Comments}/@code{$EndComments})
-after the @code{$MeshFormat}/@code{$EndMeshFormat} section: see @ref{MSH
-ASCII file format}.
-
-@c =========================================================================
-@c General tools
-@c =========================================================================
-
-@node General tools, Geometry module, Overview, Top
-@chapter General tools
-
-This chapter describes the general commands and options that can be used in
-Gmsh's ASCII text input files. By ``general'', we mean ``not specifically
-related to one of the geometry, mesh, solver or post-processing
-modules''. Commands peculiar to these modules will be introduced in
-@ref{Geometry module}, @ref{Mesh module}, @ref{Solver module}, and
-@ref{Post-processing module}, respectively.
-
-Note that, if you are just beginning to use Gmsh, or just want to see what
-Gmsh is all about, you really don't need to read this chapter and the four
-next ones. Just have a quick look at @ref{Running Gmsh}, and go play with
-the graphical user interface, running the tutorials and demonstration files
-bundled in the distribution! Most of the commands and options described in
-the following chapters are available interactively in the GUI, so you don't
-need to worry about Gmsh's internals for creating your first geometries,
-meshes and post-processing plots. Once you master the tutorial (read the
-source files: they are heavily commented---see @ref{Tutorial}), you might
-want to come back here to learn more about the specific syntax of Gmsh's
-commands and esoteric options.
-
-@menu
-* Expressions::                 
-* Operators::                   
-* Built-in functions::          
-* User-defined functions::      
-* Loops and conditionals::      
-* General commands::            
-* General options::             
-@end menu
-
 @c -------------------------------------------------------------------------
 @c Expressions
 @c -------------------------------------------------------------------------
 
-@node Expressions, Operators, General tools, General tools
+@node Expressions, Operators, Comments, General tools
 @section Expressions 
 
 @cindex Expressions, definition
 @cindex Constants
 
-The two constant types used in Gmsh are @var{real} and @var{string} (there
-is no integer type).  These types have the same meaning and syntax as in the
-C or C++ programming languages.  
+The two constant types used in Gmsh scripts are @var{real} and
+@var{string} (there is no integer type).  These types have the same
+meaning and syntax as in the C or C++ programming languages.
 
 @menu
 * Floating point expressions::  
@@ -657,16 +707,16 @@ parsing of the data file:
   GetValue("@var{string}", @var{expression})
 @end example
 
-Such @w{@var{expression}s} are used in most of Gmsh's commands.  The third
-and fourth cases in this definition permit to extract one item from a list
-(see below) and get the size of a list, respectively. The operators
-@var{operator-unary-left}, @var{operator-unary-right},
-@var{operator-binary}, @var{operator-ternary-left} and
-@var{operator-ternary-right} are defined in @ref{Operators}. For the
-definition of @w{@var{built-in-function}s}, see @ref{Built-in
-functions}. The various @w{@var{real-option}s} are listed in @ref{General
-options}, @ref{Geometry options}, @ref{Mesh options}, @ref{Solver options},
-and @ref{Post-processing options}.
+Such @w{@var{expression}s} are used in most of Gmsh's scripting
+commands.  The third and fourth cases in this definition permit to
+extract one item from a list (see below) and get the size of a list,
+respectively. The operators @var{operator-unary-left},
+@var{operator-unary-right}, @var{operator-binary},
+@var{operator-ternary-left} and @var{operator-ternary-right} are defined
+in @ref{Operators}. For the definition of @w{@var{built-in-function}s},
+see @ref{Built-in functions}. The various @w{@var{real-option}s} are
+listed in @ref{General options}, @ref{Geometry options}, @ref{Mesh
+options}, @ref{Solver options}, and @ref{Post-processing options}.
 
 The last case in the definition allows to ask the user for a value
 interactively. For example, inserting @code{GetValue("Value of parameter
@@ -1032,7 +1082,10 @@ cannot be imbricated.
 Executes the body of a (previously defined) function named @var{string}.
 @end ftable
 
-See @ref{t5.geo}, for an example of a user-defined function.
+See @ref{t5.geo}, for an example of a user-defined function. A
+shortcoming of Gmsh's scripting language is that all variables are
+``public''. Variables defined inside the body of a function will thus be
+available outside, too!
 
 @c -------------------------------------------------------------------------
 @c Loops and conditionals
@@ -1110,7 +1163,7 @@ writing.
 @findex *=
 @findex /=
 
-The following commands can be used anywhere in a Gmsh ASCII text input file:
+The following commands can be used anywhere in a Gmsh script:
 
 @ftable @code
 
@@ -1255,10 +1308,10 @@ Same as @code{Printf} above, but appends the expression at the end of
 the file.
 
 @item Merge @var{char-expression};
-Merges a file named @var{char-expression}. This command is equivalent to the
-`File->Merge' menu in the graphical user interface. If the path in
-@var{char-expression} is not absolute, @var{char-expression} is appended to
-the path of the current file.
+Merges a file named @var{char-expression}. This command is equivalent to
+the `File->Merge' menu in the GUI. If the path in @var{char-expression}
+is not absolute, @var{char-expression} is appended to the path of the
+current file.
 
 @item Draw;
 Redraws the scene.
@@ -1328,13 +1381,13 @@ appended to the path of the current file.
 @section General options
 
 Here is the list of the general @w{@var{char-option}s},
-@w{@var{real-option}s} and @w{@var{color-option}s} (in that order---check
-the default values to see the actual types). Most of these options are
-accessible in the graphical user interface, but not all of them. When
-running Gmsh interactively, changing an option in the ASCII text input file
-will modify the option in the GUI in real time. This permits for example to
-resize the graphical window in a script, or to interact with animations in
-the script and in the GUI at the same time.
+@w{@var{real-option}s} and @w{@var{color-option}s} (in that
+order---check the default values to see the actual types). Most of these
+options are accessible in the GUI, but not all of them. When running
+Gmsh interactively, changing an option in the script file will modify
+the option in the GUI in real time. This permits for example to resize
+the graphical window in a script, or to interact with animations in the
+script and in the GUI at the same time.
 
 Gmsh's default behavior is to save some of these options in a per-user
 ``session resource'' file (@code{General.SessionFileName}) every time Gmsh
@@ -1408,11 +1461,11 @@ the way meshes are saved.
 @cindex Commands, geometry
 
 The next subsections describe all the available geometry commands. These
-commands can be used anywhere in a Gmsh ASCII text input file. Note that the
-following general syntax rule is followed for the definition of geometrical
-entities: ``If an @var{expression} defines a new entity, it is enclosed
-between parentheses. If an @var{expression} refers to a previously defined
-entity, it is enclosed between braces.''
+commands can be used anywhere in a Gmsh script file. Note that the
+following general syntax rule is followed for the definition of
+geometrical entities: ``If an @var{expression} defines a new entity, it
+is enclosed between parentheses. If an @var{expression} refers to a
+previously defined entity, it is enclosed between braces.''
 
 @menu
 * Points::                      
@@ -1809,9 +1862,9 @@ set to @code{0} or @code{1} (@var{char-expression} can for example be
 @cindex Options, geometry
 @cindex Geometry, options
 
-Geometry options control the behavior of geometry commands, as well as the
-way geometrical entities are handled in the graphical user interface. For
-the signification of the `Saved in:' field in the following list, see
+Geometry options control the behavior of geometry commands, as well as
+the way geometrical entities are handled in the GUI. For the
+signification of the `Saved in:' field in the following list, see
 @ref{General options}.
 
 @include opt_geometry.texi
@@ -1906,12 +1959,12 @@ slightly different ways, depending on their capability to define groups.
 @cindex Mesh commands
 @cindex Commands, mesh
 
-The mesh module commands mostly permit to modify the characteristic lengths
-and specify structured grid parameters. The actual mesh ``actions'' (i.e.,
-``mesh the lines'', ``mesh the surfaces'' and ``mesh the volumes'') cannot
-be specified in the input ASCII text input files. They have to be given
-either in the GUI or on the command line (see @ref{Running Gmsh}, and
-@ref{Command-line options}).
+The mesh module commands mostly permit to modify the characteristic
+lengths and specify structured grid parameters. The actual mesh
+``actions'' (i.e., ``mesh the lines'', ``mesh the surfaces'' and ``mesh
+the volumes'') cannot be specified in the script files. They have to be
+given either in the GUI or on the command line (see @ref{Running Gmsh},
+and @ref{Command-line options}).
 
 @menu
 * Characteristic lengths::      
@@ -2185,8 +2238,8 @@ the moment).
 @cindex Mesh, options
 
 Mesh options control the behavior of mesh commands, as well as the way
-meshes are displayed in the graphical user interface. For the signification
-of the `Saved in:' field in the following list, see @ref{General options}.
+meshes are displayed in the GUI. For the signification of the `Saved
+in:' field in the following list, see @ref{General options}.
 
 @include opt_mesh.texi
 
@@ -2282,21 +2335,27 @@ options}):
 @cindex Graphs
 @cindex Views
 
-Gmsh's post-processing module can handle multiple scalar, vector or tensor
-data sets along with the geometry and the mesh. The data sets should be
-given in one of Gmsh's post-processing file formats described in @ref{File
-formats}. Once loaded into Gmsh, scalar fields can be displayed as iso-value
-lines and surfaces or color maps, whereas vector fields can be represented
-either by three-dimensional arrows or by displacement maps. (Tensor fields
-are currently displayed as Von-Mises effective stresses. To display other
-(combinations of) components, use @code{Plugin(Extract)}: see
-@ref{Post-processing plugins}.) 
-
-In Gmsh's jargon, each data set is called a ``view'', and can arbitrarily
-mix all types of elements and fields. Each view is given a name, and can be
-manipulated either individually (each view has its own button in the GUI and
-can be referred to by its index in a script) or globally (see the
-@code{PostProcessing.Link} option in @ref{Post-processing options}).
+Gmsh's post-processing module can handle multiple scalar, vector or
+tensor datasets along with the geometry and the mesh. The datasets can
+be given in several formats: in human-readable ``parsed'' format (these
+are just part of a standard input script, but are usually put in
+separate files with a @file{.pos} extension), in native MSH files (ASCII
+or binary files with @file{.msh} extensions: see @ref{File formats}), or
+in standard third-party formats (like MED:
+@uref{http://www.code-aster.org/outils/med/}).
+
+Once loaded into Gmsh, scalar fields can be displayed as iso-value lines
+and surfaces or color maps, whereas vector fields can be represented
+either by three-dimensional arrows or by displacement maps. (Tensor
+fields are currently displayed as Von-Mises effective stresses. To
+display other (combinations of) components, use @code{Plugin(Extract)}:
+see @ref{Post-processing plugins}.)
+
+In Gmsh's jargon, each dataset is called a ``view''. Each view is given
+a name, and can be manipulated either individually (each view has its
+own button in the GUI and can be referred to by its index in a script)
+or globally (see the @code{PostProcessing.Link} option in
+@ref{Post-processing options}).
 
 By default, Gmsh treats all post-processing views as three-dimensional
 plots, i.e., draws the scalar, vector and tensor primitives (points, lines,
@@ -2328,9 +2387,11 @@ peculiar to 3D (lightning, element selection, etc.) or 2D plots (abscissa
 labels, etc.). Note that 2D plots can be positioned explicitly inside the
 graphical window, or be automatically positioned in order to avoid overlaps.
 
-Sample post-processing files in human-readable ``parsed'' format are
-available in the @file{tutorial} directory of Gmsh's distribution
-(@file{.pos} files).
+Sample post-processing files in human-readable ``parsed'' format and in
+the native MSH file format are available in the @file{tutorial}
+directory of Gmsh's distribution (@file{.pos} and @file{.msh}
+files). The ``parsed'' format is defined in the next section (cf. the
+@code{View} command); the MSH format is defined in @ref{File formats}.
 
 @menu
 * Post-processing commands::    
@@ -2579,9 +2640,9 @@ displayed, while post-processing plugins either create new post-processing
 views, or modify the data stored in a view (in a destructive, non-reversible
 way).
 
-Plugins are available in the graphical user interface by right-clicking
-on a view button (or by clicking on the black arrow next to the view
-button) and then selecting the `Plugin' submenu.
+Plugins are available in the GUI by right-clicking on a view button (or
+by clicking on the black arrow next to the view button) and then
+selecting the `Plugin' submenu.
 
 Here is the list of the plugins that are shipped by default with Gmsh:
 
@@ -2633,12 +2694,9 @@ The nine following examples introduce new features gradually, starting with
 @file{t1.geo}. The files corresponding to these examples are available in
 the @file{tutorial} directory of the Gmsh distribution.
 
-This tutorial does not explain the mesh and post-processing file formats:
-see @ref{File formats}, for this.
-
-To learn how to run Gmsh on your computer, see @ref{Running Gmsh}. In
-addition, screencasts that show how to use the graphical user interface
-are available on @uref{http://www.geuz.org/gmsh/screencasts/}.
+To learn how to run Gmsh on your computer, see @ref{Running
+Gmsh}. Screencasts that show how to use the GUI are available on
+@uref{http://www.geuz.org/gmsh/screencasts/}.
 
 @menu
 * t1.geo::                      
@@ -2799,41 +2857,44 @@ To create a new geometry or to modify an existing geometry, select
 For example, to create a spline, select `Elementary', `Add', `New' and
 `Spline'. You will then be asked to select a list of points, and to type
 @kbd{e} to finish the selection (or @kbd{q} to abort it). Once the
-interactive command is completed, a text string is automatically added at
-the end of the current project file. You can edit this project file by hand
-at any time by pressing the `Edit' button in the `Geometry' menu and then
-reloading the project by pressing `Reload'. For example, it is often faster
-to define variables and points directly in the project file, and then use
-the graphical user interface to define the lines, the surfaces and the
+interactive command is completed, a text string is automatically added
+at the end of the current project file. You can edit this project file
+by hand at any time by pressing the `Edit' button in the `Geometry' menu
+and then reloading the project by pressing `Reload'. For example, it is
+often faster to define variables and points directly in the project
+file, and then use the GUI to define the lines, the surfaces and the
 volumes interactively.
 
-Several files can be loaded simultaneously in Gmsh. The first one defines
-the project, while the others are appended (`merged') to this project. You
-can merge such files with the `File->Merge' menu, or by directly specifying
-the names of the files on the command line. For example, to merge the
-post-processing views contained in the files @file{view1.pos} and
-@file{view2.pos} together with the geometry of the first tutorial
-@file{t1.geo}, you can type the following command:
+Several files can be loaded simultaneously in Gmsh. The first one
+defines the project, while the others are appended (`merged') to this
+project. You can merge such files with the `File->Merge' menu, or by
+directly specifying the names of the files on the command line. For
+example, to merge the post-processing views contained in the files
+@file{view1.pos} and @file{view5.msh} together with the geometry of the
+first tutorial @file{t1.geo}, you can type the following command:
 
 @example
-> gmsh t1.geo view1.pos view2.pos
+> gmsh t1.geo view1.pos view5.msh
 @end example
 
 In the Post-Processing module (select `Post-Processing' in the module
-menu), two view buttons will appear, respectively labeled `a scalar
-map' and `a vector map'. A mouse click on the name will toggle the
-visibility of the selected view, while a click on the arrow button on
-the right will provide access to the view's options. If you want the
-modifications made to one view to affect also all the other views,
-select the `Apply next changes to all views' or `Force same options
-for all views' option in the `Tools->Options->Post-processing' menu.
+menu), three view buttons will appear, respectively labeled `A scalar
+map', `Nodal scalar map' and `Element 1 vector'. These views contain
+several time steps: you can loop through them with the small
+``remote-control'' icons at the bottom of the graphic window. A mouse
+click on the name will toggle the visibility of the selected view, while
+a click on the arrow button on the right will provide access to the
+view's options. If you want the modifications made to one view to affect
+also all the other views, select the `Apply next changes to all views'
+or `Force same options for all views' option in the
+`Tools->Options->Post-processing' menu.
 
 Note that all the options specified interactively can also be directly
-specified in the ASCII input files. All available options, with their
-current values, can be saved into a file by selecting `File->Save As->Gmsh
-options', or simply viewed by pressing the `?' button in the status bar. To
-save the current options as your default preferences for all future Gmsh
-sessions, use the `Tools->Options->Save as defaults' button.
+specified in the script files. All available options, with their current
+values, can be saved into a file by selecting `File->Save As->Gmsh
+options', or simply viewed by pressing the `?' button in the status
+bar. To save the current options as your default preferences for all
+future Gmsh sessions, use the `Tools->Options->Save as defaults' button.
 
 @c -------------------------------------------------------------------------
 @c Non-interactive mode
@@ -2844,12 +2905,12 @@ sessions, use the `Tools->Options->Save as defaults' button.
 
 @cindex Non-interactive mode
 
-Gmsh's second operating mode is the non-interactive (or `batch') mode. In
-this mode, there is no graphical user interface, and all operations are
-performed without any user interaction@footnote{If you compile Gmsh without
-the graphical user interface, i.e., with @code{./configure --disable-gui},
-this is the only mode you have access to.}. For example, to mesh the first
-tutorial in non-interactive mode, just type:
+Gmsh's second operating mode is the non-interactive (or `batch')
+mode. In this mode, there is no GUI, and all operations are performed
+without any user interaction@footnote{If you compile Gmsh without the
+GUI, i.e., with @code{./configure --disable-gui}, this is the only mode
+you have access to.}. For example, to mesh the first tutorial in
+non-interactive mode, just type:
 
 @example
 > gmsh t1.geo -2
@@ -2967,10 +3028,11 @@ meshes and associated post-processing datasets. The MSH format exists in
 two flavors: ASCII and binary. The format has a version number
 (currently: 2.0) that is independent of Gmsh's main version number.
 
-(Remember that for small post-processing datasets you can also use the
-human-readable ``parsed'' format described in @ref{Post-processing
-commands}: this format does not require an underlying mesh, and is
-therefore easier to use in some cases.)
+(Remember that for small post-processing datasets you can also use
+human-readable ``parsed'' post-processing views, as described in
+@ref{Post-processing commands}. Such ``parsed'' views do not require an
+underlying mesh, and can therefore be easier easier to use in some
+cases.)
 
 @menu
 * MSH ASCII file format::       
@@ -2995,10 +3057,14 @@ information about the file (@code{$MeshFormat}), followed by several
 optional sections defining the nodes (@code{$Nodes}), elements
 (@code{$Elements}), region names (@code{$PhysicalName}) and
 post-processing datasets (@code{$NodeData}, @code{$ElementData},
-@code{$ElementNodeData}). Any section with an unrecognized header is
-simply ignored. Sections can be repeated in the same file, and
-post-processing sections can be put into separate files (e.g. one file
-per time step).
+@code{$ElementNodeData}). 
+
+Any section with an unrecognized header is simply ignored: you can thus
+add comments in a @file{.msh} file by putting them e.g. inside a
+@code{$Comments}/@code{$EndComments}) section.
+
+Sections can be repeated in the same file, and post-processing sections
+can be put into separate files (e.g. one file per time step).
 
 The format is defined as follows:
 
@@ -4093,8 +4159,8 @@ the distribution to see which problems we already know about.
 
 @itemize @bullet
 @item
-Install the `info' version of this user's guide! On your (Unix) system, this
-can be achieved by
+Install the `info' version of this reference manual! On your (Unix)
+system, this can be achieved by
 
 @enumerate
 @item
@@ -4123,7 +4189,7 @@ reset the default options, erase the @code{General.OptionsFileName}
 (usually @file{.gmsh-options} in your home directory) or use the
 `Restore default options' button in `Tools->Options->General->Output'.
 @item
-In the graphical user interface:
+In the GUI:
 
 @itemize --
 @item
diff --git a/tutorial/view1.pos b/tutorial/view1.pos
index 2405437a55..8b66ba9083 100644
--- a/tutorial/view1.pos
+++ b/tutorial/view1.pos
@@ -9,7 +9,7 @@
 // This view contains scalar triangles. There are 5 time steps,
 // i.e. 3*5 = 15 values for each triangle.
 
-View "a scalar map" {
+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};
 ST(0.056317057,0.058022103,0,0.045416206,0.061541227,0,0.048663579,0.053435419,0){3630316.8,3642820.9,3726394.8,2330872.5,2181474.8,2589713.3,197001.66,-155055.51,663071.82,-2007682.1,-2429600.5,-1465861.1,-3494460.7,-3730025.8,-3147918.6};
 ST(0.052494391,0.065958781,0,0.045416206,0.061541227,0,0.056317057,0.058022103,0){3640248,3642820.9,3630316.8,1971511.2,2181474.8,2330872.5,-601016.65,-155055.51,197001.66,-2898090,-2429600.5,-2007682.1,-3866942,-3730025.8,-3494460.7};
diff --git a/tutorial/view2.pos b/tutorial/view2.pos
index ad4f7e3c7d..f184099fb7 100644
--- a/tutorial/view2.pos
+++ b/tutorial/view2.pos
@@ -6,7 +6,7 @@
  *
  *********************************************************************/
 
-View "a vector map" {
+View "A vector map" {
 VP(1e-06,1e-06,0){0,0,122.26654,0,0,122.45426,0,0,122.82769,0,0,123.38417,0,0,124.20759};
 VP(1e-06,0.010000933,0){0,0,121.95116,0,0,120.60823,0,0,117.93735,0,0,113.96957,0,0,108.76298};
 VP(1e-06,0.020000867,0){0,0,121.76276,0,0,116.4134,0,0,105.95451,0,0,90.855892,0,0,71.867727};
diff --git a/tutorial/view3.pos b/tutorial/view3.pos
index 8ab003f4fd..0e525e600d 100644
--- a/tutorial/view3.pos
+++ b/tutorial/view3.pos
@@ -6,7 +6,7 @@
  *
  *********************************************************************/
 
-View "a 3D scalar map" {
+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};
 SS(0.88049681,0.87960137,0.13412341,1,1,0.25,1,0.70834898,0.20844998,1,0.77979347,0.00010253841){1.5518824,2.0447444,1.5291243,1.5887874};
diff --git a/tutorial/view5.msh b/tutorial/view5.msh
index 7ab339a7f8..fc6e61e459 100644
--- a/tutorial/view5.msh
+++ b/tutorial/view5.msh
@@ -3,21 +3,21 @@ $MeshFormat
 $EndMeshFormat
 $Nodes
 6
-1 0 0 0
-2 0 1 0
-3 1 0 0
-4 1 1 0
-5 2 0 0
-6 2 1 0
+1 0.0 0.0 0.0
+2 0.1 0.0 0.0
+3 0.1 0.3 0.0
+4 0.0 0.3 0.0
+5 0.0 0.15 0.0
+6 0.1 0.15 0.0
 $EndNodes
 $Elements
 2
-1 3 0 1 3 4 2
-2 3 0 3 5 6 4
+1000 3  2 6 100  1 2 6 5
+1001 3  2 6 100  5 6 3 4
 $EndElements
 $NodeData
 1
-"A 3-step scalar view"
+"Nodal scalar map"
 1
 1000.0
 3
@@ -33,7 +33,7 @@ $NodeData
 $EndNodeData
 $NodeData
 1
-"A 3-step scalar view"
+"Nodal scalar map"
 1
 2000.0
 3
@@ -49,7 +49,7 @@ $NodeData
 $EndNodeData
 $NodeData
 1
-"A 3-step scalar view"
+"Nodal scalar map"
 1
 3000.0
 3
@@ -63,31 +63,25 @@ $NodeData
 5 0
 6 0
 $EndNodeData
-$NodeData
+$ElementData
 1
-"A 2-step vector view on element 1"
+"Element 1 vector"
 1
 0.0001
 3
 0
 3
-4
-1 0.4 0.0 0.0
-2 0.5 0.2 0.0
-3 0.7 0.5 0.0
-4 0.8 0.8 0.0
-$EndNodeData
-$NodeData
 1
-"A 2-step vector view on element 1"
+1000 0.4 0.4 0.0
+$EndElememtData
+$ElementData
+1
+"Element 1 vector"
 1
 0.0002
 3
 1
 3
-4
-1 -0.4 0.0 0.0
-2 -0.5 0.2 0.0
-3 -0.7 0.5 0.0
-4 -0.8 0.8 0.0
-$EndNodeData
+1
+1000 -0.4 0.4 0.0
+$EndElementData
-- 
GitLab