2. How to read this reference manual?

Gmsh can be used at three levels:

1. as a stand-alone graphical program, driven by an interactive graphical user interface (GUI);
2. as a stand-alone script-driven program;
3. as a library.

You can skip most of this reference manual if you only want to use Gmsh at the first level (i.e., interactively with the GUI). Just read the next chapter (see section Running Gmsh on your system) to learn how to launch Gmsh on your system, then go experiment with the GUI and the tutorial files (see section Tutorial) provided in the distribution. Screencasts that show how to use the GUI are available here: 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 ‘.geo’ extension for geometry scripts, and the ‘.pos’ extension for parsed post-processing datasets. Once you master the tutorial (read the source files: they are heavily commented!), start reading chapter 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 (see section 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 Source code structure, which gives a short introduction to Gmsh's internal source code structure. Then have a look e.g. at the examples in the ‘utils/api_demos/’ directory in the source code.