Ch 12: Adapt Syntax Definitions

[tajmone]

• Get @tessman approval for these changes.
• Fix document source.
• Document the changes in CHANGES.md.
• Update commented annotation in source file.

$12.2 LoadPicture() and PictureinText()

In §12.2. Pictures edited the syntax definition:

LoadPicture("resourcefile", "picture")
LoadPicture("picture")
PictureinText("file", "pic", width, height, preserve)
PictureinText("picture", width, height, preserve)

to make it consistent with the other syntax definitions:

LoadPicture("<resourcefile>", "<picture>")
LoadPicture("<picture>")

PictureinText("<file>", "<pic>", <width>, <height>[, <preserve>])
PictureinText("<picture>", <width>, <height>[, <preserve>])

NOTE — @tessman: confirm if I've got optional parameters within […] are correctly!

$12.3 PlaySound() and PlayMusic()

And, in §12.3. Sound and Music, the the syntax definition:

PlaySound(resourcefile, sample, loop, force)
PlayMusic(resourcefile, song, loop, force)

was edited to make it consistent with the other syntax definitions:

PlaySound(<resourcefile>, <sample>, <loop>, <force>)
PlayMusic(<resourcefile>, <song>, <loop>, <force>)

NOTE — @tessman: I have the impression that some of these parameters are optional and should be within […]. This might apply to other syntax definitions in this chapter, so it might be worth giving a quick look to it!

[tessman]

I wonder whether it should be or "" in all cases, for consistency. The parameter has to be a value, i.e., a variable or dictionary word, etc.

[tajmone]

How would the syntaxes become then? I'm not quite sure where the empty "" should go. Like this:

LoadPicture("<resourcefile>", "<picture>")
LoadPicture("", "<picture>")

PictureinText("<file>", "<pic>", <width>, <height>[, <preserve>])
PictureinText("", <picture>", <width>, <height>[, <preserve>])

[tessman]

Actually, you can LoadPicture("name") without specifying the resource file, in which case it will use the last-used resourcefile.

In terms of optional arguments:

PlayMusic is PlayMusic(resourcefile, songname, volume[, loop[, force]]), and
PlaySound is PlaySound(resourcefile, soundname, volume[, loop [, force]])

(both from the library).

Actually, looking at the source code, volume is also an optional argument, resulting in regular (full) volume playback.

[tajmone]

Ah! So the <volume> parameter was missing altogether from PlaySound and PlayMusic!

So, I've updated only the syntax definition of PlaySound and PlayMusic in §12.3. Sound and Music, which now are:

PlaySound(<resourcefile>, <sample>[, <volume>[, <loop>[, <force>]]])
PlayMusic(<resourcefile>, <song>[, <volume>[, <loop>[, <force>]]])

I've also peeked at resource.h from the HugoLib, and now the definition seems correct (it includes all parameters and covers correctly their optionality).

Probably the missing parameter was due to an older library version being used at the time the chapter was written.

Actually, you can LoadPicture("name") without specifying the resource file, in which case it will use the last-used resourcefile.

So, if I've understood correctly, the Picture* syntaxes were OK as they were after the first edit.

I've also updated CHANGES.md accordingly.

If you can confirm that everything is fine I can close the issue and mark the changes as approved.

[tessman]

I think that's right, yes. (And also the part about this probably being based on an earlier library version. That would require some more archaeology to determine, but it's a good guess.)