Documentation: Missing line in scripting tutorial 3

Meta
1

There’s a minor omission in the tutorial Scripting Glyphs, part 3, towards the beginning, which starts like this:

First things first. We start by entering the menu title, declare the encoding of the file, and add a short explanation:

#MenuTitle: Glyph Shaker
__doc__="""
Goes through all selected glyphs and slaps each of their nodes around a bit.
"""

The code block is missing the line that declares the encoding.

It’s clear from the image a bit further down that this line should say, # -*- coding: [encoding] -*-, but it should be there in the code block too.

(Also, the text should have parallel verb forms: “We start by entering the menu title, declaring the encoding of the file, and adding a short explanation”.)

2

I would argue it already has: start, declare and add.

3

I suppose that’s true – though I think it’s clear from the context that entering the menu title, declaring the encoding and adding the explanation are parallel actions that together make up ‘starting’.

4

You can’t really start with three things at once. You start by entering the menu title, then declare the encoding and then add a menu title.

5

Not strictly, no, but you can start with something that consists of several subtasks carried out in succession. In the context of creating a script, the menu title, encoding and description notionally belong together as ‘initial’ things that you do before you write the actual script, and thus the thing that you start out by doing; you don’t start out by giving it a menu title, and then once that task is done, you declare the encoding, write a description and write the script.

In other words, you do [menu title, encoding, description], [functionality], not [menu title], [encoding, description, functionality].

6

The scripting tutorials are in the pipeline for a rewrite. I’ll add the encoding line for now.

Parallel verb forms: It has been a while, so I do not remember for sure, but I think I intended it as Janus suggested. It’s one of these things you tend to miss in proofreading.

1 Like