== Tutorial ==

In this tutorial we will examine a number of wscript files. The first section is
the largest and builds up a complex font creation scenario from humble
beginnings. We will use the UFO sources from the Andika-Mtihani project, and call our local copy "Example". 

=== font1 - Simplicity ===
We start with a simple, single font.

[source,python,linenums]
----
include::./tutorial/font1/wscript[]
----

In line 1, we create a new font object that we want the system to build. We
specify the target filename. This file will be created in the build tree
(`results` or what is set in the `out` variable). Line 2 specifies where to find the source file. Notice that the target file is a `.ttf` file while the source is a `.ufo` file. Smith
will use the necessary commands to build from one format to the other.

With this as our `wscript` file, we can build our font:

----
smith configure
----

This is the first step in building any project. This command tells smith to set
up the build environment and search out all the programs that it may need for
the various tasks. If a necessary program is missing smith
will stop at that point and indicate an error. Some programs are not strictly
necessary and smith can run with reduced functionality without them. It will just issue a warning. Such missing programs are listed in orange. All other programs that smith searches for and
finds are listed, along with their locations, in green. So you can see exactly
which program smith will use for any particular task. This is hepful especially in
cases where you may have a locally installed self-compiled version: you can more easily
see if smith has found the version in /usr/local/ (or other local paths) instead of the stock packaged 
version.

----
smith build
----

This command tells smith to go and build all the objects the `wscript` says to
be built. In this case just the simple `Example-Regular.ttf` which will appear in
`results`. Not very exciting, but a good start.

=== font2 - Multiple fonts ===

Most font packages consist of more than one font file and this project is no
exception. Can we scale our project to handle more than one file?

[source,python,linenums]
----
include::./tutorial/font2/wscript[]
----

This example shows the power of integrating a description with a full
programming language. `wscript` files are python programs, albeit very
enhanced ones. So we can use any python-type constructs we might need. Usually
the need is slight, and we show a typical example here.

Line 1 is the start of a loop. The lines below that are indented within the loop
will be repeated for each value in the list. The first value is `-Regular` and the second is `-Bold`.
Each time around the loop, the variable `weight` is set to the appropriate string.
We will then use that variable to help set the appropriate values in the two font objects we are creating.

Each time around the loop, we create a new font object. In line 2 we create a
new font object whose target font filename is dependent on the `weight` variable
which is set to the various strings from the list at the start of the loop. So
we will end up creating two fonts. One called `Example-Regular.ttf` as before, and one
called `Example-Bold.ttf`. Line 3 gives the source files for each of these fonts.

It may seem easier just to expand out the loop and have two `font()` object
commands but, as the complexity of this `font()` grows, we will see the value of
using a loop. The advantage of adding the loop early is that we can make
appropriate use of `weight`.

Now when we come to build this project, we will get two fonts:

----
smith configure
smith build
----

=== font3 - Packaged ===

It's good that we can create multiple fonts, but what do we do with them then?
There are two typical products that people want from a font project: a `.zip`
file containing the fonts and corresponding files (with Windows line-endings CR+LF) and a tarball (with Linux/macOS line-endings LF). Smith can create these two products from a wscript, but it needs just a little more information to do so:

[source,python,linenums]
----
include::./tutorial/font3/wscript[]
----

Line 1 gives the base name of the products that will be created and line 2 gives
the version of that product. Notice that the version variable is a string and
does not have to be numeric. Case is important here, these are, in effect, magic
variables we are setting that smith looks up.

To build this project, we do the same as before, but we can also use two extra
commands:

----
smith configure
smith build
smith zip
smith tarball
----

`smith zip` will create `Example-0.0.1-dev-(git-commit-id).zip` in the `releases` folder inside the `results` folder.
_(The git-commit-id part, e.g. 66d16eM, will be the first 7 characters taken from the git revision id. We assume you are working from within a git repository.)_

`smith tarball` will create `Example-0.0.1-dev-(git-commit-id).tar.xz` in the `releases` folder inside the `results` folder.
_(The git-commit-id part, e.g. 66d16eM, will be the first 7 characters taken from the git revision id. We assume you are working from within a git repository.)_

Notice the `-dev-` suffix to indicate that these are development versions, which means they have not been tagged as a stable and tested release. 

This zip, or tarball file, contains the four target fonts the build created, since we have now added Bold and Bold-Italic as extra weights in the loop. 

We also added extra text files at the root of the project folder: `README.txt, README.md, FONTLOG.txt, OFL-FAQ.txt`. These are just text files and more documentation than font sources, but they are nice to have and will help users and other developers of your font. We will go into more detail on packaging in the dedicated section.

=== font4 - Internal processing ===

The part of the tutorial is being rewritten

=== font5 - Smarts and Basic Tests ===

The part of the tutorial is being rewritten

=== font6 - Metadata ===

The part of the tutorial is being rewritten

=== font7 - More Tests ===

The part of the tutorial is being rewritten

=== font8 - Designspace ===

This final example shows how to use the designspace() object.

[source,python,linenums]
----
include::./tutorial/font8/wscript[]
----

