/* manual_Script.c */
/* by Paul Boersma */

#include "ManPagesM.h"

void manual_Script_init (ManPages me);
void manual_Script_init (ManPages me) {

MAN_BEGIN ("Action commands", "ppgb", 19970518)
INTRO ("The commands in the @@Dynamic menu@ of the @@Object window@.")
NORMAL ("These commands are only available if the right kinds of objects are selected. They are shown in a scrollable list, "
	"or in the #Write menu if they start with \"Write to \".")
MAN_END

MAN_BEGIN ("Add action command...", "ppgb", 19970518)
INTRO ("One of the hidden commands in the Control menu of the @@Object window@. "
	"With this command, you add a button to the dynamic menu in the Object window.")
ENTRY ("Arguments")
NORMAL ("See @@Add to dynamic menu...@.")
ENTRY ("Usage")
NORMAL ("You can use this command in your @@Initialization script@, and you will see it in your @@Buttons file@ "
	"after you have added an action button with this command or with the @ScriptEditor.")
NORMAL ("Normally, however, if you want to add a command to the dynamic menu, "
	"you would use the command @@Add to dynamic menu...@ of the @ScriptEditor instead.")
MAN_END

MAN_BEGIN ("Add menu command...", "ppgb", 19970518)
INTRO ("One of the hidden commands in the Control menu of the @@Object window@. "
	"With this command, you add a button to any of the fixed menus in the Object or Picture window.")
ENTRY ("Arguments")
NORMAL ("See @@Add to fixed menu...@.")
ENTRY ("Usage")
NORMAL ("You can use this command in your @@Initialization script@, and you will see it in your @@Buttons file@ "
	"after you have added a menu button with this command or with the @ScriptEditor.")
NORMAL ("Normally, however, if you want to add a command to a fixed menu, "
	"you would use the command @@Add to fixed menu...@ of the @ScriptEditor instead.")
MAN_END

MAN_BEGIN ("Add to dynamic menu...", "ppgb", 19980105)
INTRO ("A command in the File menu of the @ScriptEditor.")
NORMAL ("With this command, you add a button to the dynamic menu in the @@Object window@. "
	"This button will only be visible if the specified combination of objects is selected. "
	"Clicking the button will invoke the specified @@Praat script@.")
ENTRY ("Arguments")
TAG ("%%Class 1")
DEFINITION ("the name of the class of the object to be selected. "
	"For instance, if a button should only appear if the user selects a Sound, this would be \"Sound\".")
TAG ("%%Number 1")
DEFINITION ("the number of objects of %class1 that have to be selected. For most built-in commands, this number is unspecified (0); "
	"e.g., the user can choose #Draw... or ##To Spectrum# regardless of whether she selected 1, 2, 3, or more Sound objects. "
	"If the number of selected objects is different from %number1, the button will be visible but insensitive.")
TAG ("%%Class 2")
DEFINITION ("the name of the class of the second object to be selected, different from %class1. "
	"Normally the empty string (\"\").")
TAG ("%%Number 2")
DEFINITION ("the number of selected objects of %class2.")
TAG ("%%Class 3")
DEFINITION ("the name of the class of the third object to be selected, different from %class1 and %class2. "
	"Normally the empty string (\"\").")
TAG ("%%Number 3")
DEFINITION ("the number of selected objects of %class3.")
TAG ("%%Command")
DEFINITION ("the title of the new command button (or label, or submenu title). "
	"To get a separator line instead of a command text (only in a submenu), "
	"you specify a unique string that starts with a hyphen ('-'); the @ButtonEditor may contain some examples of this. "
	"If the command starts with \"Write to \", it will be placed in the @@Write menu@.")
TAG ("%%After command")
DEFINITION ("a button title in the dynamic menu or submenu where you want your new button. "
	"If you specify the empty string (\"\"), your button will be put at the bottom. "
	"You can specify a push button, a label (subheader), or a cascade button (submenu title) here.")
TAG ("%%Depth")
DEFINITION ("0 if you want your button in the main menu, 1 if you want it in a submenu.")
TAG ("%%Script")
DEFINITION ("the full path name of the script to invoke. If you saved the script you are editing, "
	"its name will already have been filled in here. "
	"If you do not specify a script, you will get a separating label or cascading menu title instead, "
	"depending on the %depth of the following command.")
ENTRY ("Example")
NORMAL ("If one object of class Sound is selected, you want a submenu called \"Filters\" "
	"after the #Convolve button, containing the commands \"Autocorrelation\" and \"Band filter...\", "
	"separated by a horizontal separator line:")
CODE ("Add to dynamic menu... Sound 0 \"\" 0 \"\" 0 \"Filters -\" \"Convolve\" 0")
CODE ("Add to dynamic menu... Sound 1 \"\" 0 \"\" 0 \"Autocorrelation\" \"Filters -\" 1 /u/praats/demo/autocorrelation.praat")
CODE ("Add to dynamic menu... Sound 0 \"\" 0 \"\" 0 \"-- band filter --\" \"Autocorrelation\" 1")
CODE ("Add to dynamic menu... Sound 1 \"\" 0 \"\" 0 \"Band filter...\" \"-- band filter --\" 1 /u/praats/demo/bandFilter.praat")
NORMAL ("Note that \"Filters -\" will be a submenu title, %because it is followed by subcommands (%depth 1). "
	"Note that %number1 is 1 only for the executable buttons; for the cascade button and the separator line, "
	"this number is ignored.")
ENTRY ("Usage convention")
NORMAL ("Please adhere to the convention that commands that take arguments, end in three dots (...).")
ENTRY ("Using this command in a script")
NORMAL ("To add a dynamic button from a script (perhaps your @@Initialization script@), "
	"use the hidden shell command @@Add action command...@ instead.")
MAN_END

MAN_BEGIN ("Add to fixed menu...", "ppgb", 19971006)
INTRO ("A command in the File menu of the @ScriptEditor.")
NORMAL ("With this command, you add a button to any fixed menu in the @@Object window@ or in the @@Picture window@. "
	"Clicking the added button will invoke the specified @@Praat script@.")
ENTRY ("Arguments")
TAG ("%Window")
DEFINITION ("the name of the window (\"Objects\" or \"Picture\") that contains the menu that you want to change.")
TAG ("%Menu")
DEFINITION ("the title of the menu that you want to change. If %window is \"Objects\", you can specify "
	"the Control, New, Read, Help, Goodies, or Preferences menu (for the Write menu, which depends on the objects selected, "
	"you would use @@Add to dynamic menu...@ instead). If %window is \"Picture\", you can specify "
	"the File, Edit, Margins, World, Select, Pen, Font, or Help menu.")
TAG ("%Command")
DEFINITION ("the title of the new menu button. To get a separator line instead of a command text, "
	"you specify a unique string that starts with a hyphen ('-'); the @ButtonEditor contains many examples of this.")
TAG ("%%After command")
DEFINITION ("a button title in the menu or submenu after which you want your new button to be inserted. "
	"If you specify the empty string (\"\"), your button will be put in the main menu.")
TAG ("%Depth")
DEFINITION ("0 if you want your button in the main menu, 1 if you want it in a submenu.")
TAG ("%Script")
DEFINITION ("the full path name of the script to invoke. If you saved the script you are editing, "
	"its name will already have been filled in here. If you do not specify a script, "
	"you will get a cascading menu title instead.")
ENTRY ("Example 1")
NORMAL ("In the #Matrix submenu of the #New menu, you want a separator line followed by the command \"Peaks\":")
CODE ("Add to fixed menu... Objects New \"-- peaks --\" \"Create simple Matrix...\" 1")
CODE ("Add to fixed menu... Objects New \"Peaks\" \"-- peaks --\" 1 /u/praats/demo/peaks.praat")
ENTRY ("Example 2")
NORMAL ("In the #New menu, you want a submenu called \"Demo\", with a subitem titled \"Lorenz...\":")
CODE ("Add to fixed menu... Objects New \"Demo\" \"\" 0")
CODE ("Add to fixed menu... Objects New \"Lorenz...\" \"Demo\" 1 /u/praats/demo/lorentz.praat")
ENTRY ("Usage convention")
NORMAL ("Please adhere to the convention that commands that take arguments, end in three dots (...).")
ENTRY ("Using this command in a script")
NORMAL ("To add a fixed button from a script (perhaps your @@Initialization script@), "
	"use the hidden shell command @@Add menu command...@ instead.")
MAN_END

MAN_BEGIN ("binomialQ", "ppgb", 20011021)
INTRO ("A function that can be used in @@numerical expressions@. The complement of the cumulative binomial distribution.")
ENTRY ("Syntax")
TAG ("$$binomialQ (%p, %k, %n)")
DEFINITION ("the probability that in %n trials an event with probability %p will occur at least %k times.")
ENTRY ("Calculator example")
NORMAL ("A die is suspected to yield more sixes than a perfect die would do. In order to test this suspicion, "
	"you throw it 1,000 times. The result is 211 sixes.")
NORMAL ("The probability that a perfect die yields at least 211 sixes is, according to @@Calculator...@, "
	"$$binomialQ (1/6, 211, 1000)$ = 0.000152.")
ENTRY ("Script example")
NORMAL ("You convert 1000 values of pitch targets in Hz to the nearest note on the piano keyboard. "
	"597 of those values turn out to be in the A, B, C, D, E, F, or G regions (the white keys), and 403 values turn out "
	"to be in the A\\# , C\\# , D\\# , F\\# , or G\\#  regions (the black keys). "
	"Do our subjects have a preference for the white keys? "
	"The following script computes the probability that in the case of no preference the subjects "
	"would target the white keys at least 597 times. This is compared with a %\\ci^2 test.")
CODE ("a = 597")
CODE ("b = 403")
CODE ("p = 7/12 ; no preference")
CODE ("echo *** Binomial test 'a', 'b', p = 'p:6' ***")
CODE ("pbin = binomialQ (p, a, a+b)")
CODE ("printline P (binomial) = 'pbin:6'")
CODE ("\\#  Chi-square test with Yates correction:")
CODE ("x2 = (a - 1/2 - p * (a+b))\\^ 2/(p*(a+b)) + (b + 1/2 - (1-p) * (a+b))\\^ 2/((1-p)*(a+b))")
CODE ("px2 = chiSquareQ (x2, 1)")
CODE ("printline P (chi-square) = 'px2:6'")
NORMAL ("The result is:")
CODE ("*** Binomial test 597, 403, p = 0.583333 ***")
CODE ("P (binomial) = 0.199330")
CODE ("P (chi-square) = 0.398365")
NORMAL ("The %\\ci^2 test is two-sided (it signals a preference for the white or for the black keys), "
	"so it has twice the probability of the binomial test.")
NORMAL ("We cannot conclude from this test that people have a preference for the white keys. "
	"Of course, we cannot conclude either that people do not have such a preference.")
MAN_END

MAN_BEGIN ("ButtonEditor", "ppgb", 19980121)
INTRO ("An editor for viewing, hiding, showing, removing, and executing the commands "
	"in the fixed and dynamic menus of the @@Praat shell@. To open it, choose ##Buttons...# "
	"from the #Control menu of the @@Object window@.")
ENTRY ("What the button editor shows")
NORMAL ("The button editor gives a list of:")
LIST_ITEM ("1. The five fixed buttons.")
LIST_ITEM ("2. The built-in and added @@fixed menu commands@, lexicographically sorted by window and menu name.")
LIST_ITEM ("3. The built-in and added @@action commands@, sorted by the names of the selected objects.")
ENTRY ("Visibility of built-in commands")
NORMAL ("Most built-in commands are visible by default, but some are hidden by default (see @@Hidden commands@). "
	"The button editor shows these commands as \"shown\" or \"hidden\", respectively. "
	"You can change the visibility of a command by clicking on the blue \"shown\" or \"hidden\" text; "
	"this text will then be replaced with \"HIDDEN\" or \"SHOWN\", with capitals to signal their non-default settings. "
	"These changes will be remembered in the @@Buttons file@ across sessions of your program. "
	"To return to the default settings, click the blue \"HIDDEN\" or \"SHOWN\" texts again.")
NORMAL ("Some built-in commands cannot be hidden. They are marked as \"unhidable\". "
	"The most notable example is the ##Buttons...# button "
	"(a failure to make the ##Commands...# command unhidable in Microsoft Word "
	"causes some computer viruses to be very hard to remove...).")
ENTRY ("Added commands")
NORMAL ("Commands that you have added to the fixed or dynamic menus (probably with @@Add to fixed menu...@ or "
	"@@Add to dynamic menu...@ in the @ScriptEditor), "
	"are marked as \"ADDED\". They are remembered in the @@Buttons file@. "
	"You can change the availability of these commands by clicking on the blue \"ADDED\" text, which will then "
	"be replaced with \"REMOVED\". After this, the added command will no longer be remembered in the @@Buttons file@. "
	"To make the command available again, click the blue \"REMOVED\" text again, before leaving the program.")
ENTRY ("Start-up commands")
NORMAL ("Commands that were added in an @@Initialization script@ (with @@Add menu command...@ or "
	"@@Add action command...@) are marked as \"START-UP\". "
	"They are %not remembered in the @@Buttons file@. "
	"You can change the visibility of these commands by clicking on the blue \"START-UP\" text, which will then "
	"be replaced with \"HIDDEN\". This setting %will be remembered in the @@Buttons file@. "
	"To make the command visible again, click the blue \"HIDDEN\" text again.")
ENTRY ("Executing commands")
NORMAL ("The button editor allows you to choose hidden commands without first making them visible in the fixed or dynamic menus.")
NORMAL ("The editor shows all the executable commands in blue. These include:")
LIST_ITEM ("1. The fixed #Remove button, if one or more objects are selected in the @@List of Objects@.")
LIST_ITEM ("2. The other fixed buttons, if exactly one object is selected.")
LIST_ITEM ("3. All of the fixed menu commands, hidden or not, and \"removed\" or not.")
LIST_ITEM ("4. Those action commands that match the currently selected objects with respect to class and number.")
NORMAL ("To execute any of these blue commands, just click on it.")
MAN_END

MAN_BEGIN ("Buttons file", "ppgb", 19971006)
NORMAL ("The file into which changes in the availability and visibility of commands in the fixed "
	"and dynamic menus of your program are recorded. ")
NORMAL ("The buttons file is written to disk when you leave the program, "
	"and it is read when you enter the program. It is a simple @@Praat script@ that you can read "
	"(but should not edit) with any text editor.")
ENTRY ("Adding buttons")
NORMAL ("To add a command to a fixed or dynamic menu, you typically use the @ScriptEditor.")
ENTRY ("Removing buttons")
NORMAL ("To remove an added command from a fixed or dynamic menu, you typically use the @ButtonEditor.")
ENTRY ("Hiding and showing buttons")
NORMAL ("To hide a built-in command from a fixed or dynamic menu, or to make a hidden command visible, "
	"you typically use the @ButtonEditor.")
ENTRY ("Unix")
NORMAL ("If your home directory is /people/miep, and your program is called surfer, "
	"the buttons file is /people/miep/.surfer-dir/buttons. "
	"If the directory .surfer-dir does not exist, it is created when you enter your program.")
ENTRY ("Macintosh")
NORMAL ("If your program is called Surfer, the buttons file, which is called \"Buttons\", "
	"will be in a folder named \"Surfer Preferences\" in the Preferences folder in your System Folder. "
	"If your hard disk is called \"H\\ael' sji'f\", and you have a Dutch system, "
	"the complete path to your preferences file is:")
CODE ("H\\ael' sji'f:Systeemmap:Voorkeuren:Surfer Preferences:Buttons")
NORMAL ("Suggestion: "
	"If you are a teacher, you can supply your students with a stripped version of Praat "
	"in the following way:")
LIST_ITEM ("1. Create a student copy of the executable:")
CODE ("cp bin/praat bin/praat_student")
LIST_ITEM ("2. Launch praat_student and hide some buttons.")
LIST_ITEM ("3. Leave praat_student. Your button settings are remembered in your "
	"/users/Miep/praat_student-dir/buttons file.")
LIST_ITEM ("4. Make sure that your students run praat_student, not praat, "
	"and put a link to your buttons file in their praat_student-dir directories.")
LIST_ITEM ("5. During the course, you can increase the accessibility of Praat to your students "
	"by entering Praat and make some of the hidden buttons visible again.")
MAN_END

MAN_BEGIN ("Calculator...", "ppgb", 19980319)
INTRO ("A mathematical calculator, found in the Control menu of the @@Object window@. "
	"You can type all kinds of simple or complicated @@Numerical expressions@.")
MAN_END

MAN_BEGIN ("Clear history", "ppgb", 20000927)
INTRO ("A command in the Edit menu of the @ScriptEditor for clearing the remembered history. "
	"See @@History mechanism@.")
MAN_END

MAN_BEGIN ("Fixed menu commands", "ppgb", 19970518)
INTRO ("The commands in the fixed menus of the @@Object window@ (#Control, #New, #Read, #Help, #Goodies, "
	"and #Preferences) and the @@Picture window@ (#File, #Edit, #Margins, #World, #Select, #Pen, #Font, #Help).")
NORMAL ("These commands are always clickable (if not hidden) and scriptable (if not added).")
MAN_END

MAN_BEGIN ("Hidden commands", "ppgb", 19970518)
NORMAL ("Some commands in the fixed and dynamic menus of the @@Praat shell@ are hidden by default. "
	"You can still call hidden commands from scripts, run them by clicking on them in a @ButtonEditor, "
	"or make them visible with the help of the @ButtonEditor.")
NORMAL ("To hide commands that are visible by default, use the @ButtonEditor.")
ENTRY ("What commands are hidden by default?")
NORMAL ("Commands that are expected to be of very limited use, are hidden by default. Examples are:")
LIST_ITEM ("1. The commands @@Add menu command...@, ##Hide menu command...#, ##Show menu command...#, "
	"@@Add action command...@, ##Hide action command...#, and ##Show action command...# in the #Control menu "
	"of the @@Object window@. These are used in the @@Buttons file@ and could be used by an @@Initialization script@ "
	"as well; in an interactive session, however, the functionality of these commands is part of the "
	"@ScriptEditor and the @ButtonEditor.")
LIST_ITEM ("2. The command ##Read from old Praat picture file...# in the #File menu of the @@Picture window@. "
	"For reading a file format that was in use before May, 1995.")
LIST_ITEM ("3. In the Praat program, the action ##Sound: Write to Sesam file...#. Writes a file format in common use "
	"in the Netherlands on Vax machines. In the Dutch phonetics departments, the plugs were pulled from the Vaxes in 1994.")
LIST_ITEM ("4. In the Praat program, the action ##Sound: To Cochleagram (edb)...#. Needed by one person in 1994. "
	"An interesting, but undocumented procedure (De Boer's gamma-tone filter bank plus Meddis & Hewitt's "
	"synapse model), which does not create a normally interpretable Cochleagram object.")
MAN_END

MAN_BEGIN ("History mechanism", "ppgb", 19991023)
INTRO ("The easiest way of @@scripting@. "
	"The %history is the sequence of all mouse clicks on menu commands "
	"(in the Objects or Picture window or in the editors), "
	"action commands (in the dynamic menu), "
	"or objects (in the list of objects), that you performed during your Praat session, "
	"together with the arguments that you specified in the dialog windows "
	"that popped up as a result of those clicks.")
ENTRY ("Viewing the history")
NORMAL ("You view your history in a @ScriptEditor (which you can create with @@New script@ "
	"or @@Open script...@) by choosing @@Paste history@ from its Edit menu.")
ENTRY ("Recording a macro")
NORMAL ("To record a sequence of mouse clicks for later re-use, "
	"perform the following steps:")
LIST_ITEM ("1. Choose @@Clear history@ from the Edit menu. "
	"This makes the history mechanism forget all previous clicks.")
LIST_ITEM ("2. Perform the actions that you want to record.")
LIST_ITEM ("3. Choose @@Paste history@ from the Edit menu. Because you cleared the history "
	"before you started, the resulting script contains only the actions "
	"that you performed in step 2. "
	"You can now already re-run the actions that you performed in step 2.")
LIST_ITEM ("4. You can save the recorded actions to a script by choosing #Save from the File menu.")
LIST_ITEM ("5. You can put this script under a button in the @@dynamic menu@ "
	"by choosing @@Add to dynamic menu...@ from the File menu, "
	"or under a button in a fixed menu by choosing @@Add to fixed menu...@. "
	"This button will be preserved across Praat sessions.")
NORMAL ("This macro mechanism is much more flexible than the usual opaque mechanism "
	"used by most programs, because you can edit the script and make some "
	"of the arguments variable by putting them in the #form clause at the top of the script. "
	"In this way, the script will prompt the user for these arguments, "
	"just as with all the menu and action commands that end in the three dots (...). "
	"See the @Scripting tutorial for all the things that you can do in scripts.")
MAN_END

MAN_BEGIN ("Initialization script", "ppgb", 19971006)
INTRO ("Your initialization script is a normal @@Praat script@ "
	"that is run as soon as you start Praat.")
NORMAL ("You create an initialization script by creating a file named \"/usr/local/praat-startUp\", "
	"or putting a file \".praat-user-startUp\" or \"praat-user-startUp\" in your home directory, "
	"if your program is called Praat. If your program is called Ldb, it is \"/usr/local/ldb-startUp\" etc.")
NORMAL ("If you have more than one of these files, they are run in the above order.")
ENTRY ("Example")
NORMAL ("If you like to be greeted by your husband when Praat starts up, "
	"you could put the following lines in your initialization script:")
CODE ("\\#  This works if you have the Praat phonetics library:")
CODE ("Read from file... /u/miep/halloMiep.aifc")
CODE ("Play")
CODE ("Remove")
CODE ("\\#  Otherwise, this would work on SGI:")
CODE ("unix sfplay /u/miep/halloMiep.aifc")
ENTRY ("What not to use an initialization script for")
NORMAL ("You could set preferences like the default font in your initialization script, "
	"but these will be automatically remembered between invocations of Praat anyway (in your @@Preferences file@), "
	"so this would often be superfluous. Added and removed commands are also remembered across "
	"Praat sessions (in your @@Buttons file@), but you may want to call a changeable list of them.")
ENTRY ("Using an initialization script for site-wide customization")
NORMAL ("If your research group shares a number of Praat scripts, these can be included in everybody's "
	"version of the program in the following way:")
LIST_ITEM ("1. Create a script that adds buttons to the fixed and dynamic menus, using the commands "
	"@@Add menu command...@ and @@Add action command...@. This script could be a slightly edited copy of someone's "
	"@@Buttons file@.")
LIST_ITEM ("2. Put this script in \"/usr/local/%%myProg%-startUp\", or have everyone call this script "
	"from her start-up file (with @@Run script...@).")
NORMAL ("This procedure allows all members of the group to automatically enjoy all the later changes in the "
	"custom command set.")
MAN_END

MAN_BEGIN ("Numerical expressions", "ppgb", 20000316)
INTRO ("You can use the following operators, constants, functions, and control structures "
	"in a @@Praat script@ or with @@Calculator...@.")

ENTRY ("Operators")
NORMAL ("In order of decreasing precedence:")
TAG ("$$( )  (,)  [ ]  [,]")
DEFINITION ("parentheses and brackets")
TAG ("$$-  \\^ ")
DEFINITION ("negation and exponentiation, from right to left (2\\^ -6 = 0.015625; -2\\^ 6 = -64)")
TAG ("$$*  /  div  mod")
DEFINITION ("multiplication and division, from left to right (%div and %mod yield integers)")
TAG ("$$+  -")
DEFINITION ("addition and subtraction, from left to right")
TAG ("$$=  ==  !=  <>  <  >  <=  >=")
DEFINITION ("comparison; = and == mean %equal; != and <> mean %unequal;")
DEFINITION ("these operators always yield 0 (%false) or 1 (%true)")
TAG ("$$not")
DEFINITION ("logical negation")
TAG ("$$and")
DEFINITION ("logical %and")
TAG ("$$or")
DEFINITION ("logical %or")

ENTRY ("Constants")
TAG ("$$pi")
DEFINITION ("%\\pi, 3.14159265358979323846")
TAG ("$$e")
DEFINITION ("%e, 2.7182818284590452354")
TAG ("$$undefined")
DEFINITION ("a special value, see @undefined")

ENTRY ("Functions")
TAG ("$$abs (%x)")
DEFINITION ("absolute value")
TAG ("$$round (%x)")
DEFINITION ("nearest integer; round (1.5) = 2")
TAG ("$$floor (%x)")
DEFINITION ("round down: highest integer value not greater than %x")
TAG ("$$ceiling (%x)")
DEFINITION ("round up: lowest integer value not less than %x")
TAG ("$$sqrt (%x)")
DEFINITION ("square root: \\Vr%x, %x \\>_ 0")
TAG ("$$sin (%x)")
DEFINITION ("sine")
TAG ("$$cos (%x)")
DEFINITION ("cosine")
TAG ("$$tan (%x)")
DEFINITION ("tangent")
TAG ("$$arcsin (%x)")
DEFINITION ("arcsine, -1 \\<_ %x \\<_ 1")
TAG ("$$arccos (%x)")
DEFINITION ("arccosine, -1 \\<_ %x \\<_ 1")
TAG ("$$arctan (%x)")
DEFINITION ("arctangent")
TAG ("$$arctan2 (%y, %x)")
DEFINITION ("argument angle")
TAG ("$$exp (%x)")
DEFINITION ("exponentiation: %e^%x; same as $$e\\^ %x")
TAG ("$$ln (%x)")
DEFINITION ("natural logarithm, base %e")
TAG ("$$log10 (%x)")
DEFINITION ("logarithm, base 10")
TAG ("$$log2 (%x)")
DEFINITION ("logarithm, base 2")
TAG ("$$sinh (%x)")
DEFINITION ("hyperbolic sine: (%e^%x - %e^^-%x^) / 2")
TAG ("$$cosh (%x)")
DEFINITION ("hyperbolic cosine: (%e^%x + %e^^-%x^) / 2")
TAG ("$$tanh (%x)")
DEFINITION ("hyperbolic tangent: sinh (%x) / cosh (%x)")
TAG ("$$arcsinh (%x)")
DEFINITION ("inverse hyperbolic sine: ln (%x + \\Vr(1+%x^2))")
TAG ("$$arccosh (%x)")
DEFINITION ("inverse hyperbolic cosine: ln (%x + \\Vr(%x^2\\--1))")
TAG ("$$arctanh (%x)")
DEFINITION ("inverse hyperbolic tangent")
TAG ("$$sigmoid (%x)")
DEFINITION ("#R \\-> (0,1): 1 / (1 + %e^^\\--%x^) or 1 \\-- 1 / (1 + %e^%x)")
TAG ("$$erf (%x)")
DEFINITION ("the error function: 2/\\Vr%\\pi __0_\\in^%x exp(-%t^2) %dt")
TAG ("$$erfc (%x)")
DEFINITION ("the complement of the error function: 1 - erf (%x)")
TAG ("$$randomUniform (%min, %max)")
DEFINITION ("uniform random deviate between %min (inclusive) and %max (exclusive)")
TAG ("$$randomInteger (%min, %max)")
DEFINITION ("uniform random deviate between %min and %max (inclusive)")
TAG ("$$randomGauss (%\\mu, %\\si)")
DEFINITION ("Gaussian random deviate with mean %\\mu and standard deviation %\\si")
TAG ("$$randomPoisson (%mean)")
DEFINITION ("Poisson random deviate")
TAG ("$$lnGamma (%x)")
DEFINITION ("logarithm of the \\Ga function")
TAG ("$$gaussP (%z)")
DEFINITION ("the area under the Gaussian distribution between \\--\\oo and %z")
TAG ("$$gaussQ (%z)")
DEFINITION ("the area under the Gaussian distribution between %z and +\\oo: "
	"the one-tailed \"statistical significance %p\" of a value that is %z standard deviations "
	"away from the mean of a Gaussian distribution")
TAG ("$$invGaussQ (%q)")
DEFINITION ("the value of %z for which $gaussQ (%z) = %q")
TAG ("$$chiSquareP (%chiSquare, %df)")
DEFINITION ("the area under the %\\ci^2 distribution between 0 and %chiSquare, for %df degrees of freedom")
TAG ("$$chiSquareQ (%chiSquare, %df)")
DEFINITION ("the area under the %\\ci^2 distribution between %chiSquare and +\\oo, "
	"for %df degrees of freedom: the \"statistical significance %p\" "
	"of the %\\ci^2 difference between two distributions in %df+1 dimensions")
TAG ("$$invChiSquareQ (%q, %df)")
DEFINITION ("the value of %\\ci^2 for which $chiSquareQ (%\\ci^2, %df) = %q")
TAG ("$$studentP (%t, %df)")
DEFINITION ("the area under the student T-distribution from -\\oo to %t")
TAG ("$$studentQ (%t, %df)")
DEFINITION ("the area under the student T-distribution from %t to +\\oo")
TAG ("$$invStudentQ (%q, %df)")
DEFINITION ("the value of %t for which $studentQ (%t, %df) = %q")
TAG ("$$fisherP (%f, %df1, %df2)")
DEFINITION ("the area under Fisher's F-distribution from 0 to %f")
TAG ("$$fisherQ (%f, %df1, %df2)")
DEFINITION ("the area under Fisher's F-distribution from %f to +\\oo")
TAG ("$$invFisherQ (%q, %df1, %df2)")
DEFINITION ("the value of %f for which $fisherQ (%f, %df1, %df2) = %q")
TAG ("$$binomialP (%p, %k, %n)")
DEFINITION ("the probability that in %n experiments, an event with probability %p will occur at most %k times")
TAG ("@binomialQ (%p, %k, %n)")
DEFINITION ("the probability that in %n experiments, an event with probability %p will occur at least %k times; equals 1 - $binomialP (%p, %k - 1, %n)")
TAG ("$$invBinomialP (%P, %k, %n)")
DEFINITION ("the value of %p for which $binomialP (%p, %k, %n) = %P")
TAG ("$$invBinomialQ (%Q, %k, %n)")
DEFINITION ("the value of %p for which $binomialQ (%p, %k, %n) = %Q")
TAG ("$$hertzToBark (%x)")
DEFINITION ("from acoustic frequency to Bark-rate (perceptual spectral frequency; place on basilar membrane): "
	"7 ln (%x/650 + \\Vr(1 + (%x/650)^2))")
TAG ("$$barkToHertz (%x)")
DEFINITION ("650 sinh (%x / 7)")
TAG ("$$hertzToMel (%x)")
DEFINITION ("from acoustic frequency to perceptual pitch: 550 ln (1 + %x / 550)")
TAG ("$$melToHertz (%x)")
DEFINITION ("550 (exp (%x / 550) - 1)")
TAG ("$$hertzToSemitones (%x)")
DEFINITION ("from acoustic frequency to a logarithmic musical scale, relative to 100 Hz: 12 ln (%x / 100) / ln 2")
TAG ("$$semitonesToHertz (%x)")
DEFINITION ("100 exp (%x ln 2 / 12)")
TAG ("$$erb (%f)")
DEFINITION ("the perceptual %%equivalent rectangular bandwidth% (ERB) in Hertz, for a specified acoustic frequency (also in Hertz): "
	"6.23\\.c10^^-6^ %f^2 + 0.09339 %f + 28.52")
TAG ("$$hertzToErb (%x)")
DEFINITION ("from acoustic frequency to ERB-rate: 11.17 ln ((%x + 312) / (%x + 14680)) + 43")
TAG ("$$erbToHertz (%x)")
DEFINITION ("(14680 %d - 312) / (1 - %d) where %d = exp ((%x - 43) / 11.17)")
TAG ("$$beta (%x, %y)")
TAG ("$$besselJ (%n, %x)")
TAG ("$$besselY (%n, %x)")
TAG ("$$besselI (%n, %x)")
TAG ("$$besselK (%n, %x)")

ENTRY ("Control: if ... then ... else ... fi")
CODE ("if %expression__1_ then %expression__2_ else %expression__3_ fi")
CODE ("if %expression__1_ then %expression__2_ else %expression__3_ endif")
NORMAL ("If %expression__1_ evaluates as zero, the result is %expression__3_; "
	"otherwise, the result is %expression__2_.")
NORMAL ("#Example. A peak clipper:")
CODE ("if abs(self)>100 then if self>0 then 100 else -100 fi else self fi")

ENTRY ("Control: the semicolon (;)")
NORMAL ("The semicolon ends the evaluation of the formula. This can be convenient "
	"if you do not want to overwrite a long formula in your text field: the formula")
CODE ("800;sqrt(2)*sin(2*pi*103*0.5)+10\\^ (-40/20)*randomGauss(0,1)")
NORMAL ("evaluates to 800.")

MAN_END

MAN_BEGIN ("New script", "ppgb", 19980825)
INTRO ("A command in the Control menu for creating a new Praat script. "
	"It creates a @ScriptEditor with an empty script that you can edit, run, and save.") 
MAN_END

MAN_BEGIN ("Open script...", "ppgb", 19980825)
INTRO ("A command in the Control menu for editing an existing @@Praat script@. "
	"It creates a @ScriptEditor and asks "
	"you to select a file. If you click #%OK, the file is read into the ScriptEditor window, "
	"and you can run and edit it; if you click #%Cancel, you get an empty script, as with @@New script@.") 
MAN_END

MAN_BEGIN ("Paste history", "ppgb", 19981107)
INTRO ("A command in the Control menu for viewing the history in a @ScriptEditor. "
	"See @@History mechanism@.")
MAN_END

MAN_BEGIN ("Praat script", "ppgb", 19980824)
INTRO ("An executable text that consists of menu commands and action commands.")
NORMAL ("See the @Scripting tutorial.")
MAN_END

MAN_BEGIN ("Preferences file", "ppgb", 19970518)
NORMAL ("The file into which some of your preferences are saved across sessions of the Praat shell. "
	"For instance, if you change the font used by the Picture window to Palatino and leave the program, "
	"the Picture-window font will still be Palatino when you enter the program again.")
NORMAL ("The preferences file is written to disk when you leave the program, "
	"and it is read when you enter the program. It is a simple text file that you can read "
	"(but should not edit) with any text editor.")
ENTRY ("Unix")
NORMAL ("If your home directory is /people/miep, and your program is called surfer, "
	"the preferences file is /people/miep/.surfer-dir/prefs. "
	"If the directory .surfer-dir does not exist, it is created when you enter your program.")
ENTRY ("Macintosh")
NORMAL ("If your program is called Surfer, the preferences file, which is called \"Preferences\", "
	"will be in a folder named \"Surfer Preferences\" in the Preferences folder in your System Folder. "
	"If your hard disk is called \"H\\ael' sji'f\", and you have a Dutch system, "
	"the complete path to your preferences file is:")
CODE ("H\\ael' sji'f:Systeemmap:Voorkeuren:Surfer Preferences:Preferences")
MAN_END

MAN_BEGIN ("Run script...", "ppgb", 19971012)
INTRO ("A hidden command in the #%Control menu of the @@Object window@. "
	"Runs a @@Praat script@.")
ENTRY ("Usage")
NORMAL ("This command is hidden because you would normally open a script "
	"with @@Open script...@, so that you can run it several times without "
	"selecting a file each time.")
NORMAL ("In scripts, the command ##%%Run script...#% is automatically replaced "
	"by the script directive #execute.")
MAN_END

MAN_BEGIN ("Scripting", "ppgb", 20000301)
INTRO ("This is one of the tutorials of the @@Praat shell@.")
NORMAL ("A %script is a text that consists of menu commands and action commands. "
	"If you %run the script (perhaps from a @ScriptEditor), "
	"the commands are executed as if you clicked on them.")
NORMAL ("You can read this tutorial sequentially with the help of the \"< 1\" and \"1 >\" buttons.")
LIST_ITEM ("1. @@Scripting 1. My first script|My first script@ (how to create, how to run)")
LIST_ITEM ("2. @@Scripting 2. Arguments to commands|Arguments to commands@ (numeric, check, radio, text, file)")
LIST_ITEM ("3. @@Scripting 3. Layout|Layout@ (white space, comments, continuation lines)")
LIST_ITEM ("4. @@Scripting 4. Object selection|Object selection@ (selecting and querying)")
LIST_ITEM ("5. @@Scripting 5. Language elements|Language elements")
LIST_ITEM1 ("5.1. @@Scripting 5.1. Variables|Variables@ (numeric, string, copy, expansion)")
LIST_ITEM1 ("5.2. @@Scripting 5.2. Expressions|Expressions@ (numeric, string)")
LIST_ITEM1 ("5.3. @@Scripting 5.3. Jumps|Jumps@ (if, then, elsif, else, endif)")
LIST_ITEM1 ("5.4. @@Scripting 5.4. Loops|Loops@ (for/endfor, while/endwhile, repeat/until)")
LIST_ITEM1 ("5.5. @@Scripting 5.5. Procedures|Procedures@ (call, procedure)")
LIST_ITEM1 ("5.6. @@Scripting 5.6. Arrays|Arrays@")
LIST_ITEM1 ("5.7. @@Scripting 5.7. Quitting|Quitting@ (exit)")
LIST_ITEM ("6. @@Scripting 6. Communication outside the script|Communication outside the script")
LIST_ITEM1 ("6.1. @@Scripting 6.1. Arguments to the script|Arguments to the script@ (form/endform, execute)")
LIST_ITEM1 ("6.2. @@Scripting 6.2. Calling system commands|Calling system commands@ (system, system_nocheck)")
LIST_ITEM1 ("6.3. @@Scripting 6.3. Writing to the Info window|Writing to the Info window@ (echo, print, printtab, printline)")
LIST_ITEM1 ("6.4. @@Scripting 6.4. Query commands|Query commands@ (Get, Count)")
LIST_ITEM1 ("6.5. @@Scripting 6.5. Files|Files@ (fileReadable, <, >, >>, filedelete, fileappend)")
LIST_ITEM1 ("6.6. @@Scripting 6.6. Controlling the user|Controlling the user@ (pause)")
LIST_ITEM1 ("6.7. @@Scripting 6.7. Sending a message to another program|Sending a message to another program@ (sendsocket)")
LIST_ITEM1 ("6.8. @@Scripting 6.8. Error message to the user|Error message to the user@ (exit)")
LIST_ITEM1 ("6.9. @@Scripting 6.9. Calling from the command line|Calling from the command line")
LIST_ITEM ("7. @@Scripting 7. Scripting the editors|Scripting the editors")
LIST_ITEM1 ("7.1. @@Scripting 7.1. Scripting an editor from a shell script|Scripting an editor from a shell script@ (editor/endeditor)")
LIST_ITEM1 ("7.2. @@Scripting 7.2. Scripting an editor from within|Scripting an editor from within@")
LIST_ITEM ("8. @@Scripting 8. Controlling Praat from another program|Controlling Praat from another program")
LIST_ITEM1 ("8.1 @@Scripting 8.1. The sendpraat subroutine|The sendpraat subroutine")
LIST_ITEM1 ("8.2 @@Scripting 8.2. The sendpraat program|The sendpraat program")
LIST_ITEM1 ("8.3 @@Scripting 8.3. The sendpraat directive|The sendpraat directive")
MAN_END

MAN_BEGIN ("Scripting 1. My first script", "ppgb", 20001029)
NORMAL ("Suppose that you want to create a script that allows you to play a selected Sound object twice. "
	"You first create an empty script, by choosing @@New script@ from the Control menu. "
	"A @ScriptEditor will appear on your screen. In this editor, you type")
CODE ("Play")
CODE ("Play")
NORMAL ("Now select a #Sound in the object menu. As you expect from selecting a Sound, a #Play button will "
	"appear in the dynamic menu. If you now choose #Run in the ScriptEditor, the sound "
	"will be played twice.")
ENTRY ("What commands can I put into my script?")
NORMAL ("In the above example, you could use the \"Play\" command because that was "
	"the text on a button currently available button in the dynamic menu. "
	"Apart from these selection-dependent action commands, "
	"you can also use all fixed commands in the menus of the @@Object window@ "
	"and the @@Picture window@. For how to proceed with commands that need %arguments "
	"(i.e. the commands that end in \"...\" and present a dialog window), "
	"see @@Scripting 2. Arguments to commands|\\SS2@.")
ENTRY ("Faster ways of getting a script text")
NORMAL ("Instead of manually typing the command lines, as described above, it may be easier "
	"to create a script text from a %%macro recording%, with the @@History mechanism@. "
	"This allows you to create script texts without typing. "
	"For instance, if you choose @@Clear history@ in your ScriptEditor, then click the #%Play button twice (after selecting a Sound), "
	"and then choose @@Paste history@, your new script text "
	"contains exactly two lines that read \"Play\".")
NORMAL ("To edit a script that is already contained in a file on disk, use @@Open script...@.")
ENTRY ("How to run a script")
NORMAL ("You can run scripts from the @ScriptEditor. If you will have to use the script very often, "
	"it is advisable to create a button for it in the fixed menu or in a dynamic menu. See the "
	"@ScriptEditor man page.")
NORMAL ("On Unix and Windows, you can also run scripts from the command line. See @@Scripting 6.9. Calling from the command line|\\SS6.9@.")
MAN_END

MAN_BEGIN ("Scripting 2. Arguments to commands", "ppgb", 19990108)
INTRO ("This chapter describes how your script should represent "
	"commands that need %arguments, i.e. commands whose button has a title that ends in \"...\". "
	"Clicking such a button normally presents a %%dialog window%, which asks the user to supply "
	"arguments and then press the OK button. In a script, all of these arguments should be supplied on the same "
	"line as the command, in the same order as in the dialog window, counted from top to bottom.")
ENTRY ("Numeric arguments")
NORMAL ("The command ##Draw line...# from the World menu in the Picture window, "
	"normally presents a dialog box that asks the user to supply values for the numeric parameters %%From x%, "
	"%%From y%, %%To x%, and %%To y% (from top to bottom). To draw a line from the point (0, 0.5) "
	"to the point (1, 1), the values of the arguments would be 0, 0.5, 1, and 1, respectively. "
	"In a script, the command would read")
CODE ("Draw line... 0 0.5 1 1")
ENTRY ("Check buttons")
NORMAL ("In a script, you represent a %%check button% (yes/no choice) by \"true\" or \"false\", "
	"which may be abbreviated to \"t\" etc., or written with a capital; "
	"\"yes\" or \"no\" can also be used, as well as \"1\" or \"0\":")
CODE ("Marks left every... 1.0 100 yes yes no")
ENTRY ("Radio boxes")
NORMAL ("You represent a %%radio box% (multiple choice) by the text on the button that you want to select:")
CODE ("Print picture to PostScript printer... Finest A4 Portrait 1.0")
NORMAL ("If the choice (in a non-final argument) contains spaces, it should be enclosed within double quotes:")
CODE ("Print picture to PostScript printer... Finest \"US Letter\" Portrait 1.0")
NORMAL ("Using these double quotes is necessary because spaces are normally used for separating the arguments. "
	"Putting quotes around \"US Letter\" ensures that the second argument consists of both words. "
	"If you forget the quotes, the interpreter will think that the second argument is \"US\", "
	"the third argument is \"Letter\", and the fourth argument is the rest of the line, namely \"Portrait 1.0\", "
	"and the command will fail with the message")
CODE ("`Paper size' cannot have the value \"US\".")
ENTRY ("Text arguments")
NORMAL ("A text argument at the end should be typed without any quotes:")
CODE ("Text... 400 Centre 1.5 Bottom This is the summit")
NORMAL ("Though spaces separate the arguments, the last argument is always written without surrounding "
	"quotes, even if it contains spaces. This is possible because the interpreter knows that the ##Text...# "
	"command takes five arguments. The fifth argument is simply everything that follows the first four "
	"arguments. With this strategy, you will not suffer from %%quote paranoia%, which would occur "
	"if your text itself contains quotes:")
CODE ("Text... 0.5 Centre 0.5 Half \"hello world\"")
NORMAL ("In this case, the quotes around \"hello world\" will be written to the Picture window as well.")
NORMAL ("For these reasons, nearly all texts in dialog windows appear in the last (bottom) field, "
	"so that it can be scripted without using quotes. The exceptions are those few commands that "
	"have more than a single text parameter. A text argument that is not at the end should then be enclosed "
	"in double quotes if it is empty or contains spaces (otherwise, the quotes are optional):")
CODE ("Add menu command... Objects New \"Create a Bicycle...\" \"\" 0 /u/miep/createBicycle.script")
NORMAL ("If you want to include a double quote in such a text, use %two double quotes:")
CODE ("Add menu command... Objects New \"Create a \\\"l\\\"lBicycle\\\"r\\\"r...\" (etc.)")
NORMAL ("This doubling of quotes is what you want to avoid in your scripts, especially if your "
	"texts come from the expansion of string variables.")
ENTRY ("File arguments")
NORMAL ("The commands from the Read and Write menus, and several other commands whose names "
	"start with Read, Open, or Write, present a %%file selector window% instead of a typical Praat "
	"dialog window. File selector windows ask the user to supply a single argument: the file name.")
NORMAL ("In a script, you can supply the complete %path, including the directory (folder) hierarchy "
	"and the name of the file. On Unix, it goes like this (if you are user \"miep\"):")
CODE ("Read from file... /home/miep/sounds/animals/miauw.aifc")
NORMAL ("On Macintosh, it goes like this (supposing your hard drive is called \"Macintosh HD\"):")
CODE ("Read from file... Macintosh HD:Sounds:Animals:miauw.aifc")
NORMAL ("If your Sounds folder is on the desktop, it would be:")
CODE ("Read from file... Macintosh HD:Desktop Folder:Sounds:Animals:miauw.aifc")
NORMAL ("If your Sounds folder is on a Zip disk called Miep, it would be:")
CODE ("Read from file... Miep:Sounds:Animals:miauw.aifc")
NORMAL ("In Windows, you may type:")
CODE ("Read from file... C:\\bsSounds\\bsAnimals\\bsmiauw.aifc")
NORMAL ("Instead of these complete path names, you can use %relative path names. "
	"These are taken as relative to the directory in which your script resides.")
NORMAL ("On Unix, a relative path name starts without a \"/\". So if your script is "
	"%%/home/miep/sounds/analysis.praat%, the above line could be")
CODE ("Read from file... animals/miauw.aifc")
NORMAL ("On Macintosh, a relative (%partial) path name starts with a colon. So if your script is "
	"Macintosh HD:Sounds:Analysis.praat, the sound file is read by")
CODE ("Read from file... :Animals:miauw.aifc")
NORMAL ("In Windows, a relative path name starts without a backslash. So if your script is "
	"C:\\bsSounds\\bsAnalysis.praat, the sound file is read by")
CODE ("Read from file... Animals\\bsmiauw.aifc")
NORMAL ("Finally, your script may not be in a directory %above the directory from which you "
	"like to read, but in a directory on the side, like /home/miep/scripts, Macintosh HD:Scripts, "
	"or C:\\bsScripts. The commands would then read")
CODE ("Read from file... ../animals/miauw.aifc")
CODE ("Read from file... ::Animals:miauw.aifc")
CODE ("Read from file... ..\\bsAnimals\\bsmiauw.aifc")
ENTRY ("How to supply arguments automatically")
NORMAL ("If you dislike manually copying arguments from dialog windows into your script, "
	"you can use the @@history mechanism@ to automate this process: "
	"choose @@Clear history@ from the Edit menu in your @ScriptEditor, "
	"click your command button, edit the arguments, and click OK. The command will be executed. "
	"Then choose @@Paste history@, and the command line, including the arguments (with correct quotes), "
	"appears in a the ScriptEditor. You can build a new script on the basis of this line.")
MAN_END

MAN_BEGIN ("Scripting 3. Layout", "ppgb", 19990108)
INTRO ("This chapter handles the way you use white space, comments, "
	"and continuation lines in a Praat script.")
ENTRY ("White space")
NORMAL ("All white space (spaces and tabs) at the beginning of lines is ignored. This means that you can "
	"use indenting to make your script readable. You are advised to use three spaces for each level of indenting:")
CODE ("sum = 0")
CODE ("for i to 10")
CODE ("   for j to 10")
CODE ("      sum = sum + i\\^ j")
CODE ("   endfor")
CODE ("endfor")
CODE ("echo The sum of the products is 'sum'")
NORMAL ("Lines that are empty or consist solely of white space, are also ignored.")
ENTRY ("Comments")
NORMAL ("Comments are lines that start with !, \\# , or ;. These lines are ignored when your script is running:")
CODE ("\\#  Create 1 second of a sine wave with a frequency of 100 Hertz,")
CODE ("\\#  sampled at 22050 Hz:")
CODE ("Create Sound... sine 0 1 22050 sin (2*pi*100*x)")
ENTRY ("Continuation lines")
NORMAL ("There is normally one line per command, and one command per line.")
NORMAL ("But you can chop up long lines by using continuaton lines that start with three dots (\"...\"). "
	"You will normally want to follow this %ellipsis with a space, unless you want to concatenate "
	"the parts of a long word:")
CODE ("Viewport... 0 10 0 4")
CODE ("Text top... yes It's a long way to Llanfairpwllgwyngyll")
CODE ("   ...gogerychwyrndrobwllllantysiliogogogoch,")
CODE ("   ... unless you start from Tyddyn-y-felin.")
MAN_END

MAN_BEGIN ("Scripting 4. Object selection", "ppgb", 19991108)
INTRO ("This chapter is about how to select objects from your script, "
	"and how to find out what objects are currently selected.")
ENTRY ("Selecting objects")
NORMAL ("To simulate the mouse-clicked and dragged selection in the list of objects, "
	"you have the following commands:")
TAG ("#select %object")
DEFINITION ("selects one object, and deselects all others. If there are more "
	"objects with the same name, the most recently created one "
	"(i.e., the one nearest to the bottom of the list of objects) is selected:")
CODE ("   #select Sound hallo")
CODE ("   Play")
TAG ("#plus %object")
DEFINITION ("adds one object to the current selection.")
TAG ("#minus %object")
DEFINITION ("removes one object from the current selection.")
TAG ("##select all")
DEFINITION ("selects all objects:")
CODE ("   ##select all")
CODE ("   Remove")
NORMAL ("In the Praat shell, newly created objects are automatically selected. "
	"This is also true in scripts: ")
CODE ("! Generate a sine wave, play it, and draw its spectrum.")
CODE ("Create Sound... sine377  0 1 10000   0.9 * sin (2*pi*377*x)")
CODE ("Play")
CODE ("To Spectrum")
CODE ("! Draw the Spectrum:")
CODE ("Draw... 0 5000 20 80 yes")
CODE ("! Remove the created Spectrum and Sound:")
CODE ("#plus Sound sine377")
CODE ("Remove")
NORMAL ("Instead of by name, you can also select objects by their sequential ID:")
CODE ("   #select 43")
NORMAL ("This selects the 43rd object that you created since you started the program (see below).")
ENTRY ("Querying selected objects")
NORMAL ("You can get the name of a selected object into a string variable. "
	"For instance, the following reads the name of the second selected Sound "
	"(as counted from the top of the list of objects) into the variable %name\\$ :")
CODE1 ("name\\$  = ##selected\\$ # (\"Sound\", 2)")
NORMAL ("If the Sound was called \"Sound hallo\", the variable %name\\$  will contain the string \"hallo\". "
	"To get the name of the topmost selected Sound object, you can leave out the number:")
CODE1 ("name\\$  = ##selected\\$ # (\"Sound\")")
NORMAL ("Negative numbers count from the bottom. Thus, to get the name of the bottom-most selected Sound "
	"object, you say")
CODE1 ("name\\$  = ##selected\\$ # (\"Sound\", -1)")
NORMAL ("You would use ##selected\\$ # for drawing the object name in a picture:")
CODE ("Draw... 0 0 0 0 yes")
CODE ("name\\$  = ##selected\\$ # (\"Sound\")")
CODE ("Text top... no This is sound 'name\\$ '")
NORMAL ("For identifying previously selected objects, this method is not very suitable, since "
	"there may be multiple objects with the same name:")
CODE ("\\#  The following two lines are OK:")
CODE ("soundName\\$  = ##selected\\$ # (\"Sound\", -1)")
CODE ("pitchName\\$  = ##selected\\$ # (\"Pitch\")")
CODE ("\\#  But the following line is questionable, since it doesn't")
CODE ("\\#  necessarily select the previously selected Sound again:")
CODE ("#select Sound 'soundName\\$ '")
NORMAL ("Instead of this error-prone approach, you should get the object's unique ID. "
	"The correct version of our example becomes:")
CODE ("soundID = #selected (\"Sound\", -1)")
CODE ("pitchID = #selected (\"Pitch\")")
CODE ("\\#  Correct:")
CODE ("#select 'soundID'")
NORMAL ("To get the number of selected objects into a variable, use")
CODE ("numberOfSelectedSounds = numberOfSelected (\"Sound\")")
MAN_END

MAN_BEGIN ("Scripting 5. Language elements", "ppgb", 19990328)
NORMAL ("In a Praat script, you can use variables, expressions, and functions, of numeric as well as string type, "
	"and most of the control structures known from other procedural computer languages. "
	"The way the distinction between numbers and strings is made, may remind you of the programming language Basic.")
LIST_ITEM ("5.1. @@Scripting 5.1. Variables|Variables@ (numeric, string, copy, expansion)")
LIST_ITEM ("5.2. @@Scripting 5.2. Expressions|Expressions@ (numeric, string)")
LIST_ITEM ("5.3. @@Scripting 5.3. Jumps|Jumps@ (if, then, elsif, else, endif)")
LIST_ITEM ("5.4. @@Scripting 5.4. Loops|Loops@ (for/endfor, while/endwhile, repeat/until)")
LIST_ITEM ("5.5. @@Scripting 5.5. Procedures|Procedures@ (call, procedure)")
LIST_ITEM ("5.6. @@Scripting 5.6. Arrays|Arrays@")
LIST_ITEM ("5.7. @@Scripting 5.7. Quitting|Quitting@ (exit)")
MAN_END

MAN_BEGIN ("Scripting 5.1. Variables", "ppgb", 20010519)
INTRO ("In a Praat script, you can use numeric variables as well as string variables.")
ENTRY ("Numeric variables")
NORMAL ("Numeric variables contain integer numbers between -1,000,000,000,000,000 and +1,000,000,000,000,000 "
	"or real numbers between -10^^308^ and +10^^308^. The smallest numbers lie near -10^^-308^ and +10^^-308^.")
NORMAL ("You can use %%numeric variables% in your script:")
TAG ("%variable = %expression")
DEFINITION ("evaluates a numeric expression and assign the result to a variable.")
NORMAL ("Example:")
CODE ("length = 10")
CODE ("Draw line... 0 length 1 1")
NORMAL ("Names of numeric variables must start with a lower-case letter, optionally followed by a sequence "
	"of letters, digits, and underscores.")
ENTRY ("String variables")
NORMAL ("You can also use %%string variables%:")
CODE ("title\\$  = \"Dutch nasal place assimilation\"")
NORMAL ("As in the programming language Basic, the names of string variables end in a dollar sign.")
ENTRY ("Variable substitution")
NORMAL ("Existing variables are substituted when put between quotes:")
CODE ("x = 99")
CODE ("x2 = x * x")
CODE ("echo The square of 'x' is 'x2'.")
NORMAL ("This will write the following text to the Info window:")
CODE ("The square of 99 is 9801.")
NORMAL ("You can reduce the number of digits after the decimal point by use of the semicolon:")
CODE ("root = sqrt (2)")
CODE ("echo The square root of 2 is approximately 'root:3'.")
NORMAL ("This will write the following text to the Info window:")
CODE ("The square root of 2 is approximately 1.414.")
NORMAL ("By using \":0\", you round to whole values:")
CODE ("root = sqrt (2)")
CODE ("echo The square root of 2 is very approximately 'root:0'.")
NORMAL ("This will write the following text to the Info window:")
CODE ("The square root of 2 is very approximately 1.")
NORMAL ("##Predefined string variables# are $$newline\\$ $,  $$tab\\$ $, and $$shellDirectory\\$ $. "
	"The last one specifies the directory that was the default directory when Praat started up; "
	"you can use it in scripts that run from the Unix or DOS command line.")
MAN_END
/*
form Convert from WAV to AIFF
   text fileName hello.wav
endform
fileName$ = fileName$ - ".wav"
Read from file... 'shellDirectory$'/'fileName$'.wav
Write to AIFF file... 'shellDirectory$'/'fileName$'.aiff

if left$ (fileName$) <> "/"
   fileName$ = 'shellDirectory$'/'fileName$'
endif
*/

MAN_BEGIN ("Scripting 5.2. Expressions", "ppgb", 20001115)
INTRO ("In a Praat script, you can use numeric expressions as well as string expressions.")
ENTRY ("Numerical expressions")
NORMAL ("You can use a large variety of @@numerical expressions@ in your script:")
CODE ("length = 10")
CODE ("height = length/2")
CODE ("area = length * height")
NORMAL ("You can use numeric variables and formulas in arguments to commands:")
CODE ("Draw line... 0 length 0 length/2")
NORMAL ("Of course, all arguments except the last should either not contain spaces, "
	"or be enclosed in double quotes. So you would write either")
CODE ("Draw line... 0 height*2 0 height")
NORMAL ("or")
CODE ("Draw line... 0 \"height * 2\" 0 height")
NORMAL ("You can use numerical expressions in assignments (as above), or after "
	"#if, #elsif, #while, #until, and twice after #for.")
NORMAL ("On how to get information from commands that normally write to the Info window, "
	"see @@Scripting 6.4. Query commands|\\SS6.4@.")
ENTRY ("String expressions")
TAG ("##a\\$  = b\\$ ")
DEFINITION ("gives the value %true (= 1) if the strings are equal, and %false (= 0) otherwise. Mainly for use in #if, #while, and #until conditions.")
TAG ("##a\\$  <> b\\$ ")
DEFINITION ("gives the value %true if the strings are unequal, and %false otherwise.")
TAG ("##a\\$  < b\\$ ")
DEFINITION ("gives %true if the string %%a\\$ % precedes the string %%b\\$ % in ASCII sorting order. "
	"Thus, \"ha\" < \"hal\" and \"ha\" < \"ja\" are true, but \"ha\" < \"JA\" is false, "
	"because all capitals precede all lower-case characters in the ASCII sorting order.")
TAG ("##a\\$  > b\\$ ")
DEFINITION ("%true if %%a\\$ % comes after %%b\\$ % in ASCII sorting order. ")
TAG ("##a\\$  <= b\\$ ")
DEFINITION ("gives the value %true if the string %%a\\$ % precedes the string %%b\\$ % in ASCII sorting order, "
	"or if the strings are equal.")
TAG ("##a\\$  >= b\\$ ")
DEFINITION ("%true if %%a\\$ % comes after %%b\\$ % or the two are equal.")
TAG ("##a\\$  + b\\$ ")
DEFINITION ("concatenates the two strings. After")
CODE ("    text\\$  = \"hallo\" + \"dag\"")
DEFINITION ("The variable %%text\\$ % contains the string \"hallodag\".")
TAG ("##a\\$  - b\\$ ")
DEFINITION ("subtracts the second string from the end of the first. After")
CODE ("    soundFileName\\$  = \"hallo.aifc\"")
CODE ("    textgridFileName\\$  = soundFileName\\$  - \".aifc\" + \".TextGrid\"")
DEFINITION ("The variable %%textgridFileName\\$ % contains the string \"hallo.TextGrid\". "
	"If the first string %%a\\$ % does not end in the string %%b\\$ %, the result of the subtraction is the string %%a\\$ %.")
TAG ("##length (a\\$ )")
DEFINITION ("gives the length of the string. After")
CODE ("    string\\$  = \"hallo\"")
CODE ("    length = length (string\\$  + \"dag\")")
DEFINITION ("the variable %length contains the number 8 (yes, variables can have the same names as functions, "
	"without any danger of confusing the interpreter).")
TAG ("##left\\$  (a\\$ , n)")
DEFINITION ("gives a string consisting of the first %n characters of %%a\\$ %. After")
CODE ("    head\\$  = left\\$  (\"hallo\", 3)")
DEFINITION ("the variable %%head\\$ % contains the string \"hal\".")
TAG ("##right\\$  (a\\$ , n)")
DEFINITION ("gives a string consisting of the last %n characters of %%a\\$ %. After")
CODE ("    english\\$  = \"he\" + right\\$  (\"hallo\", 3)")
DEFINITION ("the variable %%english\\$ % contains the string \"hello\".")
TAG ("##mid\\$  (a\\$ , i, n)")
DEFINITION ("gives a string consisting of %n characters from %%a\\$ %, starting at the %%i%th character. After")
CODE ("    mid\\$  = mid\\$  (\"hallo\", 3, 2)")
DEFINITION ("the variable %%mid\\$ % contains the string \"ll\".")
TAG ("##index (a\\$ , b\\$ )")
DEFINITION ("gives the index of the first occurrence of the string %%b\\$ % in the string %%a\\$ %. After")
CODE ("    where = index (\"hallo allemaal\", \"al\")")
DEFINITION ("the variable %where contains the number 2, because the first \"al\" starts at the second character of the longer string. "
	"If the first string does not contain the second string, %index returns 0.")
TAG ("##rindex (a\\$ , b\\$ )")
DEFINITION ("gives the index of the last occurrence of the string %%b\\$ % in the string %%a\\$ %. After")
CODE ("    where = rindex (\"hallo allemaal\", \"al\")")
DEFINITION ("the variable %where contains the number 13, because the last \"al\" starts at the 13th character. "
	"If the first string does not contain the second string, %rindex returns 0.")
TAG ("##fixed\\$  (number, precision)")
DEFINITION ("formats a number as a string with %precision digits after the decimal point. Thus, $$fixed\\$  (72.65687, 3)$ "
	"becomes the string $$72.657$, and $$fixed\\$  (72.65001, 3)$ becomes the string $$72.650$. "
	"In these examples, we see that the result can be rounded up and that trailing zeroes are kept.")
MAN_END

MAN_BEGIN ("Scripting 5.3. Jumps", "ppgb", 19991112)
NORMAL ("You can use conditional jumps in your script:")
TAG ("#if %expression")
TAG ("#elsif %expression")
DEFINITION ("if the expression evaluates to zero or %false, the execution of the script jumps to the next "
	"#elsif or after the next #else or #endif at the same depth..")
NORMAL ("The following script computes the preferred length of a bed for a person 'age' years of age:")
CODE ("#if age <= 3")
CODE ("   length = 1.20")
CODE ("#elsif age <= 8")
CODE ("   length = 1.60")
CODE ("#else")
CODE ("   length = 2.00")
CODE ("#endif")
NORMAL ("A variant spelling for #elsif is #elif.")
MAN_END

MAN_BEGIN ("Scripting 5.4. Loops", "ppgb", 19990108)
ENTRY ("\"For\" loops")
TAG ("#for %variable #from %expression__1_ #to %expression__2_")
TAG ("#for %variable #to %expression")
DEFINITION ("the statements between the #for line and the matching #endfor will be executed "
	"while a variable takes on values between two expressions, with an increment of 1 "
	"on each turn of the loop. The default starting value of the loop variable is 1.")
NORMAL ("The following script plays nine sine waves, with frequencies of 200, 300, ..., 1000 Hz:")
CODE ("#for i #from 2 #to 10")
CODE ("   frequency = i * 100")
CODE ("   \\#  In the following formula, 'frequency' must be quoted,")
CODE ("   \\#  because a Matrix formula argument is a string from the interpreter's viewpoint:")
CODE ("   Create Sound... tone 0 0.3 22050 0.9*sin(2*pi*'frequency'*x)")
CODE ("   Play")
CODE ("   Remove")
CODE ("#endfor")
NORMAL ("The stop value of the #for loop is evaluated on each turn. If the second expression "
	"is already less than the first expression to begin with, the statements between #for and #endfor "
	"are not executed even once.")
ENTRY ("\"Repeat\" loops")
TAG ("#until %expression")
DEFINITION ("the statements between the matching preceding #repeat and the #until line "
	"will be executed again if the expression evaluates to zero or %false.")
NORMAL ("The following script measures the number of trials it takes me to throw 12 with two dice:")
CODE ("throws = 0")
CODE ("#repeat")
CODE ("   eyes = randomInteger (1, 6) + randomInteger (1, 6)")
CODE ("   throws = throws + 1")
CODE ("#until eyes = 12")
CODE ("#echo It took me 'throws' trials to throw 12 with two dice.")
NORMAL ("The statements in the #repeat/#until loop are executed at least once.")
ENTRY ("\"While\" loops")
TAG ("#while %expression")
DEFINITION ("if the expression evaluates to zero or %false, the execution of the script jumps "
	"after the matching #endwhile.")
TAG ("#endwhile")
DEFINITION ("execution jumps back to the matching preceding #while line, which is then evaluated again.")
NORMAL ("The following script forces the number %x into the range [0; 2\\pi):")
CODE ("#while x < 0")
CODE ("   x = x + 2 * pi")
CODE ("#endwhile")
CODE ("#while x >= 2 * pi")
CODE ("   x = x - 2 * pi")
CODE ("#endwhile")
NORMAL ("If the expression evaluates to zero or %false to begin with, the statements between #while and #endwhile "
	"are not executed even once.")
MAN_END

MAN_BEGIN ("Scripting 5.5. Procedures", "ppgb", 20000831)
NORMAL ("In a Praat script, you can define and call %procedures (subroutines).")
TAG ("#call %procedureName [%argument1 [%argument2 [...]]]")
DEFINITION ("the execution of the script jumps to the line after the matching #procedure line, "
	"which can be anywhere in the script.")
TAG ("#procedure %procedureName [%parameter1 [%parameter2 [...]]]")
DEFINITION ("introduces a procedure definition (when the execution of the script happens to arrive here, "
	"it jumps after the matching #endproc, i.e., the statements in the procedure are ignored).")
TAG ("#endproc")
DEFINITION ("the execution of the script jumps to the line after the #call line that invoked this procedure.")
NORMAL ("The following script plays three notes:")
CODE ("#call play_note 440")
CODE ("#call play_note 400")
CODE ("#procedure play_note frequency")
CODE ("   Create Sound... note 0 0.3 22050 0.9 * sin (2*pi*'frequency'*x)")
CODE ("   Play")
CODE ("   Remove")
CODE ("#endproc")
CODE ("#call play_note 500")
NORMAL ("The variable %frequency is a normal variable, global to the script. "
	"The procedure uses the same name space as the rest of the script, so beware of possible conflicts.")
NORMAL ("For arguments that contain spaces, you use double quotes, except for the last argument, "
	"which is the rest of the line:")
CODE ("#call Conjugate be \"I am\" \"you are\" she is")
CODE ("#procedure Conjugate verb\\$  first\\$  second\\$  third\\$ ")
CODE ("   #echo Conjugation of 'to 'verb\\$ '':")
CODE ("   #printline 1sg 'first\\$ '")
CODE ("   #printline 2sg 'second\\$ '")
CODE ("   #printline 3sg 'third\\$ '")
CODE ("#endproc")
NORMAL ("Arguments (except for the last) that contain double quotes should also be put between double quotes, and the "
	"double quotes should be doubled:")
CODE ("#procedure texts top\\$  bottom\\$ ")
CODE ("   Text top... yes 'top\\$ '")
CODE ("   Text bottom... yes 'bottom\\$ '")
CODE ("#endproc")
CODE ("#call texts \\\" \\\" \\\" hello\\\" \\\"  at the top\\\"  \\\" goodbye\\\"  at the bottom")
ENTRY ("Older version")
NORMAL ("You are advised not to use the old directive #proc instead of #procedure, since #proc, "
	"with its hybrid parameters, "
	"does not distinguish between numeric and string variables, and, therefore, performs no evaluation "
	"of numeric expressions. Consider the following two procedures:")
CODE ("#proc oldmult a b")
CODE ("   #let c = 'a' * 'b'")
CODE ("   #echo The product is 'c'")
CODE ("#endproc")
CODE ("#procedure newmult a b")
CODE ("   c = a * b")
CODE ("   #echo The product is 'c'")
CODE ("#endproc")
NORMAL ("The procedure $newmult will handle the following input correctly:")
CODE ("call newmult 2+3 7")
NORMAL ("Since the interpreter knows that %a is a numeric variable, it can evaluate the expression 2+3, "
	"so that %a equals 5 upon entry of $newmult, and the correct result 35 is written to the Info window.")
NORMAL ("The procedure $oldmult will fail:")
CODE ("call oldmult 2+3 7")
NORMAL ("Since the interpreter cannot know whether the hybrid variable %a contains a number or a string, "
	"it will assume that %a is a string, and compute %c as 2+3 * 7, whose result is 23. The remedy is to "
	"put parentheses around the call, as in")
CODE ("call oldmult (2+3) 7")
NORMAL ("or to put parentheses in the procedure, as in")
CODE ("   #let c = ('a') * 'b'")
NORMAL ("Since these things are error-prone, you are advised to use the #procedure directive exclusively.")
MAN_END

MAN_BEGIN ("Scripting 5.6. Arrays", "ppgb", 20000831)
NORMAL ("Quote substitution allows you to simulate arrays of variables:")
CODE ("#for i #from 1 #to 5")
CODE ("   square'i' = i * i")
CODE ("#endfor")
NORMAL ("After this, the variables %square1, %square2, %square3, %square4, and %square5 contain "
	"the values 1, 4, 9, 16, and 25, respectively.")
NORMAL ("You can use any number of variables in a script, but you can also use Matrix or Sound objects for arrays.")
NORMAL ("You can substitute variables with the usual single quotes, as in $$'square3'$. "
	"If the index is also a variable, however, you may need a dummy variable:")
CODE ("#clearinfo")
CODE ("#for i #from 1 #to 5")
CODE ("   #hop = square'i'")
CODE ("   #print The square of 'i' is 'hop'")
CODE ("   #printline")
CODE ("#endfor")
NORMAL ("The reason for this is that the following line would not work, because of the required "
	"double substitution:")
CODE ("#print The square of 'i' is 'square'i''")
MAN_END

MAN_BEGIN ("Scripting 5.7. Quitting", "ppgb", 19990328)
NORMAL ("Normally, the execution of your script ends when the interpreter has executed the last line "
	"that is not within a procedure definition. However, you can also explicitly stop the script:")
TAG ("#exit")
DEFINITION ("stops the execution of the script in the normal way, i.e. without any messages to the user. "
	"Any parameter dialog is removed from the screen.")
TAG ("#exit %%error-message%")
DEFINITION ("stops the execution of the script while sending an error message to the user. "
	"Any parameter dialog will stay on the screen.")
NORMAL ("For an example, see @@Scripting 6.8. Error message to the user|\\SS6.8@.")
MAN_END

MAN_BEGIN ("Scripting 6. Communication outside the script", "ppgb", 20000927)
LIST_ITEM ("6.1. @@Scripting 6.1. Arguments to the script|Arguments to the script@ (form/endform, execute)")
LIST_ITEM ("6.2. @@Scripting 6.2. Calling system commands|Calling system commands@ (system, system_nocheck)")
LIST_ITEM ("6.3. @@Scripting 6.3. Writing to the Info window|Writing to the Info window@ (echo, print, printtab, printline)")
LIST_ITEM ("6.4. @@Scripting 6.4. Query commands|Query commands@ (Get, Count)")
LIST_ITEM ("6.5. @@Scripting 6.5. Files|Files@ (fileReadable, <, >, >>, filedelete, fileappend)")
LIST_ITEM ("6.6. @@Scripting 6.6. Controlling the user|Controlling the user@ (pause)")
LIST_ITEM ("6.7. @@Scripting 6.7. Sending a message to another program|Sending a message to another program@ (sendsocket)")
LIST_ITEM ("6.8. @@Scripting 6.8. Error message to the user|Error message to the user@ (exit)")
LIST_ITEM ("6.9. @@Scripting 6.9. Calling from the command line|Calling from the command line")
MAN_END

MAN_BEGIN ("Scripting 6.1. Arguments to the script", "ppgb", 20020325)
NORMAL ("You can cause a Praat script to prompt for arguments. The file $$playSine.praat$ may contain the following:")
CODE ("#form Play a sine wave")
CODE ("   #positive Sine_frequency_(Hz) 377")
CODE ("   #positive Gain_(0..1) 0.3 (= not too loud)")
CODE ("#endform")
CODE ("Create Sound... sine'sine_frequency'  0 1 10000   'gain' * sin (2*pi*'sine_frequency'*x)")
CODE ("Play")
CODE ("Remove")
NORMAL ("When running this script, the interpreter puts a dialog box (%form) on your screen, "
	"entitled \"Play a sine wave\", "
	"with two fields, titled \"Sine frequency (Hz)\" and \"Gain\", that have been provided "
	"with the default values \"377\" and \"0.3 (= not too loud)\", which you can change before clicking #OK.")
NORMAL ("As you see, the underscores have been replaced with spaces: that looks better in the dialog. "
	"Inside the script, the field names can be accessed as variables: these do contain the underscores, "
	"since they must not contain spaces, but the parentheses (Hz) have been chopped off. Note that the first "
	"letter of these variables is converted to lower case, so that you can assign to them in your script.")
NORMAL ("Inside the script, the value \"0.3 (= not too loud)\" will be known as \"0.3\", "
	"because this is a numeric field.")
NORMAL ("Scripts can be nested: the file %%doremi.praat% may contain the following:")
CODE ("#execute playSine.praat 550 0.9")
CODE ("#execute playSine.praat 615 0.9")
CODE ("#execute playSine.praat 687 0.9")
NORMAL ("You can use the following field types in your forms:")
TAG ("#real %variable %initialValue")
DEFINITION ("for real numbers.")
TAG ("#positive %variable %initialValue")
DEFINITION ("for positive real numbers: the form issues an error message if the number "
	"that you enter is negative or zero; further on in the script, the number may take on any value.")
TAG ("#integer %variable %initialValue")
DEFINITION ("for whole numbers: the form reads the number as an integer; "
	"further on in the script, the number may take on any real value.")
TAG ("#natural %variable %initialValue")
DEFINITION ("for positive whole numbers: the form issues an error message if the number "
	"that you enter is negative or zero; further on in the script, the number may take on any real value.")
TAG ("#word %variable %initialValue")
DEFINITION ("for a string without spaces: the form only reads up to the first space (\"oh yes\" becomes \"oh\"); "
	"further on in the script, the string may contain spaces.")
TAG ("#sentence %variable %initialValue")
DEFINITION ("for any short string.")
TAG ("#text %variable %initialValue")
DEFINITION ("for any possibly long string (the variable name will not be shown in the form).")
TAG ("#boolean %variable %initialValue")
DEFINITION ("a check box will be shown; the value is 0 if off, 1 if on.")
TAG ("#choice %variable %initialValue")
DEFINITION ("a radio box will be shown; the value is 1 or higher. This is followed by a series of:")
TAG ("#button %text")
DEFINITION ("a button in a radio box.")
TAG ("#comment %text")
DEFINITION ("a line with any text.")
NORMAL ("Inside the script, strings are known as string variables, numbers as numeric variables:")
CODE ("#form Sink it")
CODE ("   #sentence Name_of_the_ship Titanic")
CODE ("   #real Distance_to_the_iceberg_(m) 500.0")
CODE ("   #natural Number_of_people 1800")
CODE ("   #natural Number_of_boats 10")
CODE ("#endform")
NORMAL ("In this script, the variables are known as %%name_of_the_ship\\$ %, %distance_to_the_iceberg, "
	"%number_of_people, and %number_of_boats.")
NORMAL ("The variable associated with a radio box will get a numeric as well as a string value:")
CODE ("#form Fill attributes")
CODE ("   #comment Choose any colour and texture for your paintings")
CODE ("   #choice Colour: 5")
CODE ("      #button Dark red")
CODE ("      #button Sea green")
CODE ("      #button Navy blue")
CODE ("      #button Canary yellow")
CODE ("      #button Black")
CODE ("      #button White")
CODE ("   #choice Texture: 1")
CODE ("      #button Smooth")
CODE ("      #button Rough")
CODE ("      #button With holes")
CODE ("#endform")
CODE ("#echo You chose the colour 'colour\\$ ' and texture 'texture\\$ '.")
NORMAL ("This shows two radio boxes. In the Colour box, the fifth button (Black) is the default here. "
	"If you click on \"Navy blue\" and then #%OK, the variable %colour will have the value \"3\", "
	"and the variable %%colour\\$ % will have the value \"Navy blue\". "
	"Note that the trailing colon is chopped off, and that the button and comment texts may contain spaces. "
	"So you can test the value of the Colour box in either of the following ways:")
CODE ("if colour = 4")
NORMAL ("or")
CODE ("if colour\\$  = \"Canary yellow\"")
NORMAL ("The field types #optionmenu and #option are completely analogous to #choice and #button, "
	"but use up much less space on the screen:")
CODE ("#form Fill attributes")
CODE ("   #comment Choose any colour and texture for your paintings")
CODE ("   #optionmenu Colour: 5")
CODE ("      #option Dark red")
CODE ("      #option Sea green")
CODE ("      #option Navy blue")
CODE ("      #option Canary yellow")
CODE ("      #option Black")
CODE ("      #option White")
CODE ("   #optionmenu Texture: 1")
CODE ("      #option Smooth")
CODE ("      #option Rough")
CODE ("      #option With holes")
CODE ("#endform")
CODE ("#echo You chose the colour 'colour\\$ ' and texture 'texture\\$ '.")
NORMAL ("You can combine two short fields into one by using %left and %right:")
CODE ("#form Get duration")
CODE ("   #natural left_Year_range 1940")
CODE ("   #natural right_Year_range 1945")
CODE ("#endform")
CODE ("duration = right_Year_range - left_Year_range")
CODE ("#echo The duration is 'duration' years.")
NORMAL ("The interpreter will only show the single text \"Year range\", followed by two small text fields.")
NORMAL ("If you call a script from a script (with #execute), "
	"arguments (except for the last) that contain spaces must be put between double quotes, "
	"and values for #choice must be passed as strings:")
CODE ("#execute fill_attributes.praat \"Navy blue\" With holes")
NORMAL ("You can pass values for #boolean either as \"yes\" and \"no\" or 1 and 0.")
MAN_END

MAN_BEGIN ("Scripting 6.2. Calling system commands", "ppgb", 20020317)
INTRO ("You can call system commands from a Praat script on Unix, Windows, and MacOS X computers.")
TAG ("#system %command")
DEFINITION ("executes a Unix or Windows shell command, interpreting non-zero return values as errors:")
CODE1 ("#system cd /u/miep/sounds; sfplay hallo.aifc")
TAG ("#system_nocheck %command")
DEFINITION ("executes a Unix or Windows shell command, ignoring return values:")
CODE1 ("#system_nocheck rm dummy.aifc")
NORMAL ("In the last example, using $$#system rm dummy.aifc$ would cause the script to stop "
	"if the file $$dummy.aifc$ does not exist.")
TAG ("##environment\\$  (#%%symbol-string%#)")
DEFINITION ("returns the value of an environment variable under Unix, e.g.")
CODE ("   homeDirectory\\$  = ##environment\\$ # (\"HOME\")")
MAN_END

MAN_BEGIN ("Scripting 6.3. Writing to the Info window", "ppgb", 20000302)
NORMAL ("With the @Info button and several commands in the #Query submenus, "
	"you write to the @@Info window@. If your program is run from batch (on Unix or Windows), "
	"the text goes to %stdout.")
NORMAL ("The following commands allow you to write to the Info window from a script only:")
TAG ("#echo %text")
DEFINITION ("clears the Info window and writes some text to it:")
CODE ("   #echo Starting simulation...")
TAG ("#clearinfo")
DEFINITION ("clears the Info window.")
TAG ("#print %text")
DEFINITION ("appends some text to the Info window, without clearing it and "
	"without going to a new line.")
TAG ("#printtab")
DEFINITION ("appends a %tab character to the Info window. This allows you to create "
	"table files that can be read by some spreadsheet programs.")
TAG ("#printline [%text]")
DEFINITION ("causes the following text in the Info window to begin at a new line. "
	"You can add text, just like with #print.")
NORMAL ("The following script builds a table with statistics about a pitch contour:")
CODE ("#clearinfo")
CODE ("#printline  Minimum   Maximum")
CODE ("Create Sound... sin 0 0.1 10000 sin(2*pi*377*x)")
CODE ("To Pitch... 0.01 75 600")
CODE ("minimum = Get minimum... 0 0 Hertz Parabolic")
CODE ("#print 'minimum'")
CODE ("#printtab")
CODE ("maximum = Get maximum... Hertz")
CODE ("#print 'maximum'")
CODE ("#printline")
NORMAL ("You could combine the last four print statements into:")
CODE ("#printline 'minimum''tab\\$ ''maximum'")
NORMAL ("or:")
CODE ("#print 'minimum''tab\\$ ''maximum''newline\\$ '")
MAN_END

MAN_BEGIN ("Scripting 6.4. Query commands", "ppgb", 19990108)
NORMAL ("If you click the \"Get mean...\" command for a Pitch object, "
	"the Info window will contain a text like \"150 Hz\" as a result. In a script, you would rather "
	"have this result in a variable instead of in the Info window. The solution is simple:")
CODE ("mean = Get mean... 0 0 Hertz Parabolic")
NORMAL ("The numeric variable \"mean\" now contains the number 150. When assigning to a numeric variable, "
	"the interpreter converts the part of the text before the first space into a number.")
NORMAL ("You can also assign to string variables:")
CODE ("mean\\$  = Get mean... 0 0 Hertz Parabolic")
NORMAL ("The string variable \"mean\\$ \" now contains the entire string \"150 Hz\".")
NORMAL ("This works for every command that would otherwise write into the Info window.")
MAN_END

MAN_BEGIN ("Scripting 6.5. Files", "ppgb", 20010821)
INTRO ("You can read from and write to text files from a Praat script.")
ENTRY ("Reading a file")
NORMAL ("You can check the availability of a file for reading with the function")
CODE ("#fileReadable (fileName\\$ )")
NORMAL ("which returns #true if the file exists and can be read, and #false otherwise.")
NORMAL ("To read the contents of an existing text file into a string variable, you use")
CODE ("text\\$  ##<# %fileName")
NORMAL ("where $$text\\$ $ is any string variable and $$%fileName$ is an unquoted string. "
	"If the file does not exist, the script terminates with an error message.")
ENTRY ("Example: reading a settings file")
NORMAL ("Suppose that the file ##height.inf# may contain an appropriate value for a numeric variable "
	"called $height, which we need to use in our script. We would like to read it with")
CODE ("height\\$  < height.inf")
CODE ("height = 'height\\$ '")
NORMAL ("However, this script will fail if the file ##height.inf# does not exist. To guard "
	"against this situation, we could check the existence of the file, and supply a default "
	"value in case the file does not exist:")
CODE ("fileName\\$  = \"height.inf\"")
CODE ("if fileReadable (fileName\\$ )")
CODE ("   height\\$  < 'fileName\\$ '")
CODE ("   height = 'height\\$ '")
CODE ("else")
CODE ("   height = 180")
CODE ("endif")
ENTRY ("Writing a file")
NORMAL ("To write the contents of an existing string into a new text file, you use")
CODE ("text\\$  ##># %fileName")
NORMAL ("where $$text\\$ $ is any string variable and $$%fileName$ is an unquoted string. "
	"If the file cannot be created, the script terminates with an error message.")
NORMAL ("To append the contents of an existing string at the end of an existing text file, you use")
CODE ("text\\$  ##>># %fileName")
NORMAL ("If the file does not yet exist, it is created first.")
NORMAL ("You can delete an existing file with")
CODE ("#filedelete %fileName")
NORMAL ("If the file does not exist, #filedelete does nothing.")
NORMAL ("The simplest way to append text to a file is by using #fileappend:")
CODE ("#fileappend out.txt Hello world!")
ENTRY ("Example: writing a table of squares")
NORMAL ("Suppose that we want to create a file with the following text:")
CODE ("The square of 1 is 1")
CODE ("The square of 2 is 4")
CODE ("The square of 3 is 9")
CODE ("...")
CODE ("The square of 100 is 10000")
NORMAL ("We can do this by collecting each line in a variable:")
CODE ("filedelete squares.txt")
CODE ("for i to 100")
CODE ("   square = i * i")
CODE ("   fileappend squares.txt The square of 'i' is 'square''newline\\$ '")
CODE ("endfor")
NORMAL ("Note that we delete the file before appending to it, "
	"in order that we do not append to an already existing file.")
NORMAL ("If you put the name of the file into a variable, make sure to surround it "
	"with double quotes when using #fileappend, since the file name may contain spaces "
	"and is not at the end of the line:")
CODE ("name\\$  = \"Hard disk:Desktop Folder:squares.text\"")
CODE ("filedelete 'name\\$ '")
CODE ("for i to 100")
CODE1 ("square = i * i")
CODE1 ("fileappend \"'name\\$ '\" The square of 'i' is 'square''newline\\$ '")
CODE ("endfor")
NORMAL ("Finally, you can append the contents of the Info window to a file with")
CODE ("#fappendinfo %fileName")
ENTRY ("Directory listings")
NORMAL ("To get the names of the files if a certain type in a certain directory, "
	"use @@Create Strings as file list...@.")
MAN_END

MAN_BEGIN ("Scripting 6.6. Controlling the user", "ppgb", 19990108)
INTRO ("You can temporarily halt a Praat script:")
TAG ("#pause %text")
DEFINITION ("suspends execution of the script, and allows the user to interrupt it. "
	"A message dialog will appear with the %text and the buttons Continue and Stop:")
CODE ("   #pause The next file will be beerbeet.TextGrid")
MAN_END

MAN_BEGIN ("Scripting 6.7. Sending a message to another program", "ppgb", 20000927)
NORMAL ("To send messages to running programs that use the Praat shell, "
	"use $sendpraat (see @@Scripting 8. Controlling Praat from another program|\\SS8@).")
NORMAL ("To send a message to another running program that listens to a socket, "
	"you can use the $sendsocket directive. This works on Unix and Windows only.")
ENTRY ("Example")
NORMAL ("Suppose we are in the Praat-shell program #Praat, which is a system for doing phonetics by computer. "
	"From this program, we can send a message to the %%non%-Praat-shell program #MovieEdit, "
	"which does know how to display a sound file:")
CODE ("Write to file... hallo.wav")
CODE ("sendsocket fonsg19.hum.uva.nl:6667 display hallo.wav")
NORMAL ("In this example, $$fonsg19.hum.uva.nl$ is the computer on which MovieEdit is running; "
	"you can specify any valid Internet address instead, as long as that computer allows you to send messages to it. "
	"If MovieEdit is running on the same computer as Praat, you can specify $localhost instead of the full Internet address.")
NORMAL ("The number 6667 is the port number on which MovieEdit is listening. Other programs will use different port numbers.")
MAN_END

MAN_BEGIN ("Scripting 6.8. Error message to the user", "ppgb", 19990328)
NORMAL ("If the user makes a mistake (e.g. types the wrong arguments into your dialog), "
	"you can use the #exit directive (@@Scripting 5.7. Quitting|\\SS5.7@) "
	"to stop the execution of the script with an error message:")
CODE ("form My analysis")
CODE1 ("real Starting_time_(s) 0.0")
CODE1 ("real Finishing_time_(s) 1.0")
CODE ("endform")
CODE ("if finishing_time <= starting_time")
CODE1 ("#exit Finishing time should exceed 'starting_time' seconds.")
CODE ("endif")
CODE ("\\#  Proceed with the analysis...")
MAN_END

MAN_BEGIN ("Scripting 6.9. Calling from the command line", "ppgb", 20000719)
INTRO ("On Unix, you can call a Praat script from the command line:")
CODE ("> praat doit.praat 50 hallo")
NORMAL ("This opens #praat, runs the script ##doit.praat# with arguments \"50\" and \"hallo\", "
	"and closes #praat.")
NORMAL ("You also have the possibility of running the program interactively from the command line:")
CODE ("> praat -")
NORMAL ("You can then type in any of the fixed and dynamic commands, and commands that handle object selection, "
	"like #select. "
	"This method also works in pipes:")
CODE ("> echo \"Statistics...\" | praat -")
NORMAL ("On Windows, you can also call a Praat script from the command line:")
CODE ("e:\\bspraatcon.exe e:\\bsdoit.praat 50 hallo")
NORMAL ("Note that you use ##praatcon.exe# instead of ##praat.exe#. The script will write to the console output, and its output "
	"can be used in pipes.")
MAN_END

MAN_BEGIN ("Scripting 7. Scripting the editors", "ppgb", 19990108)
NORMAL ("With a Praat script, you can automatize your work in the editors.")
LIST_ITEM1 ("7.1. @@Scripting 7.1. Scripting an editor from a shell script|Scripting an editor from a shell script@ (editor/endeditor)")
LIST_ITEM1 ("7.2. @@Scripting 7.2. Scripting an editor from within|Scripting an editor from within@")
MAN_END

MAN_BEGIN ("Scripting 7.1. Scripting an editor from a shell script", "ppgb", 20010606)
NORMAL ("From a Praat shell script, you can switch to an editor and back again:")
CODE ("sound\\$  = \"hallo\"")
CODE ("start = 0.3")
CODE ("finish = 0.7")
CODE ("Read from file... 'sound\\$ '.aifc")
CODE ("Edit")
CODE ("#editor Sound 'sound\\$ '")
CODE ("   Zoom... start finish")
CODE ("#endeditor")
CODE ("Play")
NORMAL ("This script reads a sound file from disk, pops up an editor for the resulting object, "
	"makes this editor zoom in on the part between 0.3 and 0.7 seconds, "
	"and returns to the Praat shell to play the entire sound.")
MAN_END

MAN_BEGIN ("Scripting 7.2. Scripting an editor from within", "ppgb", 20010606)
NORMAL ("This section will show how you can permanently extend the functionality of an editor.")
NORMAL ("As an example, consider the following problem: you want to see a graphic representation "
	"of the spectrum of the sound around the cursor position in the SoundEditor. To achieve this, "
	"follow these steps:")
LIST_ITEM ("1. Create a Sound.")
LIST_ITEM ("2. View it in a SoundEditor by clicking @Edit.")
LIST_ITEM ("3. Choose ##New script# from the @File menu in the SoundEditor. The resulting @ScriptEditor "
	"will have a name like \"Untitled script [Sound hallo]\".")
LIST_ITEM ("4. Type the following lines into the ScriptEditor:")
CODE2 ("cursor = Get cursor")
CODE2 ("Select... cursor-0.02 cursor+0.02")
CODE2 ("Extract windowed selection... slice Kaiser2 2 no")
CODE1 ("#endeditor")
CODE1 ("To Spectrum")
CODE1 ("Edit")
NORMAL ("If you choose Run from the Run menu in the ScriptEditor, a region of 40 milliseconds around the "
	"current cursor position in the SoundEditor will become selected. This piece will be copied to the list of objects, "
	"after applying a double Kaiser window (total length 80 ms). Thus, a Sound named \"slice\" will appear in the list. "
	"Subsequently, a Spectrum object also called \"slice\" will appear in the list, and a SpectrumEditor titled "
	"\"Spectrum slice\" will finally appear on your screen.")
LIST_ITEM ("5. Save the script to disk, e.g. as /us/miep/spectrum.praat. The title of the ScriptEditor will change accordingly.")
LIST_ITEM ("6. Since you will want this script to be available in all future SoundEditors, you choose ##Add to menu...# from the File menu. "
	"For the %Window, you specify \"SoundEditor\" (this is preset). For the %Menu, you may want to choose \"Spectrogram\" "
	"instead of the preset value (\"File\"). For the name of the %Command, you type something like \"Show spectrum at cursor\" "
	"(instead of \"Do it...\"). Then you click OK.")
NORMAL ("The command will be visible in every SoundEditor that you create from now on. "
	"To see this, close the one visible SoundEditor, select the original Sound, choose Edit again, and inspect the Sonagram menu. "
	"You can now view the spectrum around the cursor just by choosing this menu command.")
NORMAL ("After you leave Praat and start it again, the command will continue to appear in the SoundEditor. "
	"If you don't like the command any longer, you can remove it with the @ButtonEditor, which you can start "
	"by choosing #Buttons from the Preferences submenu of the Control menu in the Objects window.")
ENTRY ("Improving your script")
NORMAL ("The above spectrum-viewing example has a number of disadvantages. It clutters the object list with a number "
	"of indiscriminable Sounds and Spectra called \"slice\", and the spectrum is shown up to the Nyquist frequency "
	"while we may just be interested in the lower 5000 Hz. Furthermore, the original selection in the SoundEditor is lost.")
NORMAL ("To improve the script, we open it again with ##Open script...# from the File menu in the SoundEditor. After every change, "
	"we can run it with Run from the Run menu again; alternatively, we could save it (with Save from the File menu) and choose our new "
	"\"Show spectrum at cursor\" button (this button will always run the version on disk, never the one viewed in a ScriptEditor).")
NORMAL ("To zoom in on the first 5000 Hz, we add the following code at the end of our script:")
CODE ("#editor Spectrum slice")
CODE1 ("Zoom... 0 5000")
NORMAL ("To get rid of the \"Sound slice\", we can add:")
CODE ("#endeditor")
CODE ("select Sound slice")
CODE ("Remove")
NORMAL ("Note that #endeditor is needed to change from the environment of a SpectrumEditor to the environment of the object & picture windows.")
NORMAL ("If you now choose the \"Show spectrum at cursor\" button for several cursor positions, you will notice that all those editors have the same name. "
	"To remedy the ambiguity of the line $$#editor Spectrum slice$, we give each slice a better name. For example, if the cursor was at "
	"635 milliseconds, the slice could be named \"635ms\". We can achieve this by changing the extraction in the following way:")
CODE ("milliseconds = round (cursor*1000)")
CODE ("Extract windowed selection... 'milliseconds'ms Kaiser2 2 no")
NORMAL ("The names of the Sound and Spectrum objects will now have more chance of being unique. Two lines will have to be edited trivially.")
NORMAL ("Finally, we will reset the selection to the original. At the top of the script, we add two lines to remember the positions of the selection markers:")
CODE ("begin = Get begin of selection")
CODE ("end = Get end of selection")
NORMAL ("At the bottom, we reset the selection:")
CODE ("#editor")
CODE1 ("Select... begin end")
NORMAL ("Note that the #editor directive if not followed by the name of an editor, returns the script to the original environment.")
NORMAL ("The complete script is:")
CODE1 ("begin = Get begin of selection")
CODE1 ("end = Get end of selection")
CODE1 ("cursor = Get cursor")
CODE1 ("Select... cursor-0.02 cursor+0.02")
CODE1 ("\\#  Create a name. E.g. \"670ms\" means at 670 milliseconds.")
CODE1 ("milliseconds = round (cursor*1000)")
CODE1 ("Extract windowed selection... 'milliseconds'ms Kaiser2 2 no")
CODE ("#endeditor")
CODE ("To Spectrum")
CODE ("Edit")
CODE ("#editor Spectrum 'milliseconds'ms")
CODE1 ("Zoom... 0 5000")
CODE ("#endeditor")
CODE ("select Sound 'milliseconds'ms")
CODE ("Remove")
CODE ("#editor")
CODE1 ("Select... begin end")
NORMAL ("This script is useful as it stands. It is good enough for safe use. For instance, if the created Sound object has the same name "
	"as an already existing Sound object, it will be the newly created Sound object that will be removed in the $Remove line, "
	"because #select always selects the most recently created object in case of ambiguity.")
MAN_END

MAN_BEGIN ("sendpraat", "ppgb", 20000927)
NORMAL ("See @@Scripting 8. Controlling Praat from another program@.")
MAN_END

MAN_BEGIN ("Scripting 8. Controlling Praat from another program", "ppgb", 20000927)
LIST_ITEM ("8.1 @@Scripting 8.1. The sendpraat subroutine|The sendpraat subroutine")
LIST_ITEM ("8.2 @@Scripting 8.2. The sendpraat program|The sendpraat program")
LIST_ITEM ("8.3 @@Scripting 8.3. The sendpraat directive|The sendpraat directive")
MAN_END

MAN_BEGIN ("Scripting 8.1. The sendpraat subroutine", "ppgb", 20020430)
INTRO ("A subroutine for sending messages to %running programs that use the @@Praat shell@. "
	"Also a Unix or DOS console program with the same purpose.")
ENTRY ("Syntax")
LIST_ITEM ("##sendpraat (void *#%display##, const char *#%program##, long #%timeOut##, char *#%text##);")
ENTRY ("Arguments")
TAG ("%display")
DEFINITION ("the display pointer if the subroutine is called from a running X program; "
	"if NULL, sendpraat will open the display by itself. On Windows and Macintosh, "
	"this argument is ignored.")
TAG ("%program")
DEFINITION ("the name of a running program that uses the Praat shell, e.g. \"Praat\" or \"ALS\". "
	"The first letter may be specified as lower or upper case; it will be converted to lower case for Unix "
	"and to upper case for Macintosh and Windows.")
TAG ("%message")
DEFINITION ("a sequence of Praat shell lines (commands and directives).")
TAG ("%timeOut (Unix and Macintosh only)")
DEFINITION ("the number of seconds that sendpraat will wait for an answer "
	"before writing an error message. A %timeOut of 0 means that "
	"the message will be sent asynchronously, i.e., that sendpraat "
	"will return immediately without issuing any error message.")
TAG ("%text")
DEFINITION ("the script text to be sent. Sendpraat may alter this text!")
ENTRY ("Example 1: killing a program")
CODE ("char message [100], *errorMessage;")
CODE ("strcpy (message, \"Quit\");")
CODE ("errorMessage = #sendpraat (NULL, \"praat\", 0, message);")
CODE ("if (errorMessage != NULL) fprintf (stderr, \"\\% s\", errorMessage);")
NORMAL ("This causes the program #Praat to quit (gracefully), because #Quit is a fixed "
	"command in the Control menu of that program. "
	"On Unix and Macintosh, sendpraat returns immediately; on Windows, you the %timeOut argument is ignored. "
	"The return value %errorMessage is a statically allocated string internal to sendpraat, "
	"and is overwritten by the next call to sendpraat.")
ENTRY ("Example 2: playing a sound file in reverse")
NORMAL ("Suppose you have a sound file whose name is in the variable $fileName, "
	"and you want the program #Praat, which can play sounds, "
	"to play this sound backwards.")
CODE ("char message [1000], *errorMessage;")
CODE ("sprintf (message, \"Read from file... \\% s\\bsnPlay reverse\\bsnRemove\", fileName);")
CODE ("errorMessage = #sendpraat (NULL, \"praat\", 0, message);")
NORMAL ("This will work because ##Play reverse# is an action command "
	"that becomes available in the dynamic menu when a Sound is selected. "
	"On Unix, sendpraat will allow #Praat at most 1000 seconds to perform this.")
ENTRY ("Example 3: executing a large script file")
NORMAL ("Sometimes, it may be unpractical to send a large script directly to #sendpraat. "
	"Fortunately, the receiving program knows the #execute directive:")
CODE ("char message [100], *errorMessage;")
CODE ("strcpy (message, \"doAll.praat 20\");")
CODE ("errorMessage = #sendpraat (NULL, \"praat\", 0, message);")
NORMAL ("This causes the program #Praat to execute the script ##doAll.praat# with an argument of \"20\".")
ENTRY ("How to download")
NORMAL ("You can download the source code of the sendpraat subroutine and program "
	"via ##www.praat.org# or from ##http://www.fon.hum.uva.nl/praat/sendpraat.html#.")
ENTRY ("See also")
NORMAL ("To start a program from the command line instead and sending it a message, "
	"you would not use #sendpraat, but instead run the program with a script file as an argument. "
	"See @@Scripting 6.9. Calling from the command line@.")
MAN_END

MAN_BEGIN ("Scripting 8.2. The sendpraat program", "ppgb", 20000927)
INTRO ("A Unix or DOS console program for sending messages to %running programs that use the @@Praat shell@.")
ENTRY ("Syntax")
CODE ("#sendpraat [%timeOut] %program %message...")
NORMAL ("For the meaning of the arguments, see @@Scripting 8.1. The sendpraat subroutine|the sendpraat subroutine@.")
ENTRY ("Example 1: killing a program")
CODE ("sendpraat 0 praat Quit")
NORMAL ("Causes the program #Praat to quit (gracefully), because #Quit is a fixed command in the Control menu. "
	"On Unix, #sendpraat returns immediately; on Windows, you leave out the %timeOut argument.")
ENTRY ("Example 2: playing a sound file in reverse")
CODE ("sendpraat 1000 praat \"Read from file... hello.wav\" \"Play reverse\" \"Remove\"")
NORMAL ("This works because ##Play reverse# is an action command "
	"that becomes available in the dynamic menu of the #Praat program when a Sound is selected. "
	"On Unix, sendpraat will allow #Praat at most 1000 seconds to perform this.")
NORMAL ("Each line is a separate argument. Lines that contain spaces should be put inside double quotes.")
ENTRY ("Example 3: drawing")
CODE ("sendpraat als \"for i from 1 to 5\" \"Draw circle... 0.5 0.5 i\" \"endfor\"")
NORMAL ("This causes the program #Als to draw five concentric circles into the Picture window.")
ENTRY ("Example 4: executing a large script")
CODE ("sendpraat praat \"execute doAll.praat 20\"")
NORMAL ("This causes the program #Praat to execute the script ##doAll.praat# with an argument of \"20\".")
MAN_END

MAN_BEGIN ("Scripting 8.3. The sendpraat directive", "ppgb", 20000927)
INTRO ("Besides being a subroutine (@@Scripting 8.1. The sendpraat subroutine|\\SS8.1@) "
	"and a program (@@Scripting 8.2. The sendpraat program|\\SS8.2@), @sendpraat "
	"can also be called from within a Praat script.")
ENTRY ("Example 1: killing a program")
NORMAL ("Suppose we are in the Praat-shell program #Als, which is a browser for dictionaries, "
	"and we want to kill the Praat-shell program #Praat, which is a program for phonetics research:")
CODE ("sendpraat Praat Quit")
ENTRY ("Example 2: playing a sound")
NORMAL ("Suppose we are in the Praat-shell program #Als, which is a browser for dictionaries, "
	"and has no idea of what a %sound is. From this program, we can play a sound file "
	"by sending a message to the Praat-shell program #Praat, which does know about sounds:")
CODE ("fileName\\$  = \"hallo.wav\"")
CODE ("sendpraat Praat")
CODE ("...'newline\\$ ' Read from file... 'fileName\\$ '")
CODE ("...'newline\\$ ' Play")
CODE ("...'newline\\$ ' Remove")
NORMAL ("The first $$newline\\$ $ is superfluous, but this format reads nicely, what do you reckon?")
MAN_END

MAN_BEGIN ("ScriptEditor", "ppgb", 19991023)
INTRO ("An aid to @@scripting@.")
NORMAL ("The #ScriptEditor is a text editor that allows you to edit, save, and run "
	"any @@Praat script@. You could type such a script from scratch, "
	"but it is easier to use the @@History mechanism@, which automatically records "
	"all your commands and mouse clicks, and which can paste these directly "
	"into a #ScriptEditor.")
NORMAL ("To add a script as a button to a fixed or dynamic menu, "
	"use @@Add to fixed menu...@ or @@Add to dynamic menu...@ from the #File menu.")
ENTRY ("Example 1")
NORMAL ("In this example, we create a fixed button that will play a 1-second sine wave with a specified frequency.")
NORMAL ("First, we create a ScriptEditor by choosing @@New script@ from the Control menu. "
	"Then, we choose @@Clear history@ from the Edit menu in the ScriptEditor. "
	"We then perform some actions that will create a sine wave, play it, and remove it:")
LIST_ITEM ("1. Choose ##%%Create Sound...#% from the New menu and type the formula of a sine wave (i.e. "
	"remove the \"randomGauss\" term).")
LIST_ITEM ("2. Click #%Play in the dynamic menu.")
LIST_ITEM ("3. Click the fixed #%Remove button.")
NORMAL ("We then choose @@Paste history@ from the Edit menu in the ScriptEditor (or type Command-H). "
	"The text will now contain at least the following lines (delete any other lines):")
CODE ("Create Sound... sine 0 1 22050 1/2*sin(2*pi*377*x)")
CODE ("Play")
CODE ("Remove")
NORMAL ("We can run this script again by choosing #Run from the Run menu (or typing Command-R). "
	"However, this always plays a sine with a frequency of 377 Hz, so we will add the variable \"Frequency\" "
	"to the script, which then looks like:")
CODE ("#form Play a sine wave")
CODE ("   #positive Frequency")
CODE ("#endform")
CODE ("Create Sound... sine'Frequency' 0 1 22050 1/2*sin(2*pi*'Frequency'*x)")
CODE ("Play")
CODE ("Remove")
NORMAL ("When we choose #%Run, the ScriptEditor will ask us to supply a value for the \"Frequency\" variable. "
	"We can now play 1-second sine waves with any frequency. Note that the name of the temporary Sound "
	"is now \"sine356\" if %Frequency is \"356\": any occurrence of the string \"\'Frequency\'\" is replaced "
	"with the supplied argument.")
NORMAL ("It is advisable to supply a default value for each argument in your script. "
	"If the duration should be variable, too, the final script could look like:")
CODE ("#form Play a sine wave")
CODE ("   #positive Frequency 440")
CODE ("   #positive Duration 1")
CODE ("#endform")
CODE ("Create Sound... sine'Frequency' 0 'Duration' 22050 0.9*sin(2*pi*'Frequency'*x)")
CODE ("Play")
CODE ("Remove")
NORMAL ("When you run this script, the ScriptEditor will ask you to supply values for the two variables, "
	"but the values \"440\" and \"1\" are already visible in the dialog, "
	"so that you will get a sensible result if you just click #%OK.")
NORMAL ("If this script is useful to you, you may want to put a button for it in the #%New menu, "
	"in the ##%%Create Sound#% submenu:")
LIST_ITEM ("1. Save the script to a file, with #%Save from the #%File menu. The file name that you supply, will "
	"be shown in the title bar of the ScriptEditor window.")
LIST_ITEM ("2. Choose @@Add to fixed menu...@ from the #%File menu. Supply #%Objects for the %window, "
	"#%New for the %menu, \"Play sine wave...\" for the %command, "
	"##%%Create Sound...#% for %%after command%, and \"1\" for the depth (because it is supposed to be in a submenu); "
	"the %script argument has already been set to the file name that you supplied in step 1.")
LIST_ITEM ("3. Click #%OK and ensure that the button has been added in the #%New menu. This button will still be there "
	"after you leave the program and enter it again; to remove it from the menu, use the @ButtonEditor.")
ENTRY ("Example 2")
NORMAL ("In this example, we will create a shortcut for the usual complex pitch-analysis command.")
NORMAL ("First, we perform the required actions:")
LIST_ITEM ("1. Select a Sound object.")
LIST_ITEM ("2. Click ##%%To Pitch...#% and set the arguments to your personal defaults.")
LIST_ITEM ("3. Click #%OK. A new #Pitch object will appear.")
NORMAL ("We then paste the history into the ScriptEditor, after which this will contain at least a line like (delete all the other lines):")
CODE ("To Pitch... 0.01 150 900")
NORMAL ("You can run this script only after selecting one or more Sound objects.")
NORMAL ("If this script is useful to you, you may want to put a button for it in the dynamic menu:")
LIST_ITEM ("1. Save the script to a file, with #%Save from the #%File menu.")
LIST_ITEM ("2. Choose @@Add to dynamic menu...@ from the #%File menu. Supply \"Sound\" for %class1 "
	"(because the button is supposed to be available only if a Sound is selected), \"0\" for %number1 "
	"(because the command is supposed to work for any number of selected Sound objects), "
	"\"To Pitch (child)\" for the %command, "
	"\"To Spectrum\" for %%after command%, and \"0\" for the depth (because it is not supposed to be in a submenu); "
	"the %script argument has already been set to the file name that you supplied in step 1.")
LIST_ITEM ("3. Click #OK and ensure that the button is clickable if you select one or more Sound objects. "
	"This button will still be available after you leave the program and enter it again; "
	"to remove it from the dynamic menus, use the @ButtonEditor.")
MAN_END

MAN_BEGIN ("undefined", "ppgb", 19980825)
INTRO ("A special value that the query commands sometimes write into the @@Info window@, "
	"where the value %undefined is written as ##--undefined--# (two hyphens at both sides of the word).")
ENTRY ("Usage")
NORMAL ("You will often use this value in a @@Praat script@ to test whether "
	"a query command returned a valid number:")
CODE ("select Pitch hallo")
CODE ("meanPitch = Get mean... 0.1 0.2 Hertz Parabolic")
CODE ("if meanPitch = undefined")
CODE ("  \\#  Take some exceptional action.")
CODE ("else")
CODE ("  \\#  Take the normal action.")
CODE ("endif")
ENTRY ("Behaviour")
NORMAL ("In text files, this value is written as ##--undefined--#. "
	"In binary files, it is written as a big-endian IEEE positive infinity.")
NORMAL ("In memory, it is the ANSI-C constant HUGE_VAL, which equals infinity "
	"on IEEE machines.")
MAN_END

}

/* End of file manual_Script.c */
