Debian Codegraph @

site/tutorial/graide_tutorial1.md

raw
1 ---
2 layout: default
3 title: Unit 1
4 nav_order: 10
5 parent: Graphite Tutorial
6 grand_parent: Developers
7 ---
8
9 {: .tut-nav-bar }
10 | [▲ Contents](../graide_tutorial#contents) | [Unit 2: A very simple GDL program ▶](graide_tutorial2) |
11
12 -----
13 # Unit 1: Running, installing, and debugging with Graide
14
15 [Exercises](graide_tutorial1#exercise-1a)
16
17 ## Discussion
18
19 When you execute the Graide program with no arguments, the first step will be to create a configuration file indicating at minimum the following aspects of your project:
20
21 * Font (.TTF) file
22 * Graphite source code (.GDL) file
23
24 Other files that are used or created by Graide include:
25
26 * Configuration (.CFG) file
27 * Test data (.XML) file
28 * Debugger (.GDX) file
29 * Font compilation error message file (gdlerr.txt)
30
31 ## Exercise 1a
32
33 **Step 1.** Download the tutorial package.
34
35 [Download](../assets/resources/GraphiteTutorialPkg_v6.zip){: .btn .btn-blue }
36
37 Create or locate a workspace folder for this tutorial; this is where your fonts and source code files will go. Copy the files called **allcaps.gdl** and **DoulosGrTut.ttf** from the tutorial materials folder into that folder. Make sure the file properties are set to read-write.
38
39 **Step 2.** Run graide.exe. Choose the **Project > New Project** menu option. You will be asked for a configuration file. Navigate to your workspace folder and enter the file name as tutorial.cfg. This will create a configuration file with that name.
40
41 **Step 3.** A dialog will appear requesting other project details.
42
43 * Set the Font File to the DoulosGrTut.ttf file you copied in Step 1.
44 * Set the GDL File to the allcaps.gdl file you copied in Step 1.
45 * Set the Tests File to tutorial_tests.xml.
46
47 {: .image-tight }
48 ![Creating a Graide project](../assets/images/graide1_1_createProject.png)
49
50 <figcaption>Creating a Graide project</figcaption>
51
52 Click OK. The contents of the **allcaps.gdl** file now appears in the code (upper right-hand) pane. In the lower right-hand pane, the Font tab shows the glyphs in the **DoulosGrTut.ttf** font.
53
54 **Step 4.** Check your workspace folder. A file has been created called **tutorial.cfg**.
55
56 Once your .cfg file exists, you can indicate that Graide should use it initially by including the -p option when you start Graide: `graide -p tutorial.cfg`.
57
58 **Step 5.** Find the uppercase A in the Fonts tab (on the lower right-hand pane) and double-click on it. The left-hand pane switches to the Glyph tab and displays the information for the A glyph.
59
60 {: .image-tight }
61 ![Graide Font and Glyph tabs](../assets/images/graide1_2_glyphTab.png)
62
63 <figcaption>Graide Font and Glyph tabs </figcaption>>
64
65 **Step 6.** Build the Graphite tables into the font by clicking the gear icon associated with the code pane. In the lower pane, click on the Errors tab to double-check that there were no errors. (Normally the Error tab will be automatically brought into focus if there are errors.) You should see the text **Compilation succeeded – 0 errors, 0 warnings**. Your workspace folder should now contain a file called DoulosGrTut.gdx.
66
67 {: .image-tight }
68 ![Building a font in Graide](../assets/images/graide1_3_buildSucceed.png)
69
70 <figcaption>Building a font in Graide </figcaption>
71
72 **Step 7.** Create some test data as follows: Click on the Tests tab again. In the middle (test data) pane, type: Hello world! Click the right-pointing arrow. The bottom (test results) pane shows the results of the Graphite rendering: **HELLO WORLD!**
73
74 {: .image-tight }
75 ![Running test data in Graide](../assets/images/graide1_4_runHelloWorld.png)
76
77 <figcaption>Running test data in Graide</figcaption>
78
79 **Step 8.** Graphite will show you which rules were run in the process of rendering. In the case of this font, there is only one rule in the GDL program. If the Passes tab is not selected, click on it. Double click on the box that says **Pass: 1 - substitution**. Then double-click on any box that says **Rule: 0**. Graide will display and highlight the single rule in the code pane:
80
81 ```
82 clsLowerCase > clsUpperCase;
83 ```
84
85 {: .image-tight }
86 ![Highlighting a rule that was fired](../assets/images/graide1_5_clickRule.png)
87
88 <figcaption>Highlighting a rule that was fired</figcaption>
89
90 We will begin to learn about rules in Unit 2.
91
92 ## Exercise 1b
93
94 For the second exercise, we will deliberately introduce some errors into the **allcaps.gdl** program and discover how Graide assists in correcting them.
95
96 **Step 1.** Click on the Classes tab in the left-hand pane. Double-click on the cell labeled **clsUpperCase**. Notice how the following line is highlighted:
97
98 ```
99 clsUpperCase = codepoint(“ABCDEFGHIJKLMNOPQRSTUVWXYZ”);
100 ```
101
102 **Step 2.** Change the name of the class to clsUppercase and change the letter “L” in the codepoint function to “X”:
103
104 ```
105 clsUppercase = codepoint(“ABCDEFGHIJKXMNOPQRSTUVWXYZ”);
106 ```
107
108 (Note that the line does not need to be highlighted in order to edit it; the highlighting is simply a convenient feature of Graide.)
109
110 We have now introduced two bugs into the program: a syntactic error (incorrect class name) and a logical error (mismatch between the upper- and lower-case letters).
111
112 **Step 3.** Build the font by clicking on the gear icon. The Error tab becomes active with an error message indicating the syntax error:
113
114 **allcaps.gdl(23):error(3139): Undefined class name: clsUpperCase**
115
116 Double-click on error message, and the rule with the (now) incorrect class name is highlighted.
117
118 **Step 4.** Correct either the class definition or the rule so that the names match. Build again by clicking the gear icon. You should see a message saying **Compilation succeeded**.
119
120 **Step 5.** Click on the Tests tab in the left-hand pane. If your test data has disappeared from the middle pane, retype it: `Hello world!`. Click the right-pointing arrow icon. You will now see the result of Graphite’s rendering which includes the bug that was introduced: **HEXXO WORXD!**
121
122 **Step 6.** If you like, fix the bug in the definition of `clsUppercase`, rebuild and rerun the test to see the correct results.
123
124 {: .tut-nav-bar }
125 | [&#x25B2; Contents](../graide_tutorial#contents) | [Unit 2: A very simple GDL program &#x25B6;](graide_tutorial2) |