/* manual_Fon.c
 *
 * Copyright (C) 1992-2003 Paul Boersma
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or (at
 * your option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * See the GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

#include "ManPagesM.h"

#include "Sound.h"

static void draw_CreateDurationTier (Graphics g) {
	static float x [] = { 0, 0.3, 0.6, 0.7, 0.9 }, y [] = { 1, 1, 2.3, 1, 1 };
	Graphics_setWindow (g, 0, 0.9, 0, 2.5);
	Graphics_drawInnerBox (g);
	Graphics_marksLeftEvery (g, 1, 1, TRUE, TRUE, FALSE);
	Graphics_marksBottomEvery (g, 1, 0.1, TRUE, TRUE, FALSE);
	Graphics_setInner (g);
	Graphics_setColour (g, Graphics_RED);
	Graphics_polyline (g, 5, x, y);
	Graphics_setColour (g, Graphics_BLACK);
	Graphics_unsetInner (g);
	Graphics_textBottom (g, TRUE, "Time (s)");
	Graphics_textLeft (g, TRUE, "Relative duration");
}

static void draw_SoundDeepen_filter (Graphics g) {
	Sound s = Sound_createSimple (100, 10);
	int i;
	double alpha = sqrt (log (2.0));
	if (! s) return;
	Graphics_setWindow (g, 0, 100, 0, 1);
	for (i = 1; i <= s -> nx; i ++) {
		double alpha_f = alpha * (s -> x1 + (i - 1) * s -> dx);
		double slow = alpha_f / 3.0, fast = alpha_f / 30.0;
		s -> z [1] [i] = exp (- fast * fast) - exp (- slow * slow);
	}
	Graphics_drawInnerBox (g);
	Graphics_textBottom (g, TRUE, "Frequency %f (Hz)");
	Graphics_textLeft (g, TRUE, "Intensity filter %H (%f)");
	Graphics_markLeft (g, 0, TRUE, TRUE, FALSE, NULL);
	Graphics_markLeft (g, 0.5, TRUE, TRUE, TRUE, NULL);
	Graphics_markLeft (g, 1, TRUE, TRUE, FALSE, NULL);
	Graphics_markRight (g, 1, FALSE, TRUE, FALSE, "0 dB");
	Graphics_markRight (g, 0.5, FALSE, TRUE, FALSE, "-6 dB");
	Graphics_markBottom (g, 0, TRUE, TRUE, FALSE, NULL);
	Graphics_markBottom (g, 3, TRUE, TRUE, TRUE, NULL);
	Graphics_markBottom (g, 30, TRUE, TRUE, TRUE, NULL);
	Graphics_markBottom (g, 100, TRUE, TRUE, FALSE, NULL);
	Graphics_setColour (g, Graphics_RED);
	Sound_draw (s, g, 0, 0, 0, 1, FALSE);
	Graphics_setColour (g, Graphics_BLACK);
	forget (s);
}

static void draw_SoundDeepen_impulse (Graphics g) {
	Sound s = Sound_create (-0.2, 0.2, 1000, 4e-4, -0.1998);
	int i;
	double pibyalpha = NUMpi / sqrt (log (2.0)), twosqrtpitimespibyalpha = 2 * sqrt (NUMpi) * pibyalpha;
	if (! s) return;
	Graphics_setWindow (g, -0.2, 0.2, -100, 400);
	for (i = 1; i <= s -> nx; i ++) {
		double pibyalpha_f = pibyalpha * (s -> x1 + (i - 1) * s -> dx);
		double slow = pibyalpha_f * 3.0, fast = pibyalpha_f * 30.0;
		s -> z [1] [i] = twosqrtpitimespibyalpha * (30.0 * exp (- fast * fast) - 3.0 * exp (- slow * slow));
	}
	Graphics_drawInnerBox (g);
	Graphics_textBottom (g, TRUE, "Time %t (s)");
	Graphics_textLeft (g, TRUE, "Intensity impulse reponse %h (%t)");
	Graphics_markBottom (g, -0.2, TRUE, TRUE, FALSE, NULL);
	Graphics_markBottom (g, 0, TRUE, TRUE, TRUE, NULL);
	Graphics_markBottom (g, 0.2, TRUE, TRUE, FALSE, NULL);
	Graphics_markLeft (g, 0, TRUE, TRUE, TRUE, NULL);
	Graphics_setColour (g, Graphics_RED);
	Sound_draw (s, g, 0, 0, -100, 400, FALSE);
	Graphics_setColour (g, Graphics_BLACK);
	forget (s);
}

static void draw_SpectrumHann (Graphics g, double f1, double f2, int stop, int garnish) {
	double fmin = garnish == 1 ? 300 : 0, fmax = garnish == 1 ? 1300 : 4000, df = garnish == 1 ? 1 : 4;
	Sound me = Sound_create (fmin, fmax, (fmax - fmin) / df + 1, df, fmin);
	double w = 100, f1left = f1 - w, f1right = f1 + w, f2left = f2 - w, f2right = f2 + w, halfpibysmooth = NUMpi / (w + w);
	int i;
	if (! me) return;
	Graphics_setWindow (g, fmin, fmax, -0.1, 1.1);
	for (i = 1; i <= my nx; i ++) {
		double f = my x1 + (i - 1) * my dx;
		my z [1] [i] = f < f1left ? 0.0 : f < f1right ? ( f1 > 0.0 ? 0.5 - 0.5 * cos (halfpibysmooth * (f - f1left)) : 1.0 ) :
			f < f2left ? 1.0 : f < f2right ? ( f2 < fmax ? 0.5 + 0.5 * cos (halfpibysmooth * (f - f2left)) : 1.0 ) : 0.0;
	}
	if (stop)
		for (i = 1; i <= my nx; i ++)
			my z [1] [i] = 1.0 - my z [1] [i];
	if (garnish) {
		Graphics_drawInnerBox (g);
		Graphics_textLeft (g, TRUE, "Intensity filter %H (%f)");
		Graphics_markLeft (g, 0, TRUE, TRUE, FALSE, NULL);
		Graphics_markLeft (g, 1, TRUE, TRUE, FALSE, NULL);
	}
	if (garnish == 1) {
		Graphics_textBottom (g, TRUE, "Frequency %f");
		Graphics_markBottom (g, f1left, FALSE, TRUE, TRUE, "%f__1_-%w");
		Graphics_markBottom (g, f1, FALSE, TRUE, TRUE, "%f__1_");
		Graphics_markBottom (g, f1right, FALSE, TRUE, TRUE, "%f__1_+%w");
		Graphics_markBottom (g, f2left, FALSE, TRUE, TRUE, "%f__2_-%w");
		Graphics_markBottom (g, f2, FALSE, TRUE, TRUE, "%f__2_");
		Graphics_markBottom (g, f2right, FALSE, TRUE, TRUE, "%f__2_+%w");
		Graphics_markRight (g, 1, FALSE, TRUE, FALSE, "0 dB");
		Graphics_markLeft (g, 0.5, TRUE, TRUE, TRUE, NULL);
		Graphics_markRight (g, 0.5, FALSE, TRUE, FALSE, "-6 dB");
	}
	if (garnish == 2) {
		Graphics_textBottom (g, TRUE, "Frequency %f (Hz)");
		Graphics_markBottom (g, 0, TRUE, TRUE, FALSE, NULL);
		Graphics_markBottom (g, 500, TRUE, TRUE, FALSE, NULL);
		Graphics_markBottom (g, 1000, TRUE, TRUE, FALSE, NULL);
		Graphics_markBottom (g, 2000, TRUE, TRUE, FALSE, NULL);
		Graphics_markBottom (g, 4000, TRUE, TRUE, FALSE, NULL);
	}
	Graphics_setColour (g, stop ? Graphics_BLUE : Graphics_RED);
	Sound_draw (me, g, 0, 0, -0.1, 1.1, FALSE);
	Graphics_setColour (g, Graphics_BLACK);
	forget (me);
}
static void draw_SpectrumPassHann (Graphics g) {
	draw_SpectrumHann (g, 500, 1000, 0, 1);
}
static void draw_SpectrumPassHann_decompose (Graphics g) {
	draw_SpectrumHann (g, 0, 500, 0, 2);
	draw_SpectrumHann (g, 500, 1000, 0, 0);
	draw_SpectrumHann (g, 1000, 2000, 0, 0);
	draw_SpectrumHann (g, 2000, 4000, 0, 0);
}
static void draw_SpectrumStopHann (Graphics g) { draw_SpectrumHann (g, 500, 1000, 1, 1); }
static void draw_SpectrumStopHann_decompose (Graphics g) {
	draw_SpectrumHann (g, 500, 1000, 0, 2);
	draw_SpectrumHann (g, 500, 1000, 1, 0);
}

void manual_Fon_init (ManPages me);
void manual_Fon_init (ManPages me) {

MAN_BEGIN ("Aliasing", "ppgb", 19980327)
INTRO ("Aliasing (Du. %vouwvervorming) is the phenomenon of the ambiguity "
	"of a sampled signal.")
ENTRY ("Example")
NORMAL ("With a sample rate of 10 kHz, a sine wave with a frequency of 3 kHz "
	"receives the same representation as a sine wave with a frequency of 7 kHz, "
	"13 kHz, or 17 kHz, and so on. If the sampled signal is meant to represent a "
	"continuous spectral range starting at 0 Hz "
	"(which is the most common case for speech recordings), "
	"all these tones are likely to be interpreted as 3 kHz tones after sampling.")
NORMAL ("To remedy this unwanted situation, the signal is usually low-pass filtered "
	"with a cut-off frequency just below 5 kHz, prior to sampling.")
MAN_END

MAN_BEGIN ("Get high index from time...", "ppgb", 20030216)
INTRO ("A @query to ask the selected tier object "
	"(@DurationTier, @FormantTier, @IntensityTier, @PitchTier, @TextTier) "
	"which point is nearest to, but no earlier than, the specified time.")
ENTRY ("Argument")
TAG ("%Time (s)")
DEFINITION ("the time from which you want to get the point index.")
ENTRY ("Return value")
NORMAL ("This query returns the index of the point with the lowest time greater than or equal to %time."
	"It is @undefined if there are no points. "
	"It is the number of points plus 1 (offright) if the specified time is greater than the time of the last point.")
MAN_END

MAN_BEGIN ("Get low index from time...", "ppgb", 20030216)
INTRO ("A @query to ask the selected tier object "
	"(@DurationTier, @FormantTier, @IntensityTier, @PitchTier, @TextTier) "
	"which point is nearest to, but no later than, the specified time.")
ENTRY ("Argument")
TAG ("%Time (s)")
DEFINITION ("the time from which you want to get the point index.")
ENTRY ("Return value")
NORMAL ("This query returns the index of the point with the highest time less than or equal to %time."
	"It is @undefined if there are no points. "
	"It is 0 (offleft) if the specified time is less than the time of the first point.")
MAN_END

MAN_BEGIN ("Get nearest index from time...", "ppgb", 20030216)
INTRO ("A @query to ask the selected tier object "
	"(@DurationTier, @FormantTier, @IntensityTier, @PitchTier, @TextTier) "
	"which point is nearest to the specified time.")
ENTRY ("Argument")
TAG ("%Time (s)")
DEFINITION ("the time near which you want to get the point index.")
ENTRY ("Return value")
NORMAL ("This query returns the index of the point with the highest time less than or equal to %time."
	"It is @undefined if there are no points.")
MAN_END

MAN_BEGIN ("Remove point...", "ppgb", 20030216)
INTRO ("A command to remove one point from every selected time-based tier object "
	"(@DurationTier, @FormantTier, @IntensityTier, @PitchTier, @TextTier).")
ENTRY ("Argument")
TAG ("%%Point number")
DEFINITION ("the index of the point you want to remove.")
ENTRY ("Behaviour")
NORMAL ("If %%point number% is 3, the third point counted from the start of the tier (if it exists) "
	"is removed from the tier.")
MAN_END

MAN_BEGIN ("Remove point near...", "ppgb", 20030216)
INTRO ("A command to remove one point from every selected time-based tier object "
	"(@DurationTier, @FormantTier, @IntensityTier, @PitchTier, @TextTier).")
ENTRY ("Argument")
TAG ("%Time (s)")
DEFINITION ("the time near which you want to remove a point.")
ENTRY ("Behaviour")
NORMAL ("The point nearest to %time (if there is any point) is removed from the tier.")
MAN_END

MAN_BEGIN ("Remove points between...", "ppgb", 20030216)
INTRO ("A command to remove some points from every selected time-based tier object "
	"(@DurationTier, @FormantTier, @IntensityTier, @PitchTier, @TextTier).")
ENTRY ("Arguments")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the times between which you want to remove all points.")
ENTRY ("Behaviour")
NORMAL ("Any points between %tmin and %tmax (inclusive) are removed from the tier.")
MAN_END

MAN_BEGIN ("Click", "ppgb", 19960913)
INTRO ("One of the ways to control @Editors.")
ENTRY ("How to click")
LIST_ITEM ("1. Position the mouse above the object that you want to click.")
LIST_ITEM ("2. Press and release the (left) mouse button.")
NORMAL ("See also @@Shift-click@.")
ENTRY ("Usage in the Praat program")
NORMAL ("Clicking on an object is used for selecting this object while deselecting "
	"all previously selected objects; clicking is also used for moving a cursor hair.")
MAN_END

MAN_BEGIN ("Cochleagram", "ppgb", 20030316)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}. It represents the excitation pattern "
	"of the basilar membrane in the inner ear (see @Excitation) as a function of time.")
MAN_END

MAN_BEGIN ("Cochleagram: Formula...", "ppgb", 20021206)
INTRO ("A command for changing the data in all selected @Cochleagram objects.")
NORMAL ("See the @Formulas tutorial for examples and explanations.")
MAN_END

MAN_BEGIN ("Create DurationTier...", "ppgb", 20021204)
INTRO ("A command in the @@New menu@ to create an empty @DurationTier object.")
NORMAL ("The resulting object will have the specified name and time domain, but contain no duration points. "
	"To add some points to it, use @@DurationTier: Add point...@.")
ENTRY ("Scripting example")
NORMAL ("To create a tier 0.9 seconds long, with an deceleration around 0.6 seconds, you do:")
CODE ("Create DurationTier... dur 0 0.9")
CODE ("Add point... 0.3 1")
CODE ("Add point... 0.6 2.3")
CODE ("Add point... 0.7 1")
NORMAL ("The result will look like")
PICTURE (5, 2.5, draw_CreateDurationTier)
NORMAL ("The target duration will be the area under this curve, which is 0.9 + 1/2 \\.c 1.3 \\.c 0.4 = 1.16 seconds.")
MAN_END

MAN_BEGIN ("Create empty PointProcess...", "ppgb", 20021204)
INTRO ("A command in the @@New menu@ to create an empty @PointProcess. The newly created object is put in the list of objects.")
MAN_END

MAN_BEGIN ("Create FormantTier...", "ppgb", 20021204)
INTRO ("A command in the @@New menu@ to create an empty @FormantTier object.")
NORMAL ("The resulting object will have the specified name and time domain, but contain no formant points. "
	"To add some points to it, use @@FormantTier: Add point...@.")
NORMAL ("For an example, see @@Source-filter synthesis@.")
MAN_END

MAN_BEGIN ("Create IntensityTier...", "ppgb", 20021204)
INTRO ("A command in the @@New menu@ to create an empty @IntensityTier object.")
NORMAL ("The resulting object will have the specified name and time domain, but contain no formant points. "
	"To add some points to it, use @@IntensityTier: Add point...@.")
NORMAL ("For an example, see @@Source-filter synthesis@.")
MAN_END

MAN_BEGIN ("Create Matrix...", "ppgb", 20021212)
INTRO ("A command in the @@New menu@ to create a @Matrix with the specified sampling attributes, "
	"filled with values from a formula (see @@Matrix: Formula...@).")
MAN_END

MAN_BEGIN ("Create PitchTier...", "ppgb", 20021204)
INTRO ("A command in the @@New menu@ to create an empty @PitchTier object.")
NORMAL ("The resulting object will have the specified name and time domain, but contain no formant points. "
	"To add some points to it, use @@PitchTier: Add point...@.")
NORMAL ("For an example, see @@Source-filter synthesis@.")
MAN_END

MAN_BEGIN ("Create Poisson process...", "ppgb", 19970402)
INTRO ("A command to create a @PointProcess object that represents a Poisson process.")
NORMAL ("A Poisson process is a stationary point process with a fixed density %\\la, "
	"which means that there are, on the average, %\\la events per second.")
ENTRY ("Arguments")
TAG ("%%Starting time% (seconds)")
DEFINITION ("%t__%min_, the beginning of the time domain.")
TAG ("%%Finishing time% (seconds)")
DEFINITION ("%t__%max_, the end of the time domain.")
TAG ("%Density (Hertz)")
DEFINITION ("the average number of points per second.")
ENTRY ("Algorithm")
NORMAL ("First, the number of points %N in the time domain is determined. Its expectation value is")
FORMULA ("%\\la = (%t__%max_ \\-- %t__%min_) \\.c %density")
NORMAL ("but its actual value is taken from the Poisson distribution:")
FORMULA ("%p(%n) = (%%\\la ^n% / %n!) %e^^\\--%\\la")
NORMAL ("Then, %N points are computed throughout the time domain, according to a uniform distribution:")
FORMULA ("%p(%t) = 1 / (%t__%max_ \\-- %t__%min_)   for %t \\e= [%t__%min_, %t__%max_]")
FORMULA ("%p(%t) = 0   outside [%t__%min_, %t__%max_]")
ENTRY ("C implementation")
PROTOTYPE ("##PointProcess PointProcess_createPoisson (double #%tmin##, double #%tmax##, double #%density##);")
MAN_END

MAN_BEGIN ("Create simple Matrix...", "ppgb", 20021204)
INTRO ("A command in the @@New menu@ to create a @Matrix with the specified number of rows and columns, "
	"filled with values from a formula (see @@Matrix: Formula...@).")
MAN_END

MAN_BEGIN ("Create Sound...", "ppgb", 20021206)
INTRO ("A command in the @@New menu@ to create a @Sound with a specified duration and sampling frequency, "
	"filled with values from a formula.")
NORMAL ("See the @Formulas tutorial for explanations and examples.")
/*
Create Sound... blok 0 1 22050 if round(x*377*2) mod 2 then 0.9 else -0.9 fi

Je kunt dus heel veel maken met een scriptje:

form Blokgolf
   word Naam blok
   real Begintijd_(s) 0.0
   real Eindtijd_(s) 1.0
   positive Samplefrequentie_(Hz) 22050
   positive Frequentie_(Hz) 377
   real Amplitude 0.9
endform
Create Sound... 'Naam' Begintijd Eindtijd Samplefrequentie
   ... if round(x*'Frequentie'*2) mod 2 then 'Amplitude' else -'Amplitude' fi
*/
MAN_END

MAN_BEGIN ("Create Sound from tone complex...", "ppgb", 20021223)
INTRO ("A command in the @@New menu@ to create a @Sound as the sum of a number of sine waves "
	"with equidistant frequencies.")
ENTRY ("Arguments")
TAG ("%Name")
DEFINITION ("the name of the resulting Sound object.")
TAG ("%%Starting time%, %%End time% (s)")
DEFINITION ("the time domain of the resulting Sound.")
TAG ("%%Sample rate% (Hz)")
DEFINITION ("the sampling frequency of the resulting Sound.")
TAG ("%Phase")
DEFINITION ("determines whether the result is a sum of %sines or a sum of %cosines, "
	"i.e., whether the zero crossings or the maxima of the components are synchronized. "
	"This choice has little perceptual consequences.")
TAG ("%%Frequency step% (Hz)")
DEFINITION ("the distance between the components. In first approximation, "
	"this is the perceived fundamental frequency.")
TAG ("%%First frequency% (Hz)")
DEFINITION ("the lowest frequency component. If you supply a value of 0, "
	"%firstFrequency is taken equal to %frequencyStep.")
TAG ("%%Ceiling% (Hz)")
DEFINITION ("the frequency above which no components are used. If you supply a value of 0 "
	"or a value above the Sound's @@Nyquist frequency@, %ceiling is taken equal to "
	"the Nyquist frequency.")
TAG ("%%Number of components")
DEFINITION ("determines how many sinusoids are used. If you supply a value of 0 "
	"or a very high value, the maximum number of components is used, "
	"limited by %ceiling.")
ENTRY ("Example 1: a pulse train")
NORMAL ("A series of pulses at regular intervals, "
	"sampled after low-pass filtering at the Nyquist frequency, "
	"can be regarded as a sum of cosine waves. For instance, a 100-Hz pulse train, "
	"sampled at 22050 Hz, can be created with:")
CODE ("Create Sound from tone complex... train 0 1 22050 Cosine 100 0 0 0")
NORMAL ("Supplying the value 0 for %firstFrequency yields an unshifted harmonic complex.")
ENTRY ("Example 2: a shifted harmonic complex")
NORMAL ("Some experiments on human pitch perception (%%residue pitch%) use "
	"a number of sinusoidal components with harmonically "
	"related frequencies that are all shifted by a constant amount.")
NORMAL ("For instance, to get a sum of sine waves with frequencies 105 Hz, 205 Hz, and 305 Hz, "
	"you would use:")
CODE ("Create Sound from tone complex... train 0.3 1 22050 Sine 100 105 0 3")
NORMAL ("or")
CODE ("Create Sound from tone complex... train 0.3 1 22050 Sine 100 105 350 0")
NORMAL ("whichever you prefer.")
NORMAL ("Some of these experiments are described in @@Plomp (1967)@ and @@Patterson & Wightman (1976)@.")
ENTRY ("Algorithm")
NORMAL ("For the `sine' phase, the resulting Sound is given by the following formula:")
NORMAL ("%x(%t) = \\su__%i=1..%numberOfComponents_ sin (2%\\pi\\.c(%firstFrequency + "
	"(%i\\--1)\\.c%frequencyStep)\\.c%t)")
ENTRY ("More flexibility?")
NORMAL ("Suppose you wanted to vary the relative strengths of the frequency components. "
	"You could achieve this by creating a Sound with the command discussed here, "
	"take its Fourier transform, run a formula on the resulting Spectrum, "
	"and take the inverse Fourier transform.")
NORMAL ("A more general approach is described shortly.")
NORMAL ("Suppose you need a sum of sine waves with frequencies 105, 205, 305, ..., 1905 Hz, "
	"and with relative amplitudes 1, 1/2, 1/3, ..., 1/19. You could build a script that computes "
	"the various components, and add them to each other as you go along. Instead of calling 19 "
	"scripts, however, you can achieve this with the following more general script:")
CODE ("form Add waves with decreasing amplitudes")
CODE1 ("Number_of_components 19")
CODE ("endform")
CODE ("\\#  Create a Matrix with frequency and amplitude information in each row:")
CODE ("Create simple Matrix... freqAndGain number_of_components 2 0")
CODE ("Formula... if col = 1 then row * 100 + 5 else 1 / row fi")
CODE ("\\#  Create a large Matrix with all the component sine waves:")
CODE ("Create Matrix... components 0 1 10000 1e-4 0.5e-4 1 number_of_components number_of_components 1 1 0")
CODE ("Formula... Matrix_freqAndGain [2] * sin (2 * pi * Matrix_freqAndGain [1] * x)")
CODE ("\\#  Integrate:")
CODE ("Formula... self + self [row - 1, col]")
CODE ("\\#  Publish last row:")
CODE ("To Sound (slice)... number_of_components")
CODE ("Scale amplitudes... 0.99")
MAN_END

MAN_BEGIN ("Create Strings as file list...", "ppgb", 19980630)
INTRO ("A command to create a @Strings object from a list of file in a given directory.")
ENTRY ("Argument")
TAG ("%%Path")
DEFINITION ("the directory name, with an optional wildcard for selecting files.")
ENTRY ("Behaviour")
NORMAL ("The resulting Strings object will contain an alphabetical list of file names, "
	"without any preceding directory names. In contrast with what the restrictions in Praat, "
	"this object may contain zero strings.")
ENTRY ("Usage")
NORMAL ("First, you could specify a directory name only. On Unix, you would type "
	"##/usr/people/miep/sounds# or ##/usr/people/miep/sounds/#. On Windows, "
	"##C:\\bsMiep\\bsSounds# or ##C:\\bsMiep\\bsSounds\\bs#. On Macintosh, "
	"##Macintosh HD:Sounds# or ##Macintosh HD:Sounds:#. Any of these return "
	"a list of all the files in the specified directory.")
NORMAL ("Secondly, you could specify a wildcard (a single asterisk) for the file names. "
	"To get a list of all the files whose names start with \"hal\" and end in \".aifc\", "
	"type ##/usr/people/miep/sounds/hal*.aifc#, ##C:\\bsMiep\\bsSounds\\bshal*.aifc#, "
	"or ##Macintosh HD:Sounds:hal*.aifc#.")
ENTRY ("Script usage")
NORMAL ("In a script, you can use this command to cycle through the files in a directory. "
	"For instance, to read in all the sound files in a specified directory, "
	"you could use the following script:")
CODE ("directory\\$  = \"/usr/people/miep/sounds\"")
CODE ("Create Strings as file list... list 'directory\\$ '/*.aifc")
CODE ("numberOfFiles = Get number of strings")
CODE ("for ifile to numberOfFiles")
CODE ("   select Strings list")
CODE ("   fileName\\$  = Get string... ifile")
CODE ("   Read from file... 'directory\\$ '/'fileName\\$ '")
CODE ("endfor")
MAN_END

MAN_BEGIN ("Create TextGrid...", "ppgb", 19970316)
INTRO ("A command to create a @TextGrid from scratch.")
ENTRY ("Arguments")
TAG ("%%From time (seconds)")
DEFINITION ("the starting time, usually 0 seconds.")
TAG ("%%To time (seconds)")
DEFINITION ("the end time, usually the duration.")
TAG ("%%Tier names")
DEFINITION ("a list of the names of the tiers that you want to create, separated by spaces.")
TAG ("%%Point tiers")
DEFINITION ("a list of the names of the tiers that you want to be %%point tiers%; "
	"the rest of the tiers will be %%interval tiers%.")
MAN_END

MAN_BEGIN ("Distributions", "ppgb", 20030316)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}. Inherits most actions from @TableOfReal.")
ENTRY ("Actions")
LIST_ITEM ("@@Distributions: To Strings...@")
MAN_END

MAN_BEGIN ("Distributions: To Strings...", "ppgb", 19971022)
INTRO ("A command to create a @Strings object from every selected @Distributions object.")
ENTRY ("Arguments")
TAG ("%%Column number")
DEFINITION ("the column (in the #Distributions object) that contains the distribution that you are "
	"interested in. Often the #Distributions object will only contain a single distribution, "
	"so this argument will often be 1. If the #Distributions object contains nine distributions, "
	"specify any number between 1 and 9.")
TAG ("%%Number of strings")
DEFINITION ("the number of times a string will be drawn from the chosen distribution. "
	"This is the number of strings that the resulting @Strings object is going to contain.")
ENTRY ("Behaviour")
NORMAL ("Every string in the resulting #Strings object will be a row label of the #Distributions object. "
	"The number in each row at the specified column will be considered the relative frequency of "
	"occurrence of that row.")
NORMAL ("%#Example. Suppose we have the following #Distributions:")
CODE ("File type = \"ooTextFile\"")
CODE ("Object class = \"Distributions\"")
CODE ("2 (number of columns)")
CODE ("         \"English\"  \"French\" (column labels)")
CODE ("3 (number of rows)")
CODE ("\"the\"     108        1.5")
CODE ("\"a\"       58.1       33")
CODE ("\"pour\"    0.7        15.5")
NORMAL ("If you set %Column to 1 and %%Number of strings% to 1000, "
	"you will get a @Strings object with approximately 647 occurrences of \"the\", "
	"348 occurrences of \"a\", and 4 occurrences of \"pour\". "
	"If you had set %Column to 2 (\"French\"), you would have gotten about "
	"30 times \"the\", 660 times \"a\", and 310 times \"pour\". "
	"The actual numbers will vary because the choice of a string will not depend on previous choices.")
MAN_END

MAN_BEGIN ("Drag", "ppgb", 19960913)
INTRO ("Dragging is one of the ways to control @Editors.")
ENTRY ("How to drag")
LIST_ITEM ("1. Position the mouse above the object that you want to drag.")
LIST_ITEM ("2. Press the (left) mouse button.")
LIST_ITEM ("3. Keeping the mouse button pressed, move the mouse across the window. "
	"A shadow of the object will follow.")
LIST_ITEM ("4. Release the mouse button when it is above the location where you want your object "
	"to be moved (the %drop %site). If the drop site makes any sense, "
	"the object will move there.")
NORMAL ("See also @@Shift-drag@.")
ENTRY ("Usage in the Praat program")
NORMAL ("Dragging is used for manipulating the time and value of one or more marks, targets, or boundaries:")
MAN_END

MAN_BEGIN ("DurationTier", "ppgb", 20030316)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}. "
	"A DurationTier object contains a number of (%time, %duration) points, "
	"where %duration is to be interpreted as a relative duration (e.g. the duration of a manipulated sound "
	"as compared to the duration of the original). For instance, "
	"if your DurationTier contains two points, one with a duration value of 1.5 at a time of 0.5 seconds "
	"and one with a duration value of 0.6 at a time of 1.1 seconds, this is to be interpreted as "
	"a relative duration of 1.5 (i.e. a slowing down) for all original times before 0.5 seconds, "
	"a relative duration of 0.6 (i.e. a speeding up) for all original times after 1.1 seconds, "
	"and a linear interpolation between 0.5 and 1.1 seconds (e.g. a relative duration of "
	"1.2 at 0.7 seconds, and of 0.9 at 0.9 seconds).")
NORMAL ("See @@Intro 8.2. Manipulation of duration@ and @@Create DurationTier...@.")
MAN_END

MAN_BEGIN ("DurationTier: Add point...", "ppgb", 20030216)
INTRO ("A command to add a point to each selected @DurationTier. "
	"For an example, see @@Create DurationTier...@.")
ENTRY ("Arguments")
TAG ("%Time (s)")
DEFINITION ("the time at which a point is to be added.")
TAG ("%%Relative duration")
DEFINITION ("the relative duration value of the requested new point.")
ENTRY ("Behaviour")
NORMAL ("The tier is modified so that it contains the new point. "
	"If a point at the specified time was already present in the tier, nothing happens.")
MAN_END

MAN_BEGIN ("DurationTier: Get target duration...", "ppgb", 19991016)
INTRO ("A @query to the selected @DurationTier for the target duration of a specified time range.")
ENTRY ("Arguments")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the start and end of the time range. If %fromTime or %toTime is outside the time domain "
	"of the Duration object, there will be .")
ENTRY ("Return value")
NORMAL ("the target duration in seconds.")
MAN_END

MAN_BEGIN ("DurationTierEditor", "ppgb", 20010330)
INTRO ("One of the @editors in the Praat program, for viewing and editing a @DurationTier object. "
	"To create a DurationTierEditor window, select a DurationTier and click Edit.")
MAN_END

MAN_BEGIN ("Editors", "ppgb", 20030316)
INTRO ("Many @@types of objects@ in P\\s{RAAT} can be viewed and edited in their own windows.")
ENTRY ("Editors")
LIST_ITEM ("\\bu @SoundEditor")
LIST_ITEM ("\\bu @LongSoundEditor")
LIST_ITEM ("\\bu @TextGridEditor")
LIST_ITEM ("\\bu @ManipulationEditor")
LIST_ITEM ("\\bu @SpectrumEditor")
LIST_ITEM ("\\bu @PitchEditor")
LIST_ITEM ("\\bu @PointEditor")
LIST_ITEM ("\\bu @PitchTierEditor")
LIST_ITEM ("\\bu @IntensityTierEditor")
LIST_ITEM ("\\bu @DurationTierEditor")
LIST_ITEM ("\\bu #SpectrogramEditor")
LIST_ITEM ("\\bu #ArtwordEditor")
LIST_ITEM ("\\bu @OTGrammarEditor")
LIST_ITEM ("\\bu @OTAnyGrammarEditor")
LIST_ITEM ("\\bu #DataEditor (see @Inspect)")
ENTRY ("How to raise an editor")
NORMAL ("To bring up a class-specific editor window, select the appropriate object and choose #Edit "
	"(if the #Edit button exists, it is usually at the top of the @@Dynamic menu@). "
	"The name of the object will appear as the title of the editor window.")
NORMAL ("Some objects may have different commands, like #View (read-only) or #Surf (hypertext-based).")
NORMAL ("To bring up a DataEditor, select one object and click the @Inspect button.")
ENTRY ("General behaviour")
NORMAL ("Changes that you make to an object in its editor window will take effect immediately "
	"(you do not have close the editor window before going on with the changed object).")
NORMAL ("If you @Remove an object that you are viewing or editing from the @@List of Objects@, "
	"the editor window will automatically disappear from the screen.")
NORMAL ("All editors are independent windows: you can minimize and maximize them; "
	"if an editor window goes hiding behind another window, "
	"you can raise it by choosing the #Edit command again.")
NORMAL ("If you rename an object that you are viewing or editing (with @@Rename...@, "
	"the title of the editor window will be changed to the new name.")
ENTRY ("Ways to control an editor")
LIST_ITEM ("\\bu @@Click")
LIST_ITEM ("\\bu @@Shift-click")
LIST_ITEM ("\\bu @@Drag")
LIST_ITEM ("\\bu @@Shift-drag")
LIST_ITEM ("\\bu @@Time selection")
LIST_ITEM ("\\bu @@Keyboard shortcuts")
MAN_END

MAN_BEGIN ("Excitation", "ppgb", 20030316)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}. It represents the excitation pattern "
	"of the basilar membrane in the inner ear.")
ENTRY ("Inside an Excitation object")
NORMAL ("With @Inspect, you will see the following attributes.")
TAG ("%xmin = 0")
DEFINITION ("minimum place or frequency (Bark).")
TAG ("%xmax = 25.6 Bark")
DEFINITION ("maximum place or frequency (Bark).")
TAG ("%nx")
DEFINITION ("number of places or frequencies.")
TAG ("%dx = 25.6 / %nx")
DEFINITION ("Place or frequency step (Bark).")
TAG ("%x1 = %dx / 2")
DEFINITION ("centre of first place or frequency band (Bark).")
TAG ("%ymin = %ymax = %dy = %y__1_ = 1; %ny = 1")
DEFINITION ("dummies.")
TAG ("%z [1]")
DEFINITION ("intensity (sensation level) in phon.")
MAN_END

MAN_BEGIN ("Excitation: Formula...", "ppgb", 20021206)
INTRO ("A command for changing the data in all selected @Excitation objects.")
NORMAL ("See the @Formulas tutorial for examples and explanations.")
MAN_END

MAN_BEGIN ("Excitation: Get loudness", "ppgb", 19991016)
INTRO ("A @query to ask the selected @Excitation object for its loudness.")
ENTRY ("Return value")
NORMAL ("the loudness in sone units.")
ENTRY ("Algorithm")
NORMAL ("The loudness is defined as")
FORMULA ("\\in%df 2^^(%e(%f) - 40 phon) / 10^")
NORMAL ("where %f is the frequency in Bark, and %e(%f) the excitation in phon. "
	"For our discrete Excitation object, the loudness is computed as")
FORMULA ("\\De%f \\su 2^^(%e__%i_ - 40) / 10")
NORMAL ("where \\De%f is the distance between the excitation channels (in Bark).")
MAN_END

MAN_BEGIN ("Excitation_hertzToBark", "ppgb", 19970401)
INTRO ("A routine for converting frequency into basilar place, "
	"the inverse of @Excitation_barkToHertz.")
ENTRY ("Syntax")
PROTOTYPE ("##double Excitation_hertzToBark (double #%hertz##);")
ENTRY ("Algorithm")
NORMAL ("Returns 7 \\.c ln (%hertz / 650 + \\Vr (1 + (%hertz / 650)^2)).")
MAN_END

MAN_BEGIN ("Excitation_barkToHertz", "ppgb", 19970401)
INTRO ("A routine for converting basilar place into frequency, "
	"the inverse of @Excitation_hertzToBark.")
ENTRY ("Syntax")
PROTOTYPE ("##double Excitation_barkToHertz (double #%bark##);")
ENTRY ("Algorithm")
NORMAL ("Returns 650 \\.c sinh (%bark / 7).")
MAN_END

/*
double Excitation_soundPressureToPhon (double soundPressure, double bark);
Uses auditory filter (width apx. 1 Bark) for masking.

Excitation Excitation_create (double df, long nf);
	Function:
		return a new instance of Excitation, or NULL if out of memory.
	Preconditions:
		df > 0.0;
		nf >= 1;
	Postconditions:
		result -> xmin == 0.0;		result -> ymin == 1;
		result -> xmax == 25.6;		result -> ymax == 1;
		result -> nx == nf;			result -> ny == 1;
		result -> dx == df;			result -> dy == 1;
		result -> x1 == 0.5 * df;		result -> y1 == 1;
		result -> z [1] [1..nt] == 0.0;
double Excitation_getDistance (Excitation me, Excitation thee);

void Excitation_draw (Excitation me, Graphics g, double fmin, double fmax, double minimum, double maximum, int garnish);

Matrix Excitation_to_Matrix (Excitation me);
	Function:
		Create a Matrix from an Excitation,
		with deep copy of all of its Matrix attributes, except class information and methods.
	Return NULL if out of memory.  
Excitation Matrix_to_Excitation (Matrix me);
	Function:
		create an Excitation from a Matrix.
		Return NULL if out of memory.
	Postconditions:
		thy xmin == 0.0;
		thy xmax == my nx / (1 / my dx);
		thy nx == my nx;
		thy dx == 1 / (1 / my dx);
		thy x1 == 0.5 * thy dx;
		thy ymin ymax ny dy y1 == 1;
		thy z [1] [...] == my z [1] [...];
*/

/*"Any object of one of the types Polygon, PointProcess, Sound, Pitch, Spectrum,\n"
"Spectrogram, Excitation, Cochleagram, VocalTract\n"
"is convertible to and from a Matrix.\n"
"This allows extra hacking and drawing possibilities.\n"
"For example, to square the y values of a Polygon, do the following:\n"
"   select a Polygon, click on `To Matrix', click on `Formula...',\n"
"   type \"self * if row=1 then 1 else self fi\", click on `To Polygon'."*/

MAN_BEGIN ("Fast Fourier Transform", "ppgb", 20031105)
INTRO ("An algorithm for fast computation of the Fourier transform of a sampled signal. "
	"It involves increasing the number of samples %N to the next-highest power of two, "
	"and the computation time scales as %N log %N.")
NORMAL ("In Praat, the Fast Fourier Transform is used:")
LIST_ITEM ("1. For the Fourier transform of an entire sound. See @@Sound: To Spectrum (fft)@ "
	"and @@Spectrum: To Sound (fft)@.")
LIST_ITEM ("2. For the Fourier transform of consecutive frames in a sound. See @@Sound: To Spectrogram...@.")
LIST_ITEM ("3. For the fast computation of correlations, e.g. in @@Sound: To Pitch (ac)...@.")
MAN_END

MAN_BEGIN ("FFT", "ppgb", 20011121)
INTRO ("An abbreviation for @@Fast Fourier Transform@.")
MAN_END

MAN_BEGIN ("Formant", "ppgb", 20030316)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}. "
	"A Formant object represents spectral structure as a function of time: a %%formant contour%. "
	"Unlike the time-stamped @FormantTier object, it is sampled into a number of %frames centred around equally spaced times, "
	"Each frame contains frequency and bandwidth information about several formants.")
ENTRY ("Inside a Formant object")
NORMAL ("With @Inspect, you will see the following attributes:")
TAG ("%xmin")
DEFINITION ("starting time, in seconds.")
TAG ("%xmax")
DEFINITION ("end time, in seconds.")
TAG ("%nx")
DEFINITION ("the number of frames (\\>_ 1).")
TAG ("%dx")
DEFINITION ("time step = frame length = frame duration, in seconds.")
TAG ("%x1")
DEFINITION ("the time associated with the first frame, in seconds. "
	"This will usually be in the range [%xmin, %xmax]. "
	"The time associated with the last frame (i.e., %x1 + (%nx \\-- 1) %dx)) "
	"will also usually be in that range.")
TAG ("%frame__%i_, %i = 1 ... %nx")
DEFINITION ("the frames (see below).")
ENTRY ("Attributes of a formant frame")
NORMAL ("Each %frame__%i_ contains the following attributes:")
TAG ("%intensity")
DEFINITION ("an indication of the maximum intensity (a squared sound amplitude) in this frame.")
TAG ("%nFormants")
DEFINITION ("the number of formants in this frame (usually between 2 and 6).")
TAG ("%formant__%j_, %j = 1 ... %nFormants")
DEFINITION ("the information about each formant (see below).")
ENTRY ("Attributes of each formant")
NORMAL ("Each %formant__%j_ contains the following attributes:")
TAG ("%frequency")
DEFINITION ("the formant's centre frequency (in Hz).")
TAG ("%bandwidth")
DEFINITION ("the formant's bandwidth (in Hz).")
ENTRY ("See also")
NORMAL ("##Linear Prediction#")
MAN_END

MAN_BEGIN ("Formant analysis...", "ppgb", 20030916)
INTRO ("The analysis parameters for formant contours in the @SoundEditor, "
	"@LongSoundEditor, and @TextGridEditor windows. These settings will be remembered across Praat sessions.")
NORMAL ("For the meaning of these settings, see @@Sound: To Formant (burg)...@. The %%number of poles% "
	"setting determines the number of poles in the linear predictive analysis. The standard value is 10, "
	"which means that 5 formants will be detected.")
MAN_END

MAN_BEGIN ("Formant: Down to FormantTier", "ppgb", 19980101)
INTRO ("A command for converting each selected @Formant object into a @FormantTier object.")
NORMAL ("The resulting FormantTier contains a point for each original frame. The number of formants "
	"in the result is limited to 10. The intensity information is lost.")
MAN_END

MAN_BEGIN ("Formant: Speckle...", "ppgb", 20030916)
INTRO ("A command to draw the selected @Formant objects to the @@Picture window@.")
ENTRY ("Behaviour")
NORMAL ("Every formant value is drawn as a small circle, filled with the current colour.")
ENTRY ("Arguments")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the time domain of the drawing. If %%To time% is not greater than %%From time%, "
	"the entire formant contour is drawn.")
TAG ("%%Maximum frequency% (Hz)")
DEFINITION ("the height of the %y axis. For speech, 5000 Hz is a usual value.")
TAG ("%%Dynamic range% (dB)")
DEFINITION ("determines the signal intensity (as stored in each formant frame) below which "
	"no formants will be drawn. If zero, all formants will be drawn. The standard value is 30 dB, "
	"which would mean that formants in frames with intensities less than the maximum intensity minus 30 dB will not be drawn.")
TAG ("%%Garnish")
DEFINITION ("determines whether axes, numbers, and texts (\"Time\", \"Formant frequency\") will be drawn in the margins around the picture. "
	"Turn this button off if you prefer to garnish you picture by yourself with the @Margins menu.")
MAN_END

MAN_BEGIN ("Formant: Draw tracks...", "ppgb", 19980321)
INTRO ("A command to draw the selected @Formant objects to the @@Picture window@.")
ENTRY ("Behaviour")
NORMAL ("Every formant value is drawn as one or two short line segments, connected, if possible, "
	"with a line segment of the corresponding formant values in the adjacent frames.")
ENTRY ("Arguments")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the time domain of the drawing. If %%To time% is not greater than %%From time%, "
	"the entire formant contour is drawn.")
TAG ("%%Maximum frequency% (Hz)")
DEFINITION ("the height of the %y axis. For speech, 5000 Hz is a usual value.")
TAG ("%%Garnish")
DEFINITION ("determines whether axes, numbers, and texts (\"Time\", \"Formant frequency\") will be drawn in the margins around the picture. "
	"Turn this button off if you prefer to garnish you picture by yourself with the @Margins menu.")
ENTRY ("Usage")
NORMAL ("Unlike @@Formant: Speckle...@, this procedure assumes that e.g. the second formant in frame %i "
	"has something to do with the second formant in frame %i+1. To make this assumption more plausible, "
	"use @@Formant: Track...@ first.")
MAN_END

MAN_BEGIN ("Formant: Formula (bandwidths)...", "ppgb", 19980323)
INTRO ("A command to modify each selected @Formant object with a specified formula.")
NORMAL ("For what you can do with formulas, see @@Matrix: Formula...@. "
	"The %%i%th row contains the values of the %%i%th bandwidth contour.")
NORMAL ("See @@Formant: Formula (frequencies)...@ for more information.")
MAN_END

MAN_BEGIN ("Formant: Formula (frequencies)...", "ppgb", 19981221)
INTRO ("A command to modify each selected @Formant object with a specified formula.")
NORMAL ("For what you can do with formulas, see @@Matrix: Formula...@. "
	"The %%i%th row contains the values of the %%i%th frequency contour.")
NORMAL ("For an example, see @@Source-filter synthesis@.")
MAN_END

MAN_BEGIN ("Formant: Get bandwidth at time...", "ppgb", 19991016)
INTRO ("A @query to the selected @Formant object for the bandwidth of the specified formant at the specified time.")
ENTRY ("Arguments")
TAG ("%%Formant number")
DEFINITION ("the ordinal number of the formant, counting up from 0 Hz. Specify \"2\" for %F__2_ etc.")
TAG ("%%Time% (s)")
DEFINITION ("the time at which to evaluate the bandwidth.")
TAG ("%Units")
DEFINITION ("the units of the result (Hertz or Bark).")
ENTRY ("Return value")
NORMAL ("the estimated bandwidth in Hertz or Bark. "
	"If %Time is not within half a frame width of any frame centre, or "
	"If the specified %%Formant number% is greater than the number of formants in the frame, "
	"the return value is @undefined; "
	"otherwise, the formant is considered to belong to the frame whose centre is nearest to the specified time.")
ENTRY ("Algorithm")
NORMAL ("If possible (i.e. if the adjacent frame has enough formants), "
	"a linear interpolation is performed between the centre of the frame and the centre of the adjacent frame. "
	"With Bark units, the Hertz-to-Bark transformation is performed "
	"on the two frequencies %F \\+_ 1/2 %B (after interpolation), and the result is the difference between these two values")
MAN_END

MAN_BEGIN ("Formant: Get frame from time...", "ppgb", 20030316)
INTRO ("A @query to the selected @Formant object. Writes into the Info window "
	"the frame number belonging to a specified time. The result is presented as a real number.")
ENTRY ("Argument")
TAG ("%%Time")
DEFINITION ("the time for which you want to know the frame number.")
ENTRY ("Example")
NORMAL ("If the Formant object has a frame length of 10 ms, and the first frame is centred around 18 ms, "
	"the frame number associated with a time of 0.1 seconds is 9.2.")
ENTRY ("Scripting")
NORMAL ("You can use this command to put the nearest frame centre into a script variable:")
CODE ("select Formant hallo")
CODE ("frame = Get frame from time... 0.1")
CODE ("nearestFrame = round (frame)")
NORMAL ("In this case, the value will not be written into the Info window. To round down or up, use")
CODE ("leftFrame = floor (frame)")
CODE ("rightFrame = ceiling (frame)")
ENTRY ("Algorithm")
NORMAL ("the result is")
FORMULA ("1 + (%time \\-- %t__1_) / \\De%t")
NORMAL ("where %t__1_ is the time associated with the centre of the first frame (i.e., the %x1 attribute of the Formant), "
	"and \\De%t is the frame length (the %dx attribute of the Formant).")
MAN_END

MAN_BEGIN ("Formant: Get frame length", "ppgb", 20030316)
INTRO ("A @query to the selected @Formant object. Writes into the Info window "
	"the time difference between the centres of the frames (the %dx attribute of the Formant).")
MAN_END

MAN_BEGIN ("Formant: Get maximum...", "ppgb", 19991016)
INTRO ("A @query to ask the selected @Formant object for the maximum value of the specified formant.")
ENTRY ("Return value")
NORMAL ("the maximum, in Hertz or Bark.")
ENTRY ("Arguments")
TAG ("%%Formant number")
DEFINITION ("the ordinal number of the formant, counting up from 0 Hz. Specify \"2\" for %F__2_ etc.")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the selected time domain. Values outside this domain are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the formant contour is considered.")
TAG ("%Units")
DEFINITION ("the units of the result (Hertz or Bark).")
TAG ("%Interpolation")
DEFINITION ("the interpolation method (none or parabolic). See @@vector peak interpolation@.")
MAN_END

MAN_BEGIN ("Formant: Get mean...", "ppgb", 19991016)
INTRO ("A @query to ask the selected @Formant object for the mean value of the specified formant.")
ENTRY ("Return value")
NORMAL ("the mean, in Hertz or Bark.")
ENTRY ("Arguments")
TAG ("%%Formant number")
DEFINITION ("the ordinal number of the formant, counting up from 0 Hz. Specify \"2\" for %F__2_ etc.")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the selected time domain. Values outside this domain are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the formant contour is considered.")
TAG ("%Units")
DEFINITION ("the units of the result (Hertz or Bark).")
ENTRY ("Scripting")
NORMAL ("You can use this command to put the mean into a script variable:")
CODE ("select Formant hallo")
CODE ("mean = Get mean... 2 0 0 Hertz")
NORMAL ("In this case, the value will not be written into the Info window.")
MAN_END

MAN_BEGIN ("Formant: Get minimum...", "ppgb", 19991016)
INTRO ("A @query to ask the selected @Formant object for the minimum value of the specified formant.")
ENTRY ("Return value")
NORMAL ("the minimum, in Hertz or Bark.")
ENTRY ("Arguments")
TAG ("%%Formant number")
DEFINITION ("the ordinal number of the formant, counting up from 0 Hz. Specify \"2\" for %F__2_ etc.")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the selected time domain. Values outside this domain are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the formant contour is considered.")
TAG ("%Units")
DEFINITION ("the units of the result (Hertz or Bark).")
TAG ("%Interpolation")
DEFINITION ("the interpolation method (none or parabolic). See @@vector peak interpolation@.")
MAN_END

MAN_BEGIN ("Formant: Get number of formants", "ppgb", 19991016)
INTRO ("A @query to ask the selected @Formant object for the number of formants in a specified frame.")
ENTRY ("Argument")
TAG ("%%Frame number")
DEFINITION ("the frame number whose formant count is sought.")
ENTRY ("Return value")
NORMAL ("the number of formants.")
MAN_END

MAN_BEGIN ("Formant: Get number of frames", "ppgb", 20030316)
INTRO ("A @query to the selected @Formant object. Writes into the Info window "
	"the total number of frames (the %nx attribute of the Formant).")
MAN_END

MAN_BEGIN ("Formant: Get quantile...", "ppgb", 19991016)
INTRO ("A @query to ask the selected @Formant object for an estimation of the specified quantile of the distribution "
	"that underlies the attested values of the specified formant.")
ENTRY ("Return value")
NORMAL ("the quantile, in Hertz or Bark.")
ENTRY ("Arguments")
TAG ("%%Formant number")
DEFINITION ("the ordinal number of the formant, counting up from 0 Hz. Specify \"2\" for %F__2_ etc.")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the selected time domain. Values outside this domain are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the formant contour is considered.")
TAG ("%Units")
DEFINITION ("the units of the result (Hertz or Bark).")
TAG ("%Quantile")
DEFINITION ("the fraction (between 0 and 1) of the values of the underlying distribution expected to lie below the result. "
	"For instance, if %Quantile is 0.10, the algorithm estimates the formant value below which 10\\%  of all formant values "
	"are expected to lie. To get an estimate of the %median of the underlying distribution, specify a quantile of 0.50.")
ENTRY ("Algorithm")
NORMAL ("First, the available formant values within the selected time domain are collected in an array. "
	"This array is then sorted and the @@quantile algorithm@ is performed. With Bark units, "
	"the Hertz-to-Bark transformation is performed before the quantile algorithm.")
MAN_END

MAN_BEGIN ("Formant: Get standard deviation", "ppgb", 19991016)
INTRO ("A @query to ask the selected @Formant object for the standard deviation of the attested values of the specified formant "
	"within a specified time domain.")
ENTRY ("Return value")
NORMAL ("the standard deviation, in Hertz or Bark.")
ENTRY ("Arguments")
TAG ("%%Formant number")
DEFINITION ("the ordinal number of the formant, counting up from 0 Hz. Specify \"2\" for %F__2_ etc.")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the selected time domain. Values outside this domain are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the formant contour is considered.")
TAG ("%Units")
DEFINITION ("the units of the result (Hertz or Bark).")
MAN_END

MAN_BEGIN ("Formant: Get time from frame...", "ppgb", 20030316)
INTRO ("A @query to the selected @Formant object. Writes into the Info window "
	"the time associated with a specified frame number.")
ENTRY ("Argument")
TAG ("%%Frame number")
DEFINITION ("the frame number whose time is sought.")
ENTRY ("Algorithm")
NORMAL ("the result is")
FORMULA ("%t__1_ + (%frameNumber - 1) \\.c \\De%t")
NORMAL ("where %t__1_ is the time associated with the centre of the first frame (i.e., the %x1 attribute of the Formant), "
	"and \\De%t is the frame length (the %dx attribute of the Formant).")
MAN_END

MAN_BEGIN ("Formant: Get time of maximum...", "ppgb", 19991016)
INTRO ("A @query to ask the selected @Formant object for the time associated with the maximum value "
	"of a specified formant within a specified time domain.")
ENTRY ("Argument")
TAG ("%%Formant number")
DEFINITION ("the ordinal number of the formant, counting up from 0 Hz. Specify \"2\" for %F__2_ etc.")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the selected time domain. Values outside this domain are ignored, except for interpolation. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the formant contour is considered.")
TAG ("%Units")
DEFINITION ("the units of the result (Hertz or Bark).")
TAG ("%Interpolation")
DEFINITION ("the interpolation method (None or Parabolic). See @@vector peak interpolation@.")
ENTRY ("Return value")
NORMAL ("the time expressed in seconds. If no relevant formants are found, the value is @undefined.")
MAN_END

MAN_BEGIN ("Formant: Get time of minimum...", "ppgb", 19991016)
INTRO ("A @query to ask the selected @Formant object for the time associated with the minimum value "
	"of a specified formant within a specified time domain.")
ENTRY ("Argument")
TAG ("%%Formant number")
DEFINITION ("the ordinal number of the formant, counting up from 0 Hz. Specify \"2\" for %F__2_ etc.")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the selected time domain. Values outside this domain are ignored, except for interpolation. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the formant contour is considered.")
TAG ("%Units")
DEFINITION ("the units of the result (Hertz or Bark).")
TAG ("%Interpolation")
DEFINITION ("the interpolation method (None or Parabolic). See @@vector peak interpolation@.")
ENTRY ("Return value")
NORMAL ("the time expressed in seconds. If no relevant formants are found, the value is @undefined.")
MAN_END

MAN_BEGIN ("Formant: Get value at time...", "ppgb", 19991016)
INTRO ("A @query to ask the selected @Formant object for the frequency of the specified formant at the specified time.")
ENTRY ("Arguments")
TAG ("%%Formant number")
DEFINITION ("the ordinal number of the formant, counting up from 0 Hz. Specify \"2\" for %F__2_ etc.")
TAG ("%%Time% (s)")
DEFINITION ("the time at which to evaluate the formant frequency.")
TAG ("%Units)")
DEFINITION ("the units of the result (Hertz or Bark).")
TAG ("%%Interpolation")
DEFINITION ("the interpolation method, see @@vector value interpolation@. "
	"Always Linear.")
ENTRY ("Return value")
NORMAL ("the bandwidth in Hertz or Bark. "
	"If %Time is not within half a frame width of any frame centre, or "
	"if the specified %%Formant number% is greater than the number of formants in the frame, "
	"the value is @undefined; "
	"otherwise, the formant is considered to belong to the frame whose centre is nearest to the specified time.")
ENTRY ("Algorithm")
NORMAL ("If possible (i.e. if the adjacent frame has enough formants), "
	"a linear interpolation is performed between the centre of the frame and the centre of the adjacent frame. "
	"With Bark units, the Hertz-to-Bark transformation is performed before interpolation.")
MAN_END

MAN_BEGIN ("Formant: Track...", "ppgb", 20020308)
INTRO ("A command to extract a specified number of formant tracks from each selected @Formant object. "
	"The tracks represent the cheapest paths through the measured formant values in consecutive frames.")
ENTRY ("How to use")
NORMAL ("In order to be capable of producing three tracks (i.e. F1, F2, and F3), there must be at least "
	"three formant candidates in %every frame of the Formant object. The typical use of "
	"this command, therefore, is to analyse five formants with @@Sound: To Formant (burg)...@ "
	"and then use the tracking command to extract three tracks.")
ENTRY ("When to use, when not")
NORMAL ("This command only makes sense if the whole of the formant contour makes sense. "
	"For speech, formant contours make sense only for vowels and the like. "
	"During some consonants, the Formant object may have fewer than three formant values, "
	"and trying to create three tracks through them will fail. "
	"You will typically use this command for the contours in diphthongs, if at all.")
ENTRY ("Arguments")
NORMAL ("To be able to interpret the arguments, you should know that the aim of the procedure is "
	"to minimize the sum of the %costs associated with the three tracks.")
TAG ("%%Number of tracks")
DEFINITION ("the number of formant tracks that the procedure must find. If this number is 3, "
	"the procedure will try to find tracks for F1, F2, and F3; if the Formant object contains "
	"a frame with less than three formants, the tracking procedure will fail.")
TAG ("%%Reference F1% (Hertz)")
DEFINITION ("the preferred value near which the first track wants to be. "
	"For average (i.e. adult female) speakers, this value will be around "
	"the average F1 for vowels of female speakers, i.e. 550 Hz.")
TAG ("%%Reference F2% (Hertz)")
DEFINITION ("the preferred value near which the second track wants to be. "
	"A good value will be around "
	"the average F2 for vowels of female speakers, i.e. 1650 Hz.")
TAG ("%%Reference F3% (Hertz)")
DEFINITION ("the preferred value near which the third track wants to be. "
	"A good value will be around "
	"the average F3 for vowels of female speakers, i.e. 2750 Hz. "
	"This argument will be ignored if you choose to have fewer than three tracks, "
	"i.e., if you are only interested in F1 and F2.")
TAG ("%%Reference F4% (Hertz)")
DEFINITION ("the preferred value near which the fourth track wants to be. "
	"A good value may be around 3850 Hz, but you will usually not want to "
	"track F4, because traditional formant lore tends to ignore it "
	"(however inappropriate this may be for the vowel [i]), "
	"and because Formant objects often contain not more than three formant values "
	"in some frames. So you will not usually specify a higher %%Number of tracks% than 3, "
	"and in that case, this argument will be ignored.")
TAG ("%%Reference F5% (Hertz)")
DEFINITION ("the preferred value near which the five track wants to be. "
	"In the unlikely case that you want five tracks, "
	"a good value may be around 4950 Hz.")
TAG ("%%Frequency cost% (per kiloHertz)")
DEFINITION ("the local cost of having a formant value in your track that deviates "
	"from the reference value. For instance, if a candidate (i.e. any formant in a frame "
	"of the Formant object) has a formant frequency of 800 Hz, "
	"and the %%Frequency cost% is 1.0/kHz, "
	"the cost of putting this formant in the first track is 0.250, "
	"because the distance to the reference F1 of 550 Hz is 250 Hz. "
	"The cost of putting the formant in the second track would be 0.850 "
	"(= (1.650 kHz - 0.600 kHz) \\.c 1.0/kHz), so we see that the procedure "
	"locally favours the inclusion of the 800 Hz candidate into the F1 track. "
	"But the next two cost factors may override this local preference.")
TAG ("%%Bandwidth cost%")
DEFINITION ("the local cost of having a bandwidth, relative to the formant frequency. "
	"For instance, if a candidate has a formant frequency of 400 Hz and "
	"a bandwidth of 80 Hz, and the %%Bandwidth cost% is 1.0, "
	"the cost of having this formant in any track is (80/400) \\.c 1.0 = 0.200. "
	"So we see that the procedure locally favours the inclusion of candidates "
	"with low relative bandwidths.")
TAG ("%%Transition cost% (per octave)")
DEFINITION ("the cost of having two different consecutive formant values in a track. "
	"For instance, if a proposed track through the candidates has two consecutive formant "
	"values of 300 Hz and 424 Hz, and the %%Transition cost% is 1.0/octave, "
	"the cost of having this large frequency jump is (0.5 octave) \\.c (1.0/octave) = 0.500.")
ENTRY ("Algorithm")
NORMAL ("This command uses a Viterbi algorithm with multiple planes. For instance, if the selected Formant object "
	"contains up to five formants per frame, and you request three tracks, the Viterbi algorithm will have to choose "
	"between ten candidates (the number of combinations of three out of five) for each frame.")
NORMAL ("The formula for the cost of e.g. track 3, with proposed values %F__2%i_ (%i = 1...%N, "
	"where %N is the number of frames) is:")
FORMULA ("\\su__%i=1..%N_ %frequencyCost\\.c\\|f%F__3%i_ \\-- %referenceF3\\|f/1000 +")
FORMULA ("+ \\su__%i=1..%N_ %bandWidthCost\\.c%B__3%i_/%F__3%i_ +")
FORMULA ("+ \\su__%i=1..%N-1_ %transitionCost\\.c\\|flog__2_(%F__3%i_/%F__3,%i+1_)\\|f")
NORMAL ("Analogous formulas compute the cost of track 1 and track 2. "
	"The procedure will assign those candidates to the three tracks that minimize "
	"the sum of three track costs.")
MAN_END

MAN_BEGIN ("FormantTier", "ppgb", 20030316)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}.")
NORMAL ("A FormantTier object represents spectral structure as a function of time: a %%formant contour%. "
	"Unlike the evenly sampled @Formant object, it consists of a number of formant %points (or %targets), sorted by time. "
	"Each point contains contains several formant/bandwidth pairs.")
NORMAL ("For examples, see @@Source-filter synthesis@.")
ENTRY ("FormantTier commands")
NORMAL ("Creation:")
LIST_ITEM ("From scratch:")
LIST_ITEM ("\\bu @@Create FormantTier...")
LIST_ITEM ("\\bu @@FormantTier: Add point...")
LIST_ITEM ("Copy from another object:")
LIST_ITEM ("\\bu @@Formant: Down to FormantTier@: trivial copying of frames to points.")
NORMAL ("Conversion:")
LIST_ITEM ("\\bu @@FormantTier: Down to PointProcess@: copy times.")
NORMAL ("Synthesis:")
LIST_ITEM ("\\bu @@Sound & FormantTier: Filter@: see @@Source-filter synthesis@.")
NORMAL ("Queries:")
LIST_ITEM ("\\bu @@Get low index from time...")
LIST_ITEM ("\\bu @@Get high index from time...")
LIST_ITEM ("\\bu @@Get nearest index from time...")
NORMAL ("Modification:")
LIST_ITEM ("\\bu @@Remove point...")
LIST_ITEM ("\\bu @@Remove point near...")
LIST_ITEM ("\\bu @@Remove points between...")
LIST_ITEM ("\\bu @@FormantTier: Add point...")
ENTRY ("FormantTier attributes")
NORMAL ("With @Inspect, you will see the following attribute:")
TAG ("%points")
DEFINITION ("when you open this, you see the %size (the number of points) and a series of points (%item [%i], %i = 1...%n).")
ENTRY ("Attributes of a formant point")
NORMAL ("Each point contains the following attributes:")
TAG ("%time")
DEFINITION ("the time associated with this formant target, in seconds. Also used to sort the targets.")
TAG ("%numberOfFormants")
DEFINITION ("the number of formant/bandwidth pairs (never more than 10).")
TAG ("%formant [0..%numberOfFormants-1]")
DEFINITION ("the formant frequencies in Hertz. ##Caution:# the frequency of the %%i%th formant is in %formant [%i-1]!")
TAG ("%bandwidth [0..%numberOfFormants-1]")
DEFINITION ("the formant bandwidths in Hertz. ##Caution:# the bandwidth of the %%i%th formant is in %bandwidth [%i-1]!")
MAN_END

MAN_BEGIN ("FormantTier: Add point...", "ppgb", 19981221)
INTRO ("A command to add a point to each selected @FormantTier.")
NORMAL ("For examples, see @@Source-filter synthesis@.")
ENTRY ("Arguments")
TAG ("%Time (s)")
DEFINITION ("the time at which a point is to be added.")
TAG ("%%Frequencies and bandwidths (Hz)")
DEFINITION ("the frequency and bandwidth values of the requested new point. To get three formants at "
	"500, 1500, and 2500 Hz with bandwidths of 50, 100, and 150 Hz, respectively, "
	"you specify \"500 50 1500 100 2500 150\".")
ENTRY ("Behaviour")
NORMAL ("The tier is modified so that it contains the new point. "
	"If a point at the specified time was already present in the tier, nothing happens.")
MAN_END

MAN_BEGIN ("FormantTier: Down to PointProcess", "ppgb", 20010410)
INTRO ("A command to degrade every selected @FormantTier to a @PointProcess.")
ENTRY ("Behaviour")
NORMAL ("The times of all the formant points are trivially copied, and so is the time domain. "
	"The formant information is lost.")
MAN_END

MAN_BEGIN ("Formula...", "ppgb", 19980319)
NORMAL ("See @@Matrix: Formula...@")
MAN_END

MAN_BEGIN ("Frequency selection", "ppgb", 20010402)
INTRO ("The way to select a frequency domain in the @SpectrumEditor. "
	"This works completely analogously to the @@time selection@ in other editors.")
MAN_END

MAN_BEGIN ("Get area...", "ppgb", 20030216)
INTRO ("A @query to the selected tier object (@PitchTier, @IntensityTier, @DurationTier).")
ENTRY ("Return value")
NORMAL ("the area under the curve.")
ENTRY ("Attributes")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the selected time domain. Values outside this domain are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the tier is considered.")
ENTRY ("Algorithm")
NORMAL ("The curve consists of a sequence of line segments. The contribution of the line segment from "
	"(%t__1_, %f__1_) to (%t__2_, %f__2_) to the area is")
FORMULA ("1/2 (%f__1_ + %f__2_) (%t__2_ \\-- %t__1_)")
MAN_END

MAN_BEGIN ("Get duration", "ppgb", 20030216)
INTRO ("A @query to ask the selected time-based object "
	"(@Formant, @Harmonicity, @Intensity, @Pitch, @Sound) "
	"for its duration.")
NORMAL ("the duration, expressed in seconds, is written to the Info window (or into a variable if you are in a script).")
MAN_END

MAN_BEGIN ("Get finishing time", "ppgb", 20030216)
INTRO ("A @query to ask the selected time-based object "
	"(@Formant, @Harmonicity, @Intensity, @Pitch, @Sound) "
	"for its finishing time (%xmax attribute).")
NORMAL ("the finishing time, expressed in seconds, is written to the Info window (or into a variable if you are in a script).")
MAN_END

MAN_BEGIN ("Get starting time", "ppgb", 20030216)
INTRO ("A @query to ask the selected time-based object "
	"(@Formant, @Harmonicity, @Intensity, @Pitch, @Sound) "
	"for its starting time (%xmin attribute).")
NORMAL ("the starting time, expressed in seconds, is written to the Info window (or into a variable if you are in a script).")
MAN_END

MAN_BEGIN ("Harmonicity", "ppgb", 20030610)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}.")
NORMAL ("A Harmonicity object represents the degree of acoustic periodicity, "
	"also called Harmonics-to-Noise Ratio (HNR). "
	"Harmonicity is expressed in dB: "
	"if 99\\%  of the energy of the signal is in the periodic part, and 1\\%  is noise, "
	"the HNR is 10*log10(99/1) = 20 dB. "
	"A HNR of 0 dB means that there is equal energy in the harmonics and in the noise.")
NORMAL ("Harmonicity can be used as a measure for:")
LIST_ITEM ("\\bu The signal-to-noise ratio of anything that generates a periodic signal.")
LIST_ITEM ("\\bu Voice quality. For instance, a healthy speaker can produce a sustained [a] or [i] "
	"with a harmonicity of around 20 dB, and an [u] at around 40 dB; "
	"the difference comes from the high frequencies in [a] and [i], versus low frequencies in [u], "
	"resulting in a much higher sensitivity of HNR to jitter in [a] and [i] than in [u]. "
	"Hoarse speakers will have an [a] with a harmonicity much lower than 20 dB. "
	"We know of a pathological case where a speaker had an HNR of 40 dB for [i], "
	"because his voice let down above 2000 Hz.")
ENTRY ("Harmonicity commands")
NORMAL ("Creation:")
LIST_ITEM ("\\bu @@Sound: To Harmonicity (cc)...@: cross-correlation method (preferred).")
LIST_ITEM ("\\bu @@Sound: To Harmonicity (ac)...@: autocorrelation method.")
MAN_END

MAN_BEGIN ("Harmonicity: Formula...", "ppgb", 20021206)
INTRO ("A command for changing the data in all selected @Harmonicity objects.")
NORMAL ("See the @Formulas tutorial for examples and explanations.")
MAN_END

MAN_BEGIN ("Harmonicity: Get frame from time...", "ppgb", 20030316)
INTRO ("A @query to the selected @Harmonicity object. Writes into the Info window "
	"the frame number belonging to a specified time. The result is presented as a real number.")
ENTRY ("Argument")
TAG ("%%Time")
DEFINITION ("the time for which you want to know the frame number.")
ENTRY ("Example")
NORMAL ("If the Harmonicity object has a frame length of 10 ms, and the first frame is centred around 18 ms, "
	"the frame number associated with a time of 0.1 seconds is 9.2.")
ENTRY ("Scripting")
NORMAL ("You can use this command to put the nearest frame centre into a script variable:")
CODE ("select Harmonicity hallo")
CODE ("frame = Get frame from time... 0.1")
CODE ("nearestFrame = round (frame)")
NORMAL ("In this case, the value will not be written into the Info window. To round down or up, use")
CODE ("leftFrame = floor (frame)")
CODE ("rightFrame = ceiling (frame)")
ENTRY ("Algorithm")
NORMAL ("the result is")
FORMULA ("1 + (%time \\-- %t__1_) / \\De%t")
NORMAL ("where %t__1_ is the time associated with the centre of the first frame (i.e., the %x1 attribute of the Harmonicity), "
	"and \\De%t is the frame length (the %dx attribute of the Harmonicity).")
MAN_END

MAN_BEGIN ("Harmonicity: Get frame length", "ppgb", 20030316)
INTRO ("A @query to the selected @Harmonicity object. Writes into the Info window "
	"the time difference between the centres of the frames (the %dx attribute of the Harmonicity).")
MAN_END

MAN_BEGIN ("Harmonicity: Get maximum...", "ppgb", 20030916)
INTRO ("A @query to the selected @Harmonicity object.")
ENTRY ("Return value")
NORMAL ("the maximum value, expressed in dB.")
ENTRY ("Arguments")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the selected time domain. Values outside this domain are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the Harmonicity object is considered.")
TAG ("%%Interpolation")
DEFINITION ("the interpolation method (None, Parabolic, Cubic, Sinc) of the @@vector peak interpolation@. "
	"The standard is Parabolic because of the usual nonlinearity (logarithm) in the computation of harmonicity; "
	"sinc interpolation would be too stiff and may give unexpected results.")
MAN_END

MAN_BEGIN ("Harmonicity: Get mean...", "ppgb", 19991016)
INTRO ("A @query to the selected @Harmonicity object.")
ENTRY ("Return value")
NORMAL ("the mean value, expressed in dB.")
ENTRY ("Arguments")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the selected time domain. Values outside this domain are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the Harmonicity is considered.")
ENTRY ("Algorithm")
NORMAL ("The mean harmonicity between the times %t__1_ and %t__2_ is defined as")
FORMULA ("1/(%t__2_ - %t__1_)  \\in__%%t%1_^^%%t%2^ %dt %x(%t)")
NORMAL ("where %x(%t) is the harmonicity as a function of time. "
	"For our discrete Harmonicity object, this mean is approximated by")
FORMULA ("1/%n \\su__%i=%m..%m+%n-1_ %x__%i_")
NORMAL ("where %n is the number of frame centres between %t__1_ and %t__2_. "
	"Frames in which the value is undefined (i.e. in silent intervals) "
	"are ignored. If all the frames are silent, the returned value is @undefined.")
MAN_END

MAN_BEGIN ("Harmonicity: Get minimum...", "ppgb", 20030916)
INTRO ("A @query to the selected @Harmonicity object.")
ENTRY ("Return value")
NORMAL ("the minimum value, expressed in dB.")
ENTRY ("Arguments")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the selected time domain. Values outside this domain are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the Harmonicity object is considered.")
TAG ("%%Interpolation")
DEFINITION ("the interpolation method (None, Parabolic, Cubic, Sinc) of the @@vector peak interpolation@. "
	"The standard is Parabolic because of the usual nonlinearity (logarithm) in the computation of harmonicity; "
	"sinc interpolation would be too stiff and may give unexpected results.")
MAN_END

MAN_BEGIN ("Harmonicity: Get number of frames", "ppgb", 20030316)
INTRO ("A @query to the selected @Harmonicity object. Writes into the Info window "
	"the total number of frames (the %nx attribute of the Harmonicity).")
MAN_END

MAN_BEGIN ("Harmonicity: Get standard deviation...", "ppgb", 19991016)
INTRO ("A @query to the selected @Harmonicity object.")
ENTRY ("Return value")
NORMAL ("the standard deviation, expressed in dB.")
ENTRY ("Arguments")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the selected time domain. Values outside this domain are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the Harmonicity is considered.")
ENTRY ("Algorithm")
NORMAL ("The standard deviation between the times %t__1_ and %t__2_ is defined as")
FORMULA ("1/(%t__2_ - %t__1_)  \\in__%%t%1_^^%%t%2^ %dt (%x(%t) - %\\mu)^2")
NORMAL ("where %x(%t) is the harmonicity as a function of time, and %\\mu its mean. "
	"For our discrete Harmonicity object, the standard deviation is approximated by")
FORMULA ("1/(%n-1) \\su__%i=%m..%m+%n-1_ (%x__%i_ - %\\mu)^2")
NORMAL ("where %n is the number of frame centres between %t__1_ and %t__2_. Note the \"minus 1\".")
MAN_END

MAN_BEGIN ("Harmonicity: Get time from frame...", "ppgb", 20030316)
INTRO ("A @query to the selected @Harmonicity object. Writes into the Info window "
	"the time associated with a specified frame number.")
ENTRY ("Argument")
TAG ("%%Frame number")
DEFINITION ("the frame number whose time is sought.")
ENTRY ("Algorithm")
NORMAL ("the result is")
FORMULA ("%t__1_ + (%frameNumber - 1) \\.c \\De%t")
NORMAL ("where %t__1_ is the time associated with the centre of the first frame (i.e., the %x1 attribute of the Harmonicity), "
	"and \\De%t is the frame length (the %dx attribute of the Harmonicity).")
MAN_END

MAN_BEGIN ("Harmonicity: Get time of maximum...", "ppgb", 20030916)
INTRO ("A @query to the selected @Harmonicity object for the time associated with its maximum value.")
ENTRY ("Return value")
NORMAL ("the time (in seconds) associated with the maximum HNR value.")
ENTRY ("Arguments")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the selected time domain. Values outside this domain are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the Harmonicity object is considered.")
TAG ("%%Interpolation")
DEFINITION ("the interpolation method (None, Parabolic, Cubic, Sinc) of the @@vector peak interpolation@. "
	"The standard is Parabolic because of the usual nonlinearity (logarithm) in the computation of harmonicity; "
	"sinc interpolation would be too stiff and may give unexpected results.")
MAN_END

MAN_BEGIN ("Harmonicity: Get time of minimum...", "ppgb", 20030916)
INTRO ("A @query to the selected @Harmonicity object.")
ENTRY ("Return value")
NORMAL ("the time (in seconds) associated with the minimum HNR value.")
ENTRY ("Arguments")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the selected time domain. Values outside this domain are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the Harmonicity object is considered.")
TAG ("%%Interpolation")
DEFINITION ("the interpolation method (None, Parabolic, Cubic, Sinc) of the @@vector peak interpolation@. "
	"The standard is Parabolic because of the usual nonlinearity (logarithm) in the computation of harmonicity; "
	"sinc interpolation would be too stiff and may give unexpected results.")
MAN_END

MAN_BEGIN ("Harmonicity: Get value at time...", "ppgb", 20030916)
INTRO ("A @query to the selected @Harmonicity object to .")
ENTRY ("Arguments")
TAG ("%Time (s)")
DEFINITION ("the time at which the value is to be evaluated.")
TAG ("%%Interpolation")
DEFINITION ("the interpolation method, see @@vector value interpolation@. "
	"The standard is Cubic because of the usual nonlinearity (logarithm) in the computation of harmonicity; "
	"sinc interpolation would be too stiff and may give unexpected results.")
ENTRY ("Return value")
NORMAL ("an estimate (in dB) of the value at a specified time. "
	"If %time is outside the samples of the Harmonicity, the result is 0.")
MAN_END

MAN_BEGIN ("Harmonicity: Get value in frame...", "ppgb", 19991016)
INTRO ("A @query to ask the selected @Harmonicity object.")
ENTRY ("Argument")
TAG ("%%Frame number")
DEFINITION ("the frame whose value is to be looked up.")
ENTRY ("Return value")
NORMAL ("the value in a specified frame, expressed in dB. "
	"If the index is less than 1 or greater than the number of frames, the result is 0; "
	"otherwise, it is %z [1] [%%frame number%].")
MAN_END

MAN_BEGIN ("Intensity", "ppgb", 20030316)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}.")
NORMAL ("An Intensity object represents an intensity contour at linearly spaced time points "
	"%t__%i_ = %t__1_ + (%i \\-- 1) %dt, with values in dB SPL, i.e. dB relative to 2\\.c10^^-5^ Pascal, "
	"which is the normative auditory threshold for a 1000-Hz sine wave.")
MAN_END

MAN_BEGIN ("Intensity: Get frame from time...", "ppgb", 20030316)
INTRO ("A @query to the selected @Intensity object. Writes into the Info window "
	"the frame number belonging to a specified time. The result is presented as a real number.")
ENTRY ("Argument")
TAG ("%%Time")
DEFINITION ("the time for which you want to know the frame number.")
ENTRY ("Example")
NORMAL ("If the Intensity object has a frame length of 10 ms, and the first frame is centred around 18 ms, "
	"the frame number associated with a time of 0.1 seconds is 9.2.")
ENTRY ("Scripting")
NORMAL ("You can use this command to put the nearest frame centre into a script variable:")
CODE ("select Intensity hallo")
CODE ("frame = Get frame from time... 0.1")
CODE ("nearestFrame = round (frame)")
NORMAL ("In this case, the value will not be written into the Info window. To round down or up, use")
CODE ("leftFrame = floor (frame)")
CODE ("rightFrame = ceiling (frame)")
ENTRY ("Algorithm")
NORMAL ("the result is")
FORMULA ("1 + (%time \\-- %t__1_) / \\De%t")
NORMAL ("where %t__1_ is the time associated with the centre of the first frame (i.e., the %x1 attribute of the Intensity), "
	"and \\De%t is the frame length (the %dx attribute of the Intensity).")
MAN_END

MAN_BEGIN ("Intensity: Get frame length", "ppgb", 20030316)
INTRO ("A @query to the selected @Intensity object. Writes into the Info window "
	"the time difference between the centres of the frames (the %dx attribute of the Intensity).")
MAN_END

MAN_BEGIN ("Intensity: Get maximum...", "ppgb", 20030916)
INTRO ("A @query to the selected @Intensity object.")
ENTRY ("Return value")
NORMAL ("the maximum value within the specified time domain, expressed in dB.")
ENTRY ("Arguments")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the selected time domain. Values outside this domain are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the Intensity object is considered.")
TAG ("%%Interpolation")
DEFINITION ("the interpolation method (None, Parabolic, Cubic, Sinc) of the @@vector peak interpolation@. "
	"The standard is Parabolic because of the usual nonlinearity (logarithm) in the computation of intensity; "
	"sinc interpolation would be too stiff and may give unexpected results.")
MAN_END

MAN_BEGIN ("Intensity: Get mean...", "ppgb", 19991016)
INTRO ("A @query to the selected @Intensity object.")
ENTRY ("Return value")
NORMAL ("the mean (in dB) of the intensity values of the frames within a specified time domain.")
ENTRY ("Arguments")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the selected time domain. Values outside this domain are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the Intensity is considered.")
ENTRY ("Algorithm")
NORMAL ("The mean intensity between the times %t__1_ and %t__2_ is defined as")
FORMULA ("1/(%t__2_ - %t__1_)  \\in__%%t%1_^^%%t%2^ %dt %x(%t)")
NORMAL ("where %x(%t) is the intensity as a function of time, in dB. "
	"For our discrete Intensity object, this mean is approximated by")
FORMULA ("1/%n \\su__%i=%m..%m+%n-1_ %x__%i_")
NORMAL ("where %n is the number of frame centres between %t__1_ and %t__2_.")
MAN_END

MAN_BEGIN ("Intensity: Get minimum...", "ppgb", 20030916)
INTRO ("A @query to the selected @Intensity object.")
ENTRY ("Return value")
NORMAL ("the minimum value witihin a specified time domain, expressed in dB.")
ENTRY ("Arguments")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the selected time domain. Values outside this domain are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the Intensity object is considered.")
TAG ("%%Interpolation")
DEFINITION ("the interpolation method (None, Parabolic, Cubic, Sinc) of the @@vector peak interpolation@. "
	"The standard is Parabolic because of the usual nonlinearity (logarithm) in the computation of intensity; "
	"sinc interpolation would be too stiff and may give unexpected results.")
MAN_END

MAN_BEGIN ("Intensity: Get number of frames", "ppgb", 20030316)
INTRO ("A @query to the selected @Intensity object. Writes into the Info window "
	"the total number of frames (the %nx attribute of the Intensity).")
MAN_END

MAN_BEGIN ("Intensity: Get standard deviation...", "ppgb", 19991016)
INTRO ("A @query to the selected @Intensity object.")
ENTRY ("Return value")
NORMAL ("the standard deviation (in dB) of the intensity values of the frames within a specified time domain.")
ENTRY ("Arguments")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the selected time domain. Values outside this domain are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the Intensity is considered.")
ENTRY ("Algorithm")
NORMAL ("The standard deviation between the times %t__1_ and %t__2_ is defined as")
FORMULA ("1/(%t__2_ - %t__1_)  \\in__%%t%1_^^%%t%2^ %dt (%x(%t) - %\\mu)^2")
NORMAL ("where %x(%t) is the intensity (in dB) as a function of time, and %\\mu its mean. "
	"For our discrete Intensity object, the standard deviation is approximated by")
FORMULA ("1/(%n-1) \\su__%i=%m..%m+%n-1_ (%x__%i_ - %\\mu)^2")
NORMAL ("where %n is the number of frame centres between %t__1_ and %t__2_. Note the \"minus 1\".")
MAN_END

MAN_BEGIN ("Intensity: Get time from frame...", "ppgb", 20030316)
INTRO ("A @query to the selected @Intensity object. Writes into the Info window "
	"the time associated with a specified frame number.")
ENTRY ("Argument")
TAG ("%%Frame number")
DEFINITION ("the frame number whose time is sought.")
ENTRY ("Algorithm")
NORMAL ("the result is")
FORMULA ("%t__1_ + (%frameNumber - 1) \\.c \\De%t")
NORMAL ("where %t__1_ is the time associated with the centre of the first frame (i.e., the %x1 attribute of the Intensity), "
	"and \\De%t is the frame length (the %dx attribute of the Intensity).")
MAN_END

MAN_BEGIN ("Intensity: Get time of maximum...", "ppgb", 20030916)
INTRO ("A @query to the selected @Intensity object.")
ENTRY ("Return value")
NORMAL ("the time (in seconds) associated with the maximum intensity within a specified time domain.")
ENTRY ("Arguments")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the selected time domain. Values outside this domain are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the Intensity object is considered.")
TAG ("%%Interpolation")
DEFINITION ("the interpolation method (None, Parabolic, Cubic, Sinc) of the @@vector peak interpolation@. "
	"The standard is Parabolic because of the usual nonlinearity (logarithm) in the computation of intensity; "
	"sinc interpolation would be too stiff and may give unexpected results.")
MAN_END

MAN_BEGIN ("Intensity: Get time of minimum...", "ppgb", 20030916)
INTRO ("A @query to the selected @Intensity object.")
ENTRY ("Return value")
NORMAL ("the time (in seconds) associated with the minimum intensity within a specified time domain.")
ENTRY ("Arguments")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the selected time domain. Values outside this domain are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the Intensity object is considered.")
TAG ("%%Interpolation")
DEFINITION ("the interpolation method (None, Parabolic, Cubic, Sinc) of the @@vector peak interpolation@. "
	"The standard is Parabolic because of the usual nonlinearity (logarithm) in the computation of intensity; "
	"sinc interpolation would be too stiff and may give unexpected results.")
MAN_END

MAN_BEGIN ("Intensity: Get value at time...", "ppgb", 20030916)
INTRO ("A @query to the selected @Intensity object.")
ENTRY ("Return value")
NORMAL ("the intensity (in dB) at a specified time. If %time is outside the frames of the Intensity, the result is 0.")
ENTRY ("Arguments")
TAG ("%Time (s)")
DEFINITION ("the time at which the value is to be evaluated.")
TAG ("%%Interpolation")
DEFINITION ("the interpolation method, see @@vector value interpolation@. "
	"The standard is Cubic because of the usual nonlinearity (logarithm) in the computation of intensity; "
	"sinc interpolation would be too stiff and may give unexpected results.")
MAN_END

MAN_BEGIN ("Intensity: Get value in frame...", "ppgb", 19991016)
INTRO ("A @query to the selected @Intensity object.")
ENTRY ("Argument")
TAG ("%%Frame number")
DEFINITION ("the frame whose value is to be looked up.")
ENTRY ("Return value")
NORMAL ("the intensity value (in dB) in the specified frame. "
	"If the index is less than 1 or greater than the number of frames, the result is 0; "
	"otherwise, it is %z [1] [%%frame number%].")
MAN_END

MAN_BEGIN ("Intensity: To IntensityTier", "ppgb", 19970321)
INTRO ("A command to convert each selected @Intensity object to an @IntensityTier.")
ENTRY ("Behaviour")
NORMAL ("Every sample in the @Intensity object is copied to a point on the @IntensityTier.")
ENTRY ("Postconditions")
DEFINITION ("Equal time domains:")
LIST_ITEM ("\\bu %result. %xmin == %intensity. %xmin")
LIST_ITEM ("\\bu %result. %xmax == %intensity. %xmax")
DEFINITION ("Equal number of points:")
LIST_ITEM ("\\bu %result. %points. %size == %intensity. %nx")
NORMAL ("For all points %i = 1 ... %intensity. %nx:")
DEFINITION ("   Explicit times:")
LIST_ITEM ("   \\bu %result. %points. %item [%i]. %time == %intensity. %x1 + (%i \\-- 1) * %intensity. %dx")
DEFINITION ("   Equal number of points:")
LIST_ITEM ("   \\bu %result. %points. %item [%i]. %value == %intensity. %z [1] [%i]")
MAN_END

MAN_BEGIN ("Intensity & TextTier: To IntensityTier...", "ppgb", 19970321)
INTRO ("A command to copy information from an @Intensity, at times specified by a @TextTier, "
	"to points on an @IntensityTier.")
ENTRY ("Behaviour")
NORMAL ("For all the times of the points in the TextTier, an intensity is computed from the "
	"information in the Intensity object, by linear interpolation.")
MAN_END

MAN_BEGIN ("IntensityTier", "ppgb", 20030316)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}. "
	"An IntensityTier object represents a time-stamped intensity contour, i.e., it contains a series of (%time, %intensity) points. "
	"The intensity values are in dB.")
NORMAL ("For examples, see @@Source-filter synthesis@.")
ENTRY ("IntensityTier commands")
NORMAL ("Creation:")
LIST_ITEM ("From scratch:")
LIST_ITEM ("\\bu @@Create IntensityTier...")
LIST_ITEM ("\\bu @@IntensityTier: Add point...")
LIST_ITEM ("Copy from another object:")
LIST_ITEM ("\\bu @@Intensity: To IntensityTier@: trivial copying of linearly spaced points.")
LIST_ITEM ("\\bu @@Intensity & TextTier: To IntensityTier...@: copying interpolated values at specified points.")
LIST_ITEM ("\\bu @@PointProcess: Up to IntensityTier...@: equal values at specified points.")
NORMAL ("Viewing and editing:")
LIST_ITEM ("\\bu @IntensityTierEditor")
NORMAL ("Conversion:")
LIST_ITEM ("\\bu @@IntensityTier: Down to PointProcess@: copy times.")
NORMAL ("Synthesis (see @@Source-filter synthesis@):")
LIST_ITEM ("\\bu @@Sound & IntensityTier: Multiply@")
NORMAL ("Queries:")
LIST_ITEM ("\\bu @@Get low index from time...")
LIST_ITEM ("\\bu @@Get high index from time...")
LIST_ITEM ("\\bu @@Get nearest index from time...")
NORMAL ("Modification:")
LIST_ITEM ("\\bu @@Remove point...")
LIST_ITEM ("\\bu @@Remove point near...")
LIST_ITEM ("\\bu @@Remove points between...")
LIST_ITEM ("\\bu @@IntensityTier: Add point...@")
MAN_END

MAN_BEGIN ("IntensityTier: Add point...", "ppgb", 20010410)
INTRO ("A command to add a point to each selected @IntensityTier.")
ENTRY ("Arguments")
TAG ("%Time (s)")
DEFINITION ("the time at which a point is to be added.")
TAG ("%Intensity (dB)")
DEFINITION ("the intensity value of the requested new point.")
ENTRY ("Behaviour")
NORMAL ("The tier is modified so that it contains the new point. "
	"If a point at the specified time was already present in the tier, nothing happens.")
MAN_END

MAN_BEGIN ("IntensityTier: Down to PointProcess", "ppgb", 20010410)
INTRO ("A command to degrade every selected @IntensityTier to a @PointProcess.")
ENTRY ("Behaviour")
NORMAL ("The times of all the points are trivially copied, and so is the time domain. The intensity information is lost.")
MAN_END

MAN_BEGIN ("IntensityTierEditor", "ppgb", 20010330)
INTRO ("One of the @editors in the Praat program, for viewing and editing an @IntensityTier object. "
	"To create a IntensityTierEditor window, select an IntensityTier and click Edit.")
MAN_END

MAN_BEGIN ("IntervalTier", "ppgb", 20030316)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}. "
	"An IntervalTier represents a series of contiguous intervals in time. "
	"Each interval contains a a string.")
ENTRY ("Creating a IntervalTier object in Praat")
NORMAL ("An IntervalTier object is normally extracted from a @TextGrid object, "
	"which may contain several tiers.")
TAG ("From scratch:")
LIST_ITEM ("1. Select an object with a time domain, e.g., a Sound or a Pitch.")
LIST_ITEM ("2. Click ##To IntervalTier#.")
NORMAL ("The resulting IntervalTier will have the same time domain "
	"as the original Sound (or Pitch), e.g., if the Sound object starts at 0.0 seconds "
	"and has a duration of 2.1 seconds, "
	"the resulting IntervalTier will also have an %xmin of 0.0 "
	"and an %xmax of 2.1 seconds.")
NORMAL ("The resulting IntervalTier will have one interval in it, extending from %xmin to %xmax.")
ENTRY ("Editing an IntervalTier in Praat")
NORMAL ("You would edit an IntervalTier by converting it to a @TextGrid "
	"and invoking a @TextGridEditor, perhaps with a Sound.")
ENTRY ("Drawing an IntervalTier")
NORMAL ("You can draw an IntervalTier alone or together with a Sound or Pitch object, "
	"after converting it to a TextGrid.")
ENTRY ("Inside an IntervalTier")
NORMAL ("With @Inspect, you will see the following attributes:")
TAG ("%x__%min_")
DEFINITION ("the starting time, in seconds.")
TAG ("%x__%max_")
DEFINITION ("the end of the time domain, in seconds.")
TAG ("%intervals")
DEFINITION ("a sorted collection of text intervals.")
NORMAL ("The attributes of a text interval are:")
TAG ("%x__%min_")
DEFINITION ("the starting time, in seconds.")
TAG ("%x__%max_")
DEFINITION ("the end of the time domain, in seconds.")
TAG ("%text")
DEFINITION ("an ASCII text string.")
NORMAL ("Though %text is a system-independent ASCII text string, "
	"it may, as everywhere in Praat, contain @@Special symbols@ "
	"like Greek letters, mathematical symbols, style information, "
	"and Phonetic symbols, which will be visible when the string is drawn "
	"into the Picture window or viewed in a @TextGridEditor.")
MAN_END

MAN_BEGIN ("IntervalTier(s): To TextGrid", "ppgb", 19970317)
INTRO ("A command to merge all selected @IntervalTier objects into a new @TextGrid object.")
TAG ("You can also merge with @TextTier objects:")
LIST_ITEM ("@@TextTier(s) & IntervalTier(s): To TextGrid@")
MAN_END

MAN_BEGIN ("Keyboard shortcuts", "ppgb", 20030316)
INTRO ("A way to accelerate the control of @Editors in P\\s{RAAT}.")
ENTRY ("Purpose")
NORMAL ("to choose a menu command with the keyboard. All of these commands can also be chosen "
	"from a menu.")
ENTRY ("Command key")
NORMAL ("When mentioning the %%Command key%, this manual refers to the key immediately to the left "
	"of the space bar. It is positioned in such a way that the most common keyboard shortcuts "
	"(Command-X: Cut, Command-C: Copy, Command-V: Paste, Command-Z: Undo, Command-Q: Quit, "
	"Command-W: Close) can be typed easily with one hand.")
NORMAL ("On Macintosh, this key is labelled with an Apple. On SGI, this key is labelled #Alt. ")
ENTRY ("Option key")
NORMAL ("When mentioning the %%Option key%, this manual refers to the key immediately to the left "
	"of the Command key. In Praat, this key is sometimes used together with the Command key "
	"for destructive actions that are the reverse of the actions invoked by using the Command key only. "
	"For instance, if Command-T means \"add a target at the cursor position\", "
	"Option-Command-T may mean \"remove the selected targets\".")
NORMAL ("On Macintosh, this key may be labelled #Option or #Alt. On SGI, this key is labelled #Ctrl. ")
MAN_END

MAN_BEGIN ("Label & Sound: To TextGrid", "ppgb", 19970317)
INTRO ("A command to convert an old-style #Label object, "
	"which you have probably read from an old file, into a new-style @TextGrid object.")
NORMAL ("The Sound is needed to supply the TextGrid with a finite time domain, "
	"which old-style Label objects lacked.")
MAN_END

MAN_BEGIN ("Log files", "ppgb", 20030116)
INTRO ("With some commands in the @Query menu of the @SoundEditor and @TextGridEditor, "
	"you can write combined information about times, pitch values, formants, and intensities "
	"to the @@Info window@ and to a log file.")
NORMAL ("A log file is a text file on disk. It consists of a number of similar lines, "
	"whose format you determine with the log settings in the Query menu.")
NORMAL ("Every time you press F12 (or choose ##Log 1# from the Query menu, "
	"Praat writes a line to log file 1. If you press Shift-F12, Praat writes a line to log file 2.")
NORMAL ("With the ##log settings# dialog, you determine the following:")
TAG ("%%Log 1 to Info window")
DEFINITION ("this determines whether your log line will be written to the Info window or not.")
TAG ("%%Log 1 to log file")
DEFINITION ("this determines whether your log line will be written to the log file or not.")
TAG ("%%Log file 1")
DEFINITION ("the name of the log file. On Windows, this has to be a complete path name, such as "
	"$$C:\\bsWINDOWS\\bsDESKTOP\\bsPitch Log.txt$. "
	"On Unix and MacOS X, it can either be a complete path name, e.g. $$/home/mary/pitch_log$, "
	"or a home-relative name such as $$~/Desktop/Pitch log$.")
TAG ("%%Log 1 format")
DEFINITION ("the format of the line that Praat will write. See below.")
NORMAL ("The same goes for log file 2.")
ENTRY ("Usage")
NORMAL ("The logging facility has been implemented in Praat especially for former users of Kay CSL, "
	"who have been used to doing it for years and like to continue doing it in Praat. "
	"Otherwise, you may prefer to use the @TextGridEditor to mark time points and run "
	"an automatic analysis afterwards.")
NORMAL ("If you do want to use the logging facility, you typically start by deleting any old "
	"log file (by choosing ##Delete log file 1# or ##Delete log file 2#), if you want to re-use "
	"the file name. Otherwise, you can change the log file name (with ##Log settings...#). "
	"After this, you will move the cursor to various time locations and press F12 (or Shift-F12) "
	"each time, so that information about the current time will be written to the log file.")
ENTRY ("Example 1: pitch logging")
NORMAL ("Suppose you want to log the time of the cursor and the pitch value at the cursor. "
	"You could use the following log format:")
CODE ("Time \'time:6\' seconds, pitch \'f0:2\' Hertz")
NORMAL ("If you now click at 3.456789876 seconds, and the pitch happens to be 355.266 Hertz "
	"at that time, the following line will be appended to the log file and/or to the Info window:")
CODE ("Time 3.456790 seconds, pitch 355.27 Hertz.")
NORMAL ("The parts \":6\" and \":2\" denote the number of digits after the decimal point. "
	"If you leave them out, the values will be written with a precision of 17 digits.")
NORMAL ("The words \'time\' and \'f0\' mean exactly the same as the result of the commands "
	"##Get cursor# and ##Get pitch#. Therefore, if instead of setting a cursor line you selected a larger "
	"piece of the sound, \'time\' will give the centre of the selection and \'f0\' will give the mean pitch "
	"in the selection.")
NORMAL ("Beware of the following pitfall: if your pitch units are not Hertz, but semitones, "
	"then \'f0\' will give the result in semitones. A format as in this example will then be misleading.")
ENTRY ("Example 2: formant logging")
NORMAL ("Suppose you want to log the start and finish of the selection, its duration, and the mean values "
	"of the first three formants, all separated by tab stops for easy importation into Microsoft\\re Excel\\tm. "
	"You could use the following log format:")
CODE ("\'t1:4\'\'tab\\$ \'\'t2:4\'\'tab\\$ \'\'f1:0\'\'tab\\$ \'\'f2:0\'\'tab\\$ \'\'f3:0\'")
NORMAL ("You see that \'t1\' and \'t2\' are the start and finish of the selection, respectively, "
	"and that they are written with 4 digits after the decimal point. By using \":0\", the three formant values "
	"are rounded to whole numbers in Hertz. The word \'tab\\$ \' is the tab stop.")
ENTRY ("Loggable values")
NORMAL ("The following values can be logged:")
LIST_ITEM ("\'time\': the time of the cursor, or the centre of the selection.")
LIST_ITEM ("\'t1\': the start of the selection (\"B\").")
LIST_ITEM ("\'t2\': the end of the selection (\"E\").")
LIST_ITEM ("\'dur\': the duration of the selection.")
LIST_ITEM ("\'f0\': the pitch at the cursor time, or the mean pitch in the selection.")
LIST_ITEM ("\'f1\', \'f2\', \'f3\', \'f4\', \'f5\': the first/second/third/fourth/fifth formant at the cursor time, "
	"or the mean first/second/third/fourth/fifth formant in the selection.")
LIST_ITEM ("\'b1\', \'b2\', \'b3\', \'b4\', \'b5\': the bandwidth of the first/second/third/fourth/fifth formant "
	"at the cursor time or at the centre of the selection.")
LIST_ITEM ("\'intensity\': the intensity at the cursor time, or the mean intensity in the selection.")
LIST_ITEM ("\'tab\\$ \': the tab stop.")
ENTRY ("More flexibility in logging")
NORMAL ("You may sometimes require information in your log file that cannot be generated directly "
	"by the loggable values above. Suppose, for instance, that you want to log the values for F1 and F2-F1 "
	"at the points where you click. You could write the following script:")
CODE ("f1 = Get first formant")
CODE ("f2 = Get second formant")
CODE ("f21 = f2 - f1")
CODE ("printline 'f1:0' 'f21:0'")
CODE ("fileappend \"D:\\bsPraat logs\\bsFormant log.txt\" 'f1:0''tab\\$ ''f21:0''newline\\$ '")
NORMAL ("With this script, the information would be appended both to the Info window and to the "
	"file \"Formant log.txt\" on your desktop.")
NORMAL ("You can make this script accessible with Option-F12 (or Command-F12) "
	"by saving the script and specifying the name of the script file in the ##Log script 3# (or #4) field "
	"in the ##Log settings...# dialog.")
NORMAL ("These scripts may take arguments. Suppose, for instance, that you want to specify a vowel symbol "
	"as you press Option-F12. The following script will take care of that:")
CODE ("form Save vowel and formants")
CODE1 ("word Vowel a")
CODE ("endform")
CODE ("f1 = Get first formant")
CODE ("f2 = Get second formant")
CODE ("f21 = f2 - f1")
CODE ("printline 'vowel\\$ ' 'f1:0' 'f21:0'")
CODE ("fileappend \"~/Praat logs/Vowels and formants log\" 'vowel\\$ ''f1:0''tab\\$ ''f21:0''newline\\$ '")
NORMAL ("Beware of the following pitfall: because of the nature of scripts, you should not try to do this "
	"when you have two editor windows with the same name. I cannot predict which of the two windows "
	"will answer the #Get queries...")
MAN_END

MAN_BEGIN ("Ltas", "ppgb", 20030316)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}. "
	"#Ltas is short for Long-Term Average Spectrum.")
NORMAL ("An object of class Ltas represents the power spectrum as a function of frequency, "
	"expressed in dB (in air). ")
ENTRY ("Inside an Ltas object")
NORMAL ("With @Inspect, you will see the following attributes:")
TAG ("%x__%min_")
DEFINITION ("the bottom of the frequency domain, in Hertz. Usually 0.")
TAG ("%x__%max_")
DEFINITION ("the top of the frequency domain, in Hertz.")
TAG ("%n__%x_")
DEFINITION ("the number of frequency bands (\\>_ 1).")
TAG ("%dx")
DEFINITION ("the frequency step, or %%bin width%, in Hertz.")
TAG ("%x__1_")
DEFINITION ("the frequency associated with the first bin, in Hertz. "
	"Usually equals %dx / 2, because the first bin tends to start at 0 Hertz.")
TAG ("%z__1%i_, %i = 1 ... %n__%x_")
DEFINITION ("the power spectrum, expressed in dB. ")
MAN_END

MAN_BEGIN ("Ltas: Get band from frequency...", "ppgb", 19991016)
INTRO ("A @query to the selected @Ltas object.")
ENTRY ("Return value")
NORMAL ("the band number belonging to the specified frequency, expressed as a real number.")
ENTRY ("Example")
NORMAL ("If the Ltas has a band width of 1000 Hz, and the lowest frequency is 0 Hz, "
	"the band number associated with a frequency of 1800 Hz is 2.3.")
ENTRY ("Scripting")
NORMAL ("You can use this command to put the nearest band centre into a script variable:")
CODE ("select Ltas hallo")
CODE ("band = Get band from frequency... 1800")
CODE ("nearestBand = round (band)")
NORMAL ("In this case, the value will not be written into the Info window. To round down or up, use")
CODE ("leftBand = floor (band)")
CODE ("rightBand = ceiling (band)")
MAN_END

MAN_BEGIN ("Ltas: Get band width", "ppgb", 19991016)
INTRO ("A @query to the selected @Ltas object.")
ENTRY ("Return value")
NORMAL ("the with of a band (%dx attribute), expressed in Hertz.")
MAN_END

MAN_BEGIN ("Ltas: Get frequency from band...", "ppgb", 19991016)
INTRO ("A @query to the selected @Ltas object what frequency is .")
ENTRY ("Return value")
NORMAL ("the frequency (in Hz) associated with a specified band number.")
TAG ("%%Band number")
DEFINITION ("the band number whose frequency is sought.")
ENTRY ("Algorithm")
NORMAL ("the result is")
FORMULA ("%f__1_ + (%bandNumber - 1) \\.c \\De%f")
NORMAL ("where %f__1_ is the frequency associated with the centre of the first band (i.e., the %x1 attribute), "
	"and \\De%f is the band width (the %dx attribute of the Ltas object).")
MAN_END

MAN_BEGIN ("Ltas: Get frequency of maximum...", "ppgb", 20030916)
INTRO ("A @query to the selected @Ltas object.")
ENTRY ("Return value")
NORMAL ("the frequency (in Hertz) associated with the maximum energy density.")
ENTRY ("Arguments")
TAG ("%%From frequency% (s), %%To frequency% (s)")
DEFINITION ("the selected frequency domain. Values outside this domain are ignored. "
	"If %%To frequency% is not greater than %%From frequency%, "
	"the entire frequency domain of the Ltas object is considered.")
TAG ("%%Interpolation")
DEFINITION ("the interpolation method (None, Parabolic, Cubic, Sinc) of the @@vector peak interpolation@. "
	"The standard is None because of the usual large binning. "
	"If the Ltas was computed with @@Spectrum: To Ltas (1-to-1)@, "
	"a Parabolic or Cubic interpolation would be more appropriate.")
MAN_END

MAN_BEGIN ("Ltas: Get frequency of minimum...", "ppgb", 20030916)
INTRO ("A @query to the selected @Ltas object.")
ENTRY ("Return value")
NORMAL ("the frequency (in Hertz) associated with the minimum energy density.")
ENTRY ("Arguments")
TAG ("%%From frequency% (s), %%To frequency% (s)")
DEFINITION ("the selected frequency domain. Values outside this domain are ignored. "
	"If %%To frequency% is not greater than %%From frequency%, "
	"the entire frequency domain of the Ltas object is considered.")
TAG ("%%Interpolation")
DEFINITION ("the interpolation method (None, Parabolic, Cubic, Sinc) of the @@vector peak interpolation@. "
	"The standard is None because of the usual large binning. "
	"If the Ltas was computed with @@Spectrum: To Ltas (1-to-1)@, "
	"a Parabolic or Cubic interpolation would be more appropriate.")
MAN_END

MAN_BEGIN ("Ltas: Get frequency range", "ppgb", 19991016)
INTRO ("A @query to the selected @Ltas object.")
ENTRY ("Return value")
NORMAL ("the frequency range in Hertz, i.e. the difference between the minimum and maximum frequency.")
MAN_END

MAN_BEGIN ("Ltas: Get highest frequency", "ppgb", 19991016)
INTRO ("A @query to the selected @Ltas object.")
ENTRY ("Return value")
NORMAL ("the highest frequency (%xmax attribute), expressed in Hertz.")
MAN_END

MAN_BEGIN ("Ltas: Get lowest frequency", "ppgb", 19991016)
INTRO ("A @query to the selected @Ltas object for its lowest frequency.")
ENTRY ("Return value")
NORMAL ("the lowest frequency (%xmin attribute), expressed in Hertz. It is normally 0 Hz.")
MAN_END

MAN_BEGIN ("Ltas: Get maximum...", "ppgb", 20030916)
INTRO ("A @query to the selected @Ltas object.")
ENTRY ("Return value")
NORMAL ("the maximum value (in dB) within a specified frequency range.")
ENTRY ("Arguments")
TAG ("%%From frequency% (s), %%To frequency% (s)")
DEFINITION ("the selected frequency domain. Values outside this domain are ignored. "
	"If %%To frequency% is not greater than %%From frequency%, "
	"the entire frequency domain of the Ltas object is considered.")
TAG ("%%Interpolation")
DEFINITION ("the interpolation method (None, Parabolic, Cubic, Sinc) of the @@vector peak interpolation@. "
	"The standard is None because of the usual large binning. "
	"If the Ltas was computed with @@Spectrum: To Ltas (1-to-1)@, "
	"a Parabolic or Cubic interpolation would be more appropriate.")
MAN_END

MAN_BEGIN ("Ltas: Get mean...", "ppgb", 19991016)
INTRO ("A @query to the selected @Ltas object.")
ENTRY ("Return value")
NORMAL ("the mean value (in dB) within a specified frequency domain.")
ENTRY ("Arguments")
TAG ("%%From frequency% (s), %%To frequency% (s)")
DEFINITION ("the selected frequency domain. Values outside this domain are ignored. "
	"If %%To frequency% is not greater than %%From frequency%, the entire frequency domain of the Ltas is considered.")
ENTRY ("Algorithm")
NORMAL ("The mean value between the frequencies %f__1_ and %f__2_ is defined as")
FORMULA ("1/(%f__2_ - %f__1_)  \\in__%%f%1_^^%%f%2^ %df %x(%f)")
NORMAL ("where %x(%f) is the LTAS as a function of frequency, expressed in dB. "
	"For our discrete Ltas object, this mean is approximated by")
FORMULA ("1/%n \\su__%i=%m..%m+%n-1_ %x__%i_")
NORMAL ("where %n is the number of band centres between %f__1_ and %f__2_.")
MAN_END

MAN_BEGIN ("Ltas: Get minimum...", "ppgb", 20030916)
INTRO ("A @query to the selected @Ltas object.")
ENTRY ("Return value")
NORMAL ("the minimum value (in dB) within a specified frequency range.")
ENTRY ("Arguments")
TAG ("%%From frequency% (s), %%To frequency% (s)")
DEFINITION ("the selected frequency domain. Values outside this domain are ignored. "
	"If %%To frequency% is not greater than %%From frequency%, "
	"the entire frequency domain of the Ltas object is considered.")
TAG ("%%Interpolation")
DEFINITION ("the interpolation method (None, Parabolic, Cubic, Sinc) of the @@vector peak interpolation@. "
	"The standard is None because of the usual large binning. "
	"If the Ltas was computed with @@Spectrum: To Ltas (1-to-1)@, "
	"a Parabolic or Cubic interpolation would be more appropriate.")
MAN_END

MAN_BEGIN ("Ltas: Get number of bands", "ppgb", 19991016)
INTRO ("A @query to the selected @Ltas object.")
ENTRY ("Return value")
NORMAL ("the total number of frequency bands (the %nx attribute).")
MAN_END

MAN_BEGIN ("Ltas: Get standard deviation...", "ppgb", 19991016)
INTRO ("A @query to the selected @Ltas object.")
ENTRY ("Return value")
NORMAL ("the standard deviation (in dB) of the LTAS within a specified frequency domain.")
ENTRY ("Arguments")
TAG ("%%From frequency% (s), %%To frequency% (s)")
DEFINITION ("the frequency window. Values outside this domain are ignored. "
	"If %%To frequency% is not greater than %%From frequency%, the entire frequency domain of the Ltas is considered.")
ENTRY ("Algorithm")
NORMAL ("The standard deviation between the frequencies %f__1_ and %f__2_ is defined as")
FORMULA ("1/(%f__2_ - %f__1_)  \\in__%%f%1_^^%%f%2^ %df (%x(%f) - %\\mu)^2")
NORMAL ("where %x(%f) is the LTAS as a function of frequency, and %\\mu its mean. "
	"For our discrete Ltas object, the standard deviation is approximated by")
FORMULA ("1/(%n-1) \\su__%i=%m..%m+%n-1_ (%x__%i_ - %\\mu)^2")
NORMAL ("where %n is the number of band centres between %f__1_ and %f__2_. Note the \"minus 1\".")
MAN_END

MAN_BEGIN ("Ltas: Get value at frequency...", "ppgb", 20030916)
INTRO ("A @query to the selected @Ltas object.")
ENTRY ("Return value")
NORMAL ("the value (in dB) at a specified frequency. "
	"If %frequency is outside the bands of the Ltas, the result is 0.")
ENTRY ("Arguments")
TAG ("%Frequency (s)")
DEFINITION ("the time at which the value is to be evaluated.")
TAG ("%%Interpolation")
DEFINITION ("the interpolation method, see @@vector value interpolation@. "
	"The standard is None because binning is usually large.")
MAN_END

MAN_BEGIN ("Ltas: Get value in band...", "ppgb", 19991016)
INTRO ("A @query to the selected @Ltas object.")
ENTRY ("Return value")
NORMAL ("the LTAS value (in dB) in a specified band. "
	"If the band number is less than 1 or greater than the number of bands, the result is 0; "
	"otherwise, it is %z [1] [%%band number%].")
ENTRY ("Argument")
TAG ("%%Band number")
DEFINITION ("the band whose value is to be looked up.")
MAN_END

MAN_BEGIN ("Manipulation", "ppgb", 20030316)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}, for changing the pitch and duration contours of a sound.")
ENTRY ("Inside a manipulation object")
NORMAL ("With @Inspect, you will see the following attributes:")
TAG ("%%timeStep%")
DEFINITION ("the time step (of %%frame length%) used in the pitch analysis. A common value is 0.010 seconds.")
TAG ("%%minimumPitch%")
DEFINITION ("the minimum pitch frequency considered in the pitch analysis. A common value is 75 Hertz.")
TAG ("%%maximumPitch%")
DEFINITION ("the maximum pitch frequency considered in the pitch analysis. A common value is 600 Hertz.")
NORMAL ("A Manipulation object also contains the following smaller objects:")
LIST_ITEM ("1. The original @Sound.")
LIST_ITEM ("2. A @PointProcess representing glottal pulses.")
LIST_ITEM ("3. A @PitchTier.")
LIST_ITEM ("4. A @DurationTier.")
ENTRY ("Analysis")
NORMAL ("When a Manipulation object is created from a sound, the following steps are performed:")
LIST_ITEM ("1. A pitch analysis is performed on the original sound, with the method of @@Sound: To Pitch...@. "
	"This uses the time step, minimum pitch, and maximum pitch parameters.")
LIST_ITEM ("2. The information of the resulting pitch contour (frequency and voiced/unvoiced decisions) "
	"is used to posit glottal pulses where the original sound contains much energy. "
	"The method is the same as in @@Sound & Pitch: To PointProcess (cc)@.")
LIST_ITEM ("3. The pitch contour is converted to a pitch tier with many points (targets), "
	"with the method of @@Pitch: To PitchTier@.")
LIST_ITEM ("4. An empty @DurationTier is created.")
ENTRY ("Resynthesis")
TAG ("A Manipulation object can produce Sound input. This Sound can be computed in several ways:")
LIST_ITEM ("\\bu @PSOLA: from original sound + pulses + pitch tier + duration tier;")
LIST_ITEM ("\\bu #LPC: from LPC (from original sound) + pulses + pitch tier;")
LIST_ITEM ("\\bu from the pulses only, as a pulse train or hummed;")
LIST_ITEM ("\\bu from the pitch tier only, as a pulse train or hummed.")
MAN_END

MAN_BEGIN ("Manipulation: Extract duration tier", "ppgb", 20010330)
INTRO ("A command to extract a copy of the duration information in each selected @Manipulation object into a new @DurationTier object.")
MAN_END

MAN_BEGIN ("Manipulation: Extract original sound", "ppgb", 20010330)
INTRO ("A command to copy the original sound in each selected @Manipulation object to a new @Sound object.")
MAN_END

MAN_BEGIN ("Manipulation: Extract pitch tier", "ppgb", 20010330)
INTRO ("A command to extract a copy of the pitch information in each selected @Manipulation object into a new @PitchTier object.")
MAN_END

MAN_BEGIN ("Manipulation: Extract pulses", "ppgb", 20010330)
INTRO ("A command to extract a copy of the vocal-pulse information in each selected @Manipulation object into a new @PointProcess object.")
MAN_END

MAN_BEGIN ("Manipulation: Play (PSOLA)", "ppgb", 20010330)
INTRO ("A command to play each selected @Manipulation object, resynthesized with the @PSOLA method.")
MAN_END

MAN_BEGIN ("Manipulation: Get resynthesis (PSOLA)", "ppgb", 20010330)
INTRO ("A command to extract the sound from each selected @Manipulation object, resynthesized with the @PSOLA method.")
MAN_END

MAN_BEGIN ("Manipulation: Replace duration tier", "ppgb", 20030216)
INTRO ("You can replace the duration tier that you see in your @Manipulation object "
	"with a separate @DurationTier object, for instance one that you extracted from another Manipulation "
	"or one that you created with @@Create DurationTier...@.")
NORMAL ("To do this, select your Manipulation object together with the @DurationTier object and click ##Replace duration tier#.")
MAN_END

MAN_BEGIN ("Manipulation: Replace pitch tier", "ppgb", 20030216)
INTRO ("You can replace the pitch tier that you see in your @Manipulation object "
	"with a separate @PitchTier object, for instance one that you extracted from another Manipulation "
	"or one that you created with @@Create PitchTier...@.")
NORMAL ("To do this, select your Manipulation object together with the @PitchTier object and click ##Replace pitch tier#.")
MAN_END

MAN_BEGIN ("Manipulation: Replace pulses", "ppgb", 20010330)
INTRO ("A command to replace the vocal-pulse information in the selected @Manipulation object with the selected @PointProcess object.")
MAN_END

MAN_BEGIN ("Manipulation: Replace original sound", "ppgb", 20010330)
INTRO ("A command to replace the original sound in the selected @Manipulation object with the selected @Sound object.")
MAN_END

MAN_BEGIN ("ManipulationEditor", "ppgb", 20030316)
	INTRO ("One of the @Editors in P\\s{RAAT}, for viewing and manipulating a @Manipulation object.")
ENTRY ("Objects")
	NORMAL ("The editor shows:")
	LIST_ITEM ("\\bu The original @Sound.")
	LIST_ITEM ("\\bu The @PointProcess that represents the glottal %pulses. "
		"You can edit it for improving the pitch analysis.")
	LIST_ITEM ("\\bu A pitch contour based on the locations of the pulses, for comparison (drawn as grey dots). "
		"Changes shape if you edit the pulses.")
	LIST_ITEM ("\\bu The @PitchTier that determines the pitch contour of the resynthesized @Sound (drawn as blue circles). "
		"At the creation of the @Manipulation object, it is computed from the original pitch contour. "
		"You can manipulate it by simplifying it (i.e., removing targets), "
		"or by moving parts of it up and down, and back and forth.")
	LIST_ITEM ("\\bu A @DurationTier for manipulating the relative durations of the voiced parts of the sound.")
ENTRY ("Playing")
	NORMAL ("To play (a part of) the %resynthesized sound (by any of the methods shown in the #Synth menu, "
		"like @PSOLA and #LPC), @click on any of the 1 to 8 buttons below and above the drawing area "
		"or use the Play commands from the View menu.")
	NORMAL ("To play the %original sound instead, use ##Shift-click#.")
ENTRY ("Pulses")
	TAG ("To add:")
	DEFINITION ("#click at the desired time location, and choose ##Add pulse at cursor# or type ##Command-p#.")
	TAG ("To remove:")
	DEFINITION ("make a @@time selection@, and choose ##Remove pulse(s)# or type ##Option-Command-p#. "
		"If there is no selection, the pulse nearest to the cursor is removed.")
ENTRY ("Pitch points")
	TAG ("To add one at a specified %%time and frequency%:")
	DEFINITION ("#click at the desired time-frequency location, and choose ##Add pitch point at cursor# or type ##Command-t#.")
	TAG ("To add one at a specified %time only:")
	DEFINITION ("#click at the desired time, and choose ##Add pitch point at time slice#. ManipulationEditor tries to compute the frequency from the "
		"intervals between the pulses, basically by a median-of-three method.")
	TAG ("To remove:")
	DEFINITION ("make a @@time selection@, and choose ##Remove pitch point(s)# or type ##Option-Command-t#. "
		"If there is no selection, the pitch point nearest to the cursor is removed.")
	TAG ("To move %some:")
	DEFINITION ("make a @@time selection@ (the points become red) and ##Shift-drag# the points across the window. "
		"You cannot drag them across adjacent points, or below 50 Hz, or above the maximum frequency. "
		"You can only drag them horizontally if the %%dragging strategy% is ##All# or ##Only horizontal#, "
		"and you can drag them vertically if the dragging strategy is not ##Only horizontal#. "
		"You can change the dragging strategy with ##Set pitch dragging strategy...# from the #Pitch menu.")
	TAG ("To move %one:")
	DEFINITION ("@drag that point across the window. "
		"You can only drag it horizontally if the dragging strategy is not ##Only vertical#, "
		"and you can drag it vertically if the dragging strategy is not ##Only horizontal#.")
ENTRY ("Duration points")
	NORMAL ("Work pretty much the same as pitch points.")
ENTRY ("Stylization")
	NORMAL ("Before editing the Pitch points, you may want to reduce their number by choosing any of the #Stylize "
		"commands from the #Pitch menu.")
MAN_END

MAN_BEGIN ("Matrix", "ppgb", 20030216)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}. "
	"A Matrix object represents a function %z (%x, %y) "
	"on the domain [%x__%min_, %x__%max_] \\xx [%y__%min_, %y__%max_]. "
	"The domain has been sampled in the %x and %y directions "
	"with constant sampling intervals (%dx and %dy) along each direction. "
	"The samples are thus %z [%i__%y_] [%i__%x_], %i__%x_ = 1 ... %n__%x_, %i__%y_ = 1 ... %n__%y_. "
	"The samples represent the function values %z (%x__1_ + (%ix - 1) %dx, %y__1_ + (%iy - 1) %dy).")
ENTRY ("Matrix commands")
NORMAL ("Creation:")
LIST_ITEM ("\\bu @@Create Matrix...")
LIST_ITEM ("\\bu @@Create simple Matrix...")
LIST_ITEM ("\\bu @@Read from file...")
LIST_ITEM ("\\bu @@Read Matrix from raw text file...")
LIST_ITEM ("\\bu ##Read Matrix from LVS AP file...")
NORMAL ("Drawing:")
LIST_ITEM ("\\bu ##Matrix: Draw rows...")
LIST_ITEM ("\\bu ##Matrix: Draw contours...")
LIST_ITEM ("\\bu ##Matrix: Paint contours...")
LIST_ITEM ("\\bu ##Matrix: Paint cells...")
LIST_ITEM ("\\bu ##Matrix: Scatter plot...")
LIST_ITEM ("\\bu @@Matrix: Draw as squares...")
LIST_ITEM ("\\bu ##Matrix: Draw value distribution...")
LIST_ITEM ("\\bu ##Matrix: Paint surface...")
NORMAL ("Modification:")
LIST_ITEM ("\\bu @@Matrix: Formula...")
LIST_ITEM ("\\bu ##Matrix: Scale...")
ENTRY ("Inside a Matrix object")
NORMAL ("With @Inspect, you will see the following attributes.")
TAG ("%xmin, %xmax \\>_ %xmin")
DEFINITION ("%x domain.")
TAG ("%nx \\>_ 1")
DEFINITION ("number of columns.")
TAG ("%dx > 0.0")
DEFINITION ("distance between columns.")
TAG ("%x1")
DEFINITION ("%x value associated with first column.")
TAG ("%ymin, %ymax \\>_ %ymin")
DEFINITION ("%y domain.")
TAG ("%ny \\>_ 1")
DEFINITION ("number of rows.")
TAG ("%dy > 0.0")
DEFINITION ("distance between rows.")
TAG ("%y1")
DEFINITION ("%y value associated with first row.")
TAG ("%z [1..%ny] [1..%nx]")
DEFINITION ("The sample values.")
NORMAL ("After creation of the #Matrix, %xmin, %xmax, %ymin, %ymax, "
	"%nx, %ny, %dx, %dy, %x1, and %y1 "
	"do not usually change. The contents of %z do.")
NORMAL ("Normally, you will want %xmin \\<_ %x1 and %xmax \\>_ %x1 + (%nx - 1) %dx.")
ENTRY ("Example: simple matrix")
NORMAL ("If a simple matrix has %x equal to column number "
	"and %y equal to row number, it has the following attributes:")
LIST_ITEM ("%xmin = 1;   %xmax = %nx;   %dx = 1;  %x1 = 1;")
LIST_ITEM ("%ymin = 1;   %ymax = %ny;   %dy = 1;  %y1 = 1;")
ENTRY ("Example: sampled signal")
NORMAL ("If the matrix represents a sampled signal of 1 second duration "
	"with a sampling frequency of 10 kHz, it has the following attributes:")
LIST_ITEM ("%xmin = 0.0;   %xmax = 1.0;   %nx = 10000 ;   %dx = 1.0\\.c10^^-4^;   %x1 = 0.5\\.c10^^-4^;")
LIST_ITEM ("%ymin = 1;   %ymax = 1;   %ny = 1;   %dy = 1;   %y1 = 1;")
ENTRY ("Example: complex signal")
NORMAL ("If the matrix represents a complex spectrum "
	"derived with an @FFT from the sound of example 2, it has the following attributes:")
LIST_ITEM ("%xmin = 0.0;   %xmax = 5000.0;   %nx = 8193 ;   %dx = 5000.0 / 8192;   %x1 = 0.0;")
LIST_ITEM ("%ny = 2 (real and imaginary part);")
LIST_ITEM ("%ymin = 1 (first row, real part);")
LIST_ITEM ("%ymax = 2 (second row, imaginary part);")
LIST_ITEM ("%dy = 1;   %y1 = 1;  (so that %y is equal to row number)")
MAN_END

MAN_BEGIN ("Matrix: Draw as squares...", "ppgb", 19980319)
INTRO ("A command to draw a @Matrix object into the @@Picture window@.")
ENTRY ("Arguments")
TAG ("%Xmin, %Xmax")
DEFINITION ("the windowing domain in the %x direction. Elements outside will not be drawn. "
	"%Autowindowing: if (%Xmin \\>_ %Xmax), the entire %x domain [%x__%min_, %x__%max_] of the Matrix is used.")
TAG ("%Ymin, %Ymax")
DEFINITION ("the windowing domain in the %y direction. Elements outside will not be drawn. "
	"%Autowindowing: if (%Ymin \\>_ %Ymax), the entire %y domain [%y__%min_, %y__%max_] of the Matrix is used.")
TAG ("%Garnish")
DEFINITION ("determines whether axes are drawn around the picture. "
	"Turn this button off if you prefer to garnish your picture by yourself with the @Margins menu.")
ENTRY ("Behaviour")
NORMAL ("For every element of the Matrix inside the specified windowing domain, "
	"an opaque white or black rectangle is painted (white if the value of the element is positive, "
	"black if it is negative), surrounded by a thin black box. "
	"The %area of the rectangle is proportional to the value of the element.")
ENTRY ("Trick")
NORMAL ("If you prefer the %sides of the rectangle (instead of the area) to be proportional "
	"to the value of the element, you can use the formula \"$$self\\^ 2$\" before drawing (see @@Matrix: Formula...@).") 
MAN_END

MAN_BEGIN ("Matrix: Formula...", "ppgb", 20021206)
INTRO ("A command for changing the data in all selected @Matrix objects.")
NORMAL ("See the @Formulas tutorial for examples and explanations.")
MAN_END

MAN_BEGIN ("Matrix: Paint cells...", "ppgb", 20021204)
INTRO ("A command to draw the contents of a @Matrix to the @@Picture window@.")
NORMAL ("Every cell of the matrix is drawn as a rectangle filled with a grey value between white (if the content "
	"of the cell is small) and black (if the content is large).")
MAN_END

/*
if x > 1 and x < 1.5 then self * 1.3 else self fi



je had gewoon de manual kunnen lezen (Help klikken bij Formula...).

>poging 1:
>  for col:=16000 to 24000 do {self[col] := self[col] * 1.3 }

geen lussen in formules. Er is een automatische lus:
for row := 1 to nrow do for col := 1 to ncol do self := ...

>poging 2:
>  col:=16000; for col:=16000 to 24000 do {self[col] := self[col] * 1.3 }

geen toekenningen. Als je het 1000ste element op 8 wilt zetten, kun je doen

Formula... if col=1000 then 8 else self fi

of sneller:

Set value... 1 1000 8

Wat dus wel werkt, maar ERG traag is:

for col = 16000 to 24000
   value = Get value... 1 col
   Set value... 1 col value*1.3
endfor

>toen ben ik het wilde weg gaan proberen:
>  col=16000; for col:=16000 to 24000 do {self[col] := self[col] * 1.3 }

de puntkomma betekent einde formule. Deze formule zet alles op 0,
behalve element 16000, dat op 1 gezet wordt. De expressie is namelijk booleaans:
"is col gelijk aan 16000"?

Dit staat allemaal in de on-line handleiding, dus je hoeft niet te gokken!
*/

MAN_BEGIN ("Matrix: Set value...", "ppgb", 19980319)
INTRO ("A command to change the value of one cell in each selected @Matrix object.")
ENTRY ("Arguments")
TAG ("%%Row number")
DEFINITION ("the number of the row of the cell whose value you want to change.")
TAG ("%%Column number")
DEFINITION ("the number of the column of the cell whose value you want to change.")
TAG ("%%New value")
DEFINITION ("the value that you want the specified cell to have.")
MAN_END

/*
1. The Hilbert transform.

I wondered whether my use of taking the square was worse than taking
the Hilbert envelope. My formula is

   my_envelope1(t) = x(t) ^ 2

For a sampled signal, this introduces higher frequencies, so I should have
filtered the signal at half the Nyquist frequency to prevent aliasing. I wonder
how the Hilbert envelope behaves in this respect:

   your_envelope1(t) = x(t) ^ 2 + Px(t) ^ 2

I think it has the same problem, since it involves squaring the real and imaginary parts.

Of course, the Hilbert transform is much smoother, but that cannot matter for
frequencies above 100 Hz or so, since we are going to filter at 30 Hz anyway.
Thus, I think these methods are comparable. Do you agree?


2. The non-linearity.

In the second step, I take the logarithm:

   my_envelope2(t) = 10 log10 (my_envelope1(t) + 1e-6)

Of course, the 1e-6 is there to guard against zero values in my_envelope1.
I took the logarithm because it can handle negative values, which will arise
in the filtering process. You take the square root instead:

   your_envelope2(t) = sqrt (your_envelope1(t))


3. Filtering between 3 and 30 Hz.

You use a second-order Butterworth filter in the time domain:

   your_envelope3(t) = your_envelope2(t) * Butterworth(t)

What do you mean by "forward and backward filtering"?
Did you use the second-order filter twice, thus making it fourth-order effectively?

My alternative was to use the two Gaussians:

   my_spectrum2(f) = fft (my_envelope2(t))
   my_spectrum3(f) = my_spectrum2(f) (exp(-(f/35)^2)-exp(-(f/3.5)^2)
   my_envelope3(t) = ifft (my_spectrum3 (f))

This is a filter with several desirable properties: no ringing, phase-preserving,
an area of zero. On the other hand, it is not causal, but I think that that is not
an issue here. Is it?


4. The new band.

In my algorithm, I have to undo the non-linearity:

   my_envelope4(t) = 10 ^ (my_envelope3(t) / 2)

You see that I divide by 2, not 10, thus effectively multiplying the dynamics,
expressed in dB, by a factor of 5. Since I am going to use the new envelope as
a multiplication factor, I will have to limit it to a factor of 10, because the
maximum enhancement is 20 dB. But this limiting factor is band-dependent:

   ceiling(Fmid) = 1 + 9 (1/2 - 1/2 cos (pi Fmid / 13))

where Fmid is expressed in Bark. The limiting is done smoothly:

   my_envelope5(t) = 1 / (1 / my_envelope4(t) + 1 / ceiling)

So this is the final multiplication factor for the band-filtered signal:

   new_band(t) = x(t) my_envelope5(t)

Your multiplication factor is very different. Please tell me whether I am correct.

   your_envelope4(t) = rectify (your_envelope3(t))

This step is needed because you cannot handle negative values. It introduces
higher-frequency components, which will have to be filtered out later.
The new signal will have to carry the new envelope, so the multiplication
factor is taken relative to the envelope of the original signal:

   your_envelope5(t) = your_envelope4(t) / your_envelope2(t)

The components that were introduced by the rectification must be thrown out:

   your_envelope6(t) = your_envelope5(t) * Butterworth?(t)

What were the characteristics of that filter? You did not specify them in your paper.
Well, the next step is normalization to the power of the original band:

   new_band(t) = your_envelope6(t) ||x(t)|| / ||your_envelope5(t)||

At least, that's your formula (12). I suppose that it contains a mistake, and that
the norm in the denominator should refer to the filtered your_envelope6(t) instead?

By the normalization, the fast movements within each band have been strengtened,
and the slow parts have been weakened. Thus, there is dynamic expansion within
each band, whereas my algorithm has this only in the mid frequency range, am I correct?
Could you also explain figure 5 to me? Some of the thick curves show enhanced peaks,
but how about the valleys, are some of them deepened as well?


5. The new signal.

My algorithm simply adds all the bands:

   new_signal(t) = SUM new_band(Fmid,t)

The mid-frequency bands are favoured because they have stronger modulation deepening
than the other bands. In your algorithm, the favouring of the mid frequencies is
implemented in the last step:

   new_signal(t) = SUM new_band(Fmid,t) gain(Fmid)

This would mean, for instance, that if the modulation is not deepened (for instance
if there are no fast movements), the mid-frequency range is still multiplied by a factor
of 10, whereas my algorithm would not change the signal at all in such a case. Is that so?

If so, could any of the learning results have been produced by the general emphasis
in the 1-4 kHz range? Have you any proof that the modulation deepening itself
is the cause of the learning results?

So the differences between the two algorithms are clear now: mine does modulation
deepening selectively in the F2 range, yours does modulation deepening everywhere
plus an independent emphasis in the F2 range. Since both algorithms will lead to
emphasis in the F2 range, that leaves the question of whether a modulation change
is necessary for the other frequency bands. Have you any idea, or was your choice
for this just one of the minor decisions while constructing your algorithm?

To sum up, I think that both algorithms perform what they were intended to do,
namely selectively enhancing fast F2 transitions. If you agree with this, I may
advise Eliane to use my algorithm without change. I would, however, welcome any
suggestions as to oversights in my implementation, or other possible problems
or incorrect choices.
*/

MAN_BEGIN ("Matrix: To TableOfReal", "ppgb", 19991030)
INTRO ("A command to convert every selected @Matrix to a @TableOfReal.")
NORMAL ("This command is available from the Cast submenu. The resulting TableOfReal "
	"has the same number of rows and columns as the original Matrix, "
	"and the same data in the cells. However, it does not yet have any row or column "
	"labels; you can add those with some commands from the TableOfReal Modify submenu.")
MAN_END

MAN_BEGIN ("Modify", "ppgb", 20021204)
INTRO ("The title of a submenu of the @@dynamic menu@ for many object types. "
	"This submenu usually collects all the commands that can change the selected object.")
MAN_END

MAN_BEGIN ("Nyquist frequency", "ppgb", 19970520)
INTRO ("The %%Nyquist frequency% is the bandwidth of a sampled signal, "
	"and is equal to half the sampling frequency of that signal. "
	"If the sampled signal should represent a continuous spectral range starting "
	"at 0 Hz (which is the most common case for speech recordings), "
	"the Nyquist frequency is the highest frequency that the sampled signal "
	"can unambiguously represent.")
ENTRY ("Example")
NORMAL ("If a speech signal is sampled at 22050 Hz, the highest frequency that we can "
	"expect to be present in the sampled signal is 11025 Hz. "
	"This means that to heed this expectation, we should run the continuous signal "
	"through a low-pass filter with a cut-off frequency below 11025 Hz; "
	"otherwise, we would experience the phenomenon of @aliasing.")
NORMAL ("Of course, with a sample rate of 22050 Hz we could also represent a signal "
	"band-limited between, say, 40000 Hz and 51025 Hz, but this seems less useful "
	"in speech research.")
MAN_END

MAN_BEGIN ("PairDistribution", "ppgb", 20030316)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}. A "
	"PairDistribution object represents the relative probabilities with which "
	"the specified pairs of strings occur.")
ENTRY ("Class description")
TAG ("##struct-list# pairs")
DEFINITION ("a list of relative string-pair probabilities. Each element consists of:")
TAG1 ("#string %string1")
DEFINITION1 ("the first string.")
TAG1 ("#string %string2")
DEFINITION1 ("the second string.")
TAG1 ("#real %weight")
DEFINITION1 ("the relative probability associated with the string pair. This value cannot be negative.")
MAN_END

MAN_BEGIN ("PairDistribution: To Stringses...", "ppgb", 20030916)
INTRO ("A command to generate a number of string pairs from the selected @PairDistribution object. "
	"This command will create two aligned @Strings objects of equal size.")
ENTRY ("Arguments")
TAG ("%Number (standard: 1000)")
DEFINITION ("the number of the strings in either resulting Strings object.")
TAG ("%%Name of first Strings% (standard: \"input\")")
DEFINITION ("the name of the resulting Strings object associated with the first string of each pair.")
TAG ("%%Name of second Strings% (standard: \"output\")")
DEFINITION ("the name of the resulting Strings object associated with the second string of each pair.")
ENTRY ("Example")
NORMAL ("Suppose the PairDistribution contains the following:")
CODE ("4 pairs")
CODE ("\"at+ma\"  \"atma\"  100")
CODE ("\"at+ma\"  \"apma\"    0")
CODE ("\"an+pa\"  \"anpa\"   20")
CODE ("\"an+pa\"  \"ampa\"   80")
NORMAL ("The resulting Strings object \"input\" may then contain:")
FORMULA ("at+ma, an+pa, an+pa, at+ma, at+ma, an+pa, an+pa, an+pa, an+pa, at+ma, ...")
NORMAL ("The Strings object \"output\" may then contain:")
FORMULA ("atma,  ampa,  ampa,  atma,  atma,  ampa,  anpa,  ampa,  ampa,  atma, ...")
MAN_END

MAN_BEGIN ("ParamCurve", "ppgb", 20030316)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}.")
NORMAL ("An object of class #ParamCurve represents a sequence of time-stamped points (%x (%%t__i_), %y (%%t__i_)) "
	"in a two-dimensional space.")
MAN_END

MAN_BEGIN ("Pitch", "ppgb", 20030316)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}. For tutorial information, see @@Intro 4. Pitch analysis@.")
NORMAL ("A Pitch object represents periodicity candidates as a function of time. "
	"It does not mind whether this periodicity refers to acoustics, "
	"perception, or vocal-cord vibration. "
	"It is sampled into a number of %frames centred around equally spaced times.")
ENTRY ("Pitch commands")
NORMAL ("Creation:")
LIST_ITEM ("\\bu @@Sound: To Pitch...@: preferred method (autocorrelation).")
LIST_ITEM ("\\bu @@Sound: To Pitch (ac)...@: autocorrelation method (all parameters).")
LIST_ITEM ("\\bu @@Sound: To Pitch (cc)...@: cross-correlation method.")
NORMAL ("Drawing:")
LIST_ITEM ("\\bu @@Pitch: Draw...@")
NORMAL ("Viewing and editing:")
LIST_ITEM ("\\bu @PitchEditor")
NORMAL ("Synthesis:")
LIST_ITEM ("\\bu @@Pitch: To PointProcess@: create points in voiced intervals.")
LIST_ITEM ("\\bu @@Sound & Pitch: To PointProcess (cc)@: near locations of high amplitude.")
LIST_ITEM ("\\bu @@Sound & Pitch: To PointProcess (peaks)...@: near locations of high amplitude.")
NORMAL ("Conversion:")
LIST_ITEM ("\\bu @@Pitch: To PitchTier@: time-stamp voiced intervals.")
LIST_ITEM ("\\bu @@Pitch & TextTier: To PitchTier...@: interpolate values at specified times.")
ENTRY ("Inside a Pitch object")
NORMAL ("With @Inspect, you will see the following attributes:")
TAG ("%x__%min_")
DEFINITION ("starting time, in seconds.")
TAG ("%x__%max_")
DEFINITION ("end time, in seconds.")
TAG ("%n__%x_")
DEFINITION ("the number of frames (\\>_ 1).")
TAG ("%dx")
DEFINITION ("time step = frame length = frame duration, in seconds.")
TAG ("%x__1_")
DEFINITION ("the time associated with the first frame, in seconds. "
	"This will usually be in the range [%xmin, %xmax]. "
	"The time associated with the last frame (i.e., %x__1_ + (%n__%x_ \\-- 1) %dx)) "
	"will also usually be in that range.")
TAG ("%ceiling")
DEFINITION ("a frequency above which a candidate is considered voiceless.")
TAG ("%frame__%i_, %i = 1 ... %n__%x_")
DEFINITION ("the frames (see below).")
ENTRY ("Attributes of a pitch frame")
NORMAL ("Each frame contains the following attributes:")
TAG ("%nCandidates")
DEFINITION ("the number of candidates in this frame (at least one: the `unvoiced' candidate).")
TAG ("%candidate__%j_, %j = 1 ... %nCandidates")
DEFINITION ("the information about each candidate (see below).")
ENTRY ("Attributes of each candidate")
NORMAL ("Each candidate contains the following attributes:")
TAG ("%frequency")
DEFINITION ("the candidate's frequency in Hz (for a voiced candidate), or 0 (for an unvoiced candidate).")
TAG ("%strength")
DEFINITION ("the degree of periodicity of this candidate (between 0 and 1).")
ENTRY ("Interpretation")
NORMAL ("The current pitch contour is determined by the path through all first candidates. "
	"If the first candidate of a certain frame has a frequency of 0, "
	"or a frequency above %ceiling, this frame is considered voiceless.")
MAN_END

MAN_BEGIN ("Pitch: Draw...", "ppgb", 19960910)
INTRO ("A command for drawing the selected @Pitch objects into the @@Picture window@.")
ENTRY ("Arguments")
TAG ("%%From time% (seconds), %%To time% (seconds)")
DEFINITION ("the time domain along the horizontal axis. "
	"If these are both zero, the time domain of the #Pitch itself is taken (autowindowing).")
TAG ("%%Minimum frequency% (Hz), %%Maximum frequency% (Hz)")
DEFINITION ("the frequency range along the vertical axis. "
	"%%MaximumFrequency% must be greater than %%minimumFrequency%.")
ENTRY ("Behaviour")
NORMAL ("In unvoiced frames, nothing will be drawn.")
NORMAL ("In voiced frames, the pitch frequency associated with the frame "
	"is thought to represent the time midpoint of the frame, "
	"but frequencies will be drawn at all time points in the frame, as follows:")
LIST_ITEM ("\\bu If two adjacent frames are both voiced, the frequency of the time points between the midpoints "
	"of the frames is linearly interpolated from both midpoints.")
LIST_ITEM ("\\bu If a voiced frame is adjacent to another voiced frame on one side, "
	"and to a voiceless frame on the other side, "
	"the frequencies in the half-frame on the unvoiced side will be linearly extrapolated "
	"from the midpoints of the two voiced frames involved.")
LIST_ITEM ("\\bu If a voiced frame is adjacent to two unvoiced frames, "
	"a horizontal line segment will be drawn at the frequency of the midpoint.")
MAN_END

/*
F0beg = Get value at time... tbeg Hertz Linear
while F0beg = undefined
   tbeg = tbeg + 0.01
   F0beg = Get value at time... tbeg Hertz Linear
endwhile
*/

MAN_BEGIN ("Pitch: Get frame from time...", "ppgb", 20030316)
INTRO ("A @query to the selected @Pitch object. Writes into the Info window "
	"the frame number belonging to a specified time. The result is presented as a real number.")
ENTRY ("Argument")
TAG ("%%Time")
DEFINITION ("the time for which you want to know the frame number.")
ENTRY ("Example")
NORMAL ("If the Pitch object has a frame length of 10 ms, and the first frame is centred around 18 ms, "
	"the frame number associated with a time of 0.1 seconds is 9.2.")
ENTRY ("Scripting")
NORMAL ("You can use this command to put the nearest frame centre into a script variable:")
CODE ("select Pitch hallo")
CODE ("frame = Get frame from time... 0.1")
CODE ("nearestFrame = round (frame)")
NORMAL ("In this case, the value will not be written into the Info window. To round down or up, use")
CODE ("leftFrame = floor (frame)")
CODE ("rightFrame = ceiling (frame)")
ENTRY ("Algorithm")
NORMAL ("the result is")
FORMULA ("1 + (%time \\-- %t__1_) / \\De%t")
NORMAL ("where %t__1_ is the time associated with the centre of the first frame (i.e., the %x1 attribute of the Pitch), "
	"and \\De%t is the frame length (the %dx attribute of the Pitch).")
MAN_END

MAN_BEGIN ("Pitch: Get frame length", "ppgb", 20030316)
INTRO ("A @query to the selected @Pitch object. Writes into the Info window "
	"the time difference between the centres of the frames (the %dx attribute of the Pitch).")
MAN_END

MAN_BEGIN ("Pitch: Get number of frames", "ppgb", 20030316)
INTRO ("A @query to the selected @Pitch object. Writes into the Info window "
	"the total number of frames (the %nx attribute of the Pitch).")
MAN_END

MAN_BEGIN ("Pitch: Get time from frame...", "ppgb", 20030316)
INTRO ("A @query to the selected @Pitch object. Writes into the Info window "
	"the time associated with a specified frame number.")
ENTRY ("Argument")
TAG ("%%Frame number")
DEFINITION ("the frame number whose time is sought.")
ENTRY ("Algorithm")
NORMAL ("the result is")
FORMULA ("%t__1_ + (%frameNumber - 1) \\.c \\De%t")
NORMAL ("where %t__1_ is the time associated with the centre of the first frame (i.e., the %x1 attribute of the Pitch), "
	"and \\De%t is the frame length (the %dx attribute of the Pitch).")
MAN_END

MAN_BEGIN ("Pitch: Interpolate", "ppgb", 19990811)
INTRO ("A command that converts every selected @Pitch object.")
/*
	myID = idofselected ("Pitch")
	tmin = Get starting time
	tmax = Get finishing time
	numberOfFrames = Get number of frames
	timeStep = Get time step
	t1 = Get time of frame... 1
	ceiling = Get ceiling
	Create Pitch... interpolated tmin tmax numberOfFrames timeStep t1 ceiling 2
	for iframe to numberOfFrames
		select 'myID'
		f = Get frequency... iframe 1
		if f > 0.0 and f < ceiling
			# The frame is voiced? Copy the frequency.
			select Pitch interpolated
			Set frequency... iframe 1 f
		else
			# The frame is unvoiced? Interpolate the frequency.
			fleft = 0.0
			fright = 0.0
			# Find nearest voiced frame to the left.
			left = iframe - 1
			while left >= 1 and fleft = 0.0
				fleft = Get frequency... left 1
				if fleft >= ceiling
					fleft = 0.0
				endif
				left = left - 1
			endwhile
			# Find nearest voiced frame to the right.
			right = iframe + 1
			while right <= numberOfFrames and fright = 0.0
				fright = Get frequency... right 1
				if fright >= ceiling
					fright = 0.0
				endif
				right = right + 1
			endwhile
			if fleft <> 0 and fright <> 0
				select Pitch interpolated
				Set frequency... iframe 1 ((iframe - left) * fright + (right - iframe) * fleft) / (right - left)
			endif
		endif
		select Pitch interpolated
		Set strength... iframe 1 0.9
	endfor
	select Pitch interpolated
*/
MAN_END

MAN_BEGIN ("Pitch: Smooth...", "ppgb", 19990811)
INTRO ("A command that converts every selected @Pitch object.")
MAN_END

MAN_BEGIN ("Pitch: To PitchTier", "ppgb", 19960915)
INTRO ("A command that converts a @Pitch object into a @PitchTier object.")
ENTRY ("Algorithm")
NORMAL ("The #PitchTier object will contain as many points as there were voiced frames in the #Pitch.")
NORMAL ("The %time of each point is the time associated with the centre of the corresponding %frame "
	"of the #Pitch contour. The %frequency of the point is the pitch frequency associated in this frame "
	"with the current path through the candidates.")
MAN_END

MAN_BEGIN ("Pitch: To PointProcess", "ppgb", 19960917)
INTRO ("A command that uses a @Pitch object to generate a @PointProcess.")
ENTRY ("Purpose")
NORMAL ("to interpret an acoustic periodicity contour as the frequency of an underlying point process "
	"(such as the sequence of glottal closures in vocal-fold vibration).")
ENTRY ("Algorithm")
LIST_ITEM ("1. A @PitchTier is created with @@Pitch: To PitchTier@.")
LIST_ITEM ("2. The algorithm of @@PitchTier: To PointProcess@ generates points along the entire time domain "
	"of the PitchTier.")
LIST_ITEM ("3. The PitchTier is removed (it never appeared in the List of Objects).")
LIST_ITEM ("4. The voiced/unvoiced information in the Pitch is used to remove all points "
	"that lie within voiceless frames.")
MAN_END

MAN_BEGIN ("Pitch & TextTier: To PitchTier...", "ppgb", 20030916)
INTRO ("A command that creates a @PitchTier object from one selected @Pitch and one selected @TextTier object.")
ENTRY ("Purpose")
NORMAL ("to return the frequencies in the Pitch contour at the times specified by the TextTier.")
ENTRY ("Argument")
TAG ("%%Check voicing% (standard: on)")
DEFINITION ("determines whether, if the time of a mark is not within a voiced frame, you will get a message like "
	"\"No periodicity at time %xxx.\", and no PitchTier is created. If this button is off, "
	"the resulting pitch frequency will be 0.0 Hz.")
ENTRY ("Normal behaviour")
NORMAL ("For all the times of the marks in the TextTier, a pitch frequency is computed from the "
	"information in the Pitch, by linear interpolation.")
NORMAL ("All the resulting time-frequency pairs are put in a new PitchTier object.")
NORMAL ("The time domain of the resulting PitchTier is a union of the domains of the original Pitch "
	"and TextTier functions.")
MAN_END

MAN_BEGIN ("PitchEditor", "ppgb", 20030316)
INTRO ("One of the @Editors in P\\s{RAAT}, for viewing and modifying a @Pitch object.")
ENTRY ("What the Pitch editor shows")
NORMAL ("In the window of the PitchEditor, you will see the following features:")
LIST_ITEM ("\\bu Digits between 0 and 9 scattered all over the drawing area. Their locations represent "
	"the pitch %#candidates, of which there are several for every time frame. The digits themselves "
	"represent the goodness of a candidate, multiplied by ten. For instance, if you see a \"9\" "
	"at the location (1.23 seconds, 189 Hertz), this means that in the time frame at 1.23 seconds, "
	"there is a pitch candidate with a value of 189 Hertz, and its goodness is 0.9. "
	"The number 0.9 may be the relative height of an autocorrelation peak, a cross-correlation peak, "
	"or a spectral peak, depending on the method by which the Pitch object was computed.")
LIST_ITEM ("\\bu A %#path of red disks. These disks represent the best path through the candidates, "
	"i.e. our best guess at what the pitch contour is. The path will usually have been determined "
	"by the %%path finder%, which was called by the pitch-extraction algorithm, and you can change "
	"the path manually. The path finder takes into account the goodness of each candidate, "
	"the intensity of the sound in the frame, voiced-unvoiced transitions, and frequency jumps. "
	"It also determines whether each frame is voiced or unvoiced.")
LIST_ITEM ("\\bu A %%##voicelessness bar%# at the bottom of the drawing area. If there is no suitable "
	"pitch candidate in a frame, the frame is considered voiceless, which is shown as a blue rectangle "
	"in the voicelessness bar.")
LIST_ITEM ("\\bu A line of digits between 0 and 9 along the top. These represent the relative intensity "
	"of the sound in each frame.")
ENTRY ("Moving the marks")
NORMAL ("To move the cursor hair or the beginning or end of the selection, "
	"use the @@time selection@ mechanism.")
ENTRY ("Changing the path")
NORMAL ("To change the path through the candidates manually, click on the candidates of your choice. "
	"The changes will immediately affect the Pitch object that you are editing. To make a voiced frame "
	"voiceless, click on the voicelessness bar.")
NORMAL ("To change the path automatically, choose `Path finder...' from the `Edit' menu; "
	"this will have the same effect as filling in different values in the @@Sound: To Pitch (ac)...@ dialog, "
	"but is much faster because the candidates do not have to be determined again.")
ENTRY ("Resynthesis")
NORMAL ("To hum any part of the pitch contour, click on one of the buttons "
	"below or above the data area (there can be 1 to 8 of these buttons), or use a Play command from the View menu.")
ENTRY ("Changing the ceiling")
NORMAL ("To change the ceiling, but not the path, choose `Change ceiling...' from the `Edit' menu; "
	"if the new ceiling is lower than the old ceiling, some formerly voiced frames may become unvoiced; "
	"if the new ceiling is higher than the old ceiling, some formerly unvoiced frames may become voiced.")
MAN_END

MAN_BEGIN ("PitchTier", "ppgb", 20030316)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}. "
	"A PitchTier object represents a time-stamped pitch contour, "
	"i.e. it contains a number of (%time, %pitch) points, without voiced/unvoiced information. "
	"For instance, if your PitchTier contains two points, namely 150 Hz at a time of 0.5 seconds and "
	"200 Hz at a time of 1.5 seconds, then this is to be interpreted as a pitch contour that "
	"is constant at 150 Hz for all times before 0.5 seconds, constant at 200 Hz for all times after 1.5 seconds, "
	"and linearly interpolated for all times between 0.5 and 1.5 seconds (i.e. 170 Hz at 0.7 seconds, "
	"210 Hz at 1.1 seconds, and so on).")
ENTRY ("PitchTier commands")
NORMAL ("Creation:")
LIST_ITEM ("From scratch:")
LIST_ITEM ("\\bu @@Create PitchTier...")
LIST_ITEM ("\\bu @@PitchTier: Add point...")
LIST_ITEM ("Copy from another object:")
LIST_ITEM ("\\bu @@Pitch: To PitchTier@: trivial copying of voiced frames.")
LIST_ITEM ("\\bu @@PointProcess: Up to PitchTier...@: single value at specified times.")
LIST_ITEM ("\\bu @@Pitch & TextTier: To PitchTier...@: copying interpolated values at specified points.")
LIST_ITEM ("Synthesize from another object:")
LIST_ITEM ("\\bu @@PointProcess: To PitchTier...@: periodicity analysis.")
LIST_ITEM ("Extract from a @Manipulation object:")
LIST_ITEM ("\\bu @@Manipulation: Extract pitch tier@")
NORMAL ("Viewing and editing:")
LIST_ITEM ("\\bu @PitchTierEditor: with or without a Sound.")
LIST_ITEM ("\\bu @ManipulationEditor")
NORMAL ("Conversion:")
LIST_ITEM ("\\bu @@PitchTier: Down to PointProcess@: copy times.")
NORMAL ("Synthesis:")
LIST_ITEM ("\\bu @@PitchTier: To PointProcess@: area-1 pulse generation (used in @PSOLA).")
LIST_ITEM ("\\bu @@Manipulation: Replace pitch tier@")
NORMAL ("Queries:")
LIST_ITEM ("\\bu @@Get low index from time...")
LIST_ITEM ("\\bu @@Get high index from time...")
LIST_ITEM ("\\bu @@Get nearest index from time...")
NORMAL ("Modification:")
LIST_ITEM ("\\bu @@Remove point...")
LIST_ITEM ("\\bu @@Remove point near...")
LIST_ITEM ("\\bu @@Remove points between...")
LIST_ITEM ("\\bu @@PitchTier: Add point...")

MAN_END

MAN_BEGIN ("PitchTier: Add point...", "ppgb", 20010410)
INTRO ("A command to add a point to each selected @PitchTier.")
ENTRY ("Arguments")
TAG ("%Time (s)")
DEFINITION ("the time at which a point is to be added.")
TAG ("%Pitch (Hz)")
DEFINITION ("the pitch value of the requested new point.")
ENTRY ("Behaviour")
NORMAL ("The tier is modified so that it contains the new point. "
	"If a point at the specified time was already present in the tier, nothing happens.")
MAN_END

MAN_BEGIN ("PitchTier: Down to PointProcess", "ppgb", 20010410)
INTRO ("A command to degrade every selected @PitchTier to a @PointProcess.")
ENTRY ("Behaviour")
NORMAL ("The times of all the pitch points are trivially copied, and so is the time domain. The pitch information is lost.")
MAN_END

MAN_BEGIN ("PitchTier: Get mean (curve)...", "ppgb", 20010821)
INTRO ("A @query to the selected @PitchTier object.")
ENTRY ("Return value")
NORMAL ("the mean of the curve within a specified time window.")
ENTRY ("Attributes")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the time window. Values outside this window are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the tier is considered.")
ENTRY ("Algorithm")
NORMAL ("The curve consists of a sequence of line segments. The contribution of the line segment from "
	"(%t__1_, %f__1_) to (%t__2_, %f__2_) to the area under the curve is")
FORMULA ("1/2 (%f__1_ + %f__2_) (%t__2_ \\-- %t__1_)")
NORMAL ("The mean is the sum of these values divided by %toTime \\-- %fromTime.")
NORMAL ("For a PitchTier that was created from a @Pitch object, this command gives the same result as "
	"##Get mean....# for the original Pitch object (but remember that the median, "
	"as available for Pitch objects, is more robust).")
NORMAL ("To get the mean in the entire curve, i.e. weighted by the durations of the line pieces, "
	"Use @@PitchTier: Get mean (points)...@ instead.")
MAN_END

MAN_BEGIN ("PitchTier: Get mean (points)...", "ppgb", 20010821)
INTRO ("A @query to the selected @PitchTier object.")
ENTRY ("Return value")
NORMAL ("the mean of the points within a specified time window.")
ENTRY ("Attributes")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the time window. Values outside this window are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the tier is considered.")
NORMAL ("To get the mean in the entire curve, i.e. weighted by the durations of the line pieces, "
	"Use @@PitchTier: Get mean (curve)...@ instead.")
MAN_END

MAN_BEGIN ("PitchTier: Get standard deviation (curve)...", "ppgb", 20010821)
INTRO ("A @query to the selected @PitchTier object.")
ENTRY ("Return value")
NORMAL ("the standard deviation in the curve within a specified time window.")
ENTRY ("Attributes")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the selected time domain. Values outside this domain are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the tier is considered.")
ENTRY ("Algorithm")
NORMAL ("The curve consists of a sequence of line segments. The contribution of the line segment from "
	"(%t__1_, %f__1_) to (%t__2_, %f__2_) to the variance-multiplied-by-time is")
FORMULA ("[ 1/4 (%f__1_ + %f__2_)^2 + 1/12 (%f__1_ \\-- %f__2_)^2 ] (%t__2_ \\-- %t__1_)")
NORMAL ("The standard deviation is the square root of: the sum of these values divided by %toTime \\-- %fromTime.")
NORMAL ("To get the standard deviation in the points only, i.e. not weighted by the durations of the line pieces, "
	"Use @@PitchTier: Get standard deviation (points)...@ instead.")
MAN_END

MAN_BEGIN ("PitchTier: Get standard deviation (points)...", "ppgb", 20010821)
INTRO ("A @query to the selected @PitchTier object.")
ENTRY ("Return value")
NORMAL ("the standard deviation in the points within a specified time window.")
ENTRY ("Attributes")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the selected time domain. Values outside this domain are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the tier is considered.")
NORMAL ("For a PitchTier that was created from a @Pitch object, this command gives the same result as "
	"##Get standard deviation....# for the original Pitch object (but remember that variation measures "
	"based on quantiles, as available for Pitch objects, are more robust).")
NORMAL ("To get the standard deviation in the entire curve, i.e. weighted by the durations of the line pieces, "
	"Use @@PitchTier: Get standard deviation (curve)...@ instead.")
MAN_END

MAN_BEGIN ("PitchTier: To PointProcess", "ppgb", 19960915)
INTRO ("A command that uses a @PitchTier object to generate a @PointProcess.")
ENTRY ("Purpose")
NORMAL ("to interpret an acoustic periodicity contour as the frequency of an underlying point process "
	"(such as the sequence of glottal closures in vocal-fold vibration).")
ENTRY ("Algorithm")
NORMAL ("Points are generated along the entire time domain of the #PitchTier, "
	"because there is no voiced/unvoiced information. The area between two adjacent points "
	"under the linearly interpolated pitch contour, is always 1.")
MAN_END

MAN_BEGIN ("PitchTierEditor", "ppgb", 20030316)
INTRO ("One of the @Editors in P\\s{RAAT}, for viewing and manipulating a @PitchTier object, "
	"which is optionally shown together with a @Sound object.")
ENTRY ("Objects")
NORMAL ("The editor shows:")
LIST_ITEM ("\\bu The @Sound, if you selected a Sound object together with the PichTier object "
	"before you clicked #Edit.")
LIST_ITEM ("\\bu The @PitchTier: blue points connected with blue lines.")
ENTRY ("Playing")
NORMAL ("To play (a part of) the %resynthesized sound: "
	"@click on any of the 8 buttons below and above the drawing area, or choose a Play command from the View menu.")
NORMAL ("To play the %original sound instead, use @@Shift-click@.")
ENTRY ("Adding a point")
NORMAL ("@Click at the desired time location, and choose ##Add point at cursor# or type ##Command-P#.")
ENTRY ("Removing points")
NORMAL ("To remove one or more pitch points, "
	"make a @@time selection@ and choose ##Remove point(s)# from the ##Point# menu. "
	"If there is no selection, the point nearest to the cursor is removed.")
MAN_END

MAN_BEGIN ("PointEditor", "ppgb", 20030316)
INTRO ("One of the @Editors in P\\s{RAAT}, for viewing and manipulating a @PointProcess object, "
	"which is optionally shown together with a @Sound object.")
ENTRY ("Objects")
NORMAL ("The editor shows:")
LIST_ITEM ("\\bu The @Sound, if you selected a Sound object together with the PointProcess object "
	"before you clicked \"Edit\".")
LIST_ITEM ("\\bu The @PointProcess; vertical blue lines represent the points.")
ENTRY ("Playing")
NORMAL ("To play (a part of) the %resynthesized sound (pulse train): "
	"@click on any of the 8 buttons below and above the drawing area, or choose a Play command from the View menu.")
NORMAL ("To play the %original sound instead, use @@Shift-click@.")
ENTRY ("Adding a point")
NORMAL ("@Click at the desired time location, and choose \"Add point at cursor\" or type ##Command-P#.")
ENTRY ("Removing points")
NORMAL ("To remove one or more points, "
	"make a @@time selection@ and choose ##Remove point(s)# from the ##Point# menu. "
	"If there is no selection, the point nearest to the cursor is removed.")
MAN_END

MAN_BEGIN ("PointProcess", "ppgb", 20030521)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}.")
NORMAL ("A PointProcess object represents a %%point process%, "
	"which is a sequence of %points %t__%i_ in time, defined on a domain [%t__%min_, %t__%max_]. "
	"The index %i runs from 1 to the number of points. The points are sorted by time, i.e. %t__%i+1_ > %t__%i_.")
ENTRY ("PointProcess commands")
NORMAL ("Creation from scratch:")
LIST_ITEM ("\\bu @@Create empty PointProcess...@")
LIST_ITEM ("\\bu @@Create Poisson process...@")
NORMAL ("Creation of a pulse train from a pitch contour:")
LIST_ITEM ("\\bu @@PitchTier: To PointProcess@: area-1 along entire time domain.")
LIST_ITEM ("\\bu @@Pitch: To PointProcess@: same, but excludes voiceless intervals.")
LIST_ITEM ("\\bu @@Sound & Pitch: To PointProcess (cc)@: \"pitch-synchronous\": near locations of high amplitude.")
LIST_ITEM ("\\bu @@Sound & Pitch: To PointProcess (peaks)...@: \"pitch-synchronous\": near locations of high amplitude.")
LIST_ITEM ("\\bu @@Sound: To PointProcess (periodic, cc)...@: near locations of high amplitude.")
LIST_ITEM ("\\bu @@Sound: To PointProcess (periodic, peaks)...@: near locations of high amplitude.")
NORMAL ("Creation from converting another object:")
LIST_ITEM ("\\bu ##Matrix: To PointProcess")
LIST_ITEM ("\\bu @@TextTier: Down to PointProcess@")
LIST_ITEM ("\\bu @@PitchTier: Down to PointProcess@")
LIST_ITEM ("\\bu @@IntensityTier: Down to PointProcess@")
NORMAL ("Hearing:")
LIST_ITEM ("\\bu @@PointProcess: Play@: pulse train.")
LIST_ITEM ("\\bu @@PointProcess: Hum@: pulse train with formants.")
NORMAL ("Drawing:")
LIST_ITEM ("\\bu @@PointProcess: Draw...@")
NORMAL ("Editing:")
LIST_ITEM ("\\bu ##PointProcess: Edit#: invokes a @PointEditor.")
LIST_ITEM ("\\bu ##PointProcess & Sound: Edit#: invokes a @PointEditor.")
LIST_ITEM ("\\bu Inside a @ManipulationEditor.")
NORMAL ("Queries:")
LIST_ITEM ("\\bu @@PointProcess: Get jitter (local)...@: periodic jitter.")
LIST_ITEM ("\\bu @@PointProcess: Get jitter (local, absolute)...@: periodic jitter.")
LIST_ITEM ("\\bu @@PointProcess: Get jitter (rap)...@: periodic jitter.")
LIST_ITEM ("\\bu @@PointProcess: Get jitter (ppq5)...@: periodic jitter.")
LIST_ITEM ("\\bu @@PointProcess: Get jitter (ddp)...@: periodic jitter.")
LIST_ITEM ("\\bu @@PointProcess: Get low index...@: index of nearest point not after specified time.")
LIST_ITEM ("\\bu @@PointProcess: Get high index...@: index of nearest point not before specified time.")
LIST_ITEM ("\\bu @@PointProcess: Get nearest index...@: index of point nearest to specified time.")
LIST_ITEM ("\\bu @@PointProcess: Get interval...@: duration of interval around specified time.")
NORMAL ("Set calculations:")
LIST_ITEM ("\\bu @@PointProcesses: Union@: the union of two point processes.")
LIST_ITEM ("\\bu @@PointProcesses: Intersection@: the intersection of two point processes.")
LIST_ITEM ("\\bu @@PointProcesses: Difference@: the difference of two point processes.")
NORMAL ("Modification:")
LIST_ITEM ("\\bu @@PointProcess: Add point...@: at a specified time.")
LIST_ITEM ("\\bu @@PointProcess: Remove point...@: at specified index.")
LIST_ITEM ("\\bu @@PointProcess: Remove point near...@: near specified time.")
LIST_ITEM ("\\bu @@PointProcess: Remove points...@: between specified indices.")
LIST_ITEM ("\\bu @@PointProcess: Remove points between...@: between specified times.")
NORMAL ("Analysis:")
LIST_ITEM ("\\bu @@PointProcess: To PitchTier...@: pitch values in interval centres.")
LIST_ITEM ("\\bu ##PointProcess & Sound: To Manipulation")
NORMAL ("Synthesis:")
LIST_ITEM ("\\bu @@PointProcess: To Sound (pulse train)...@")
LIST_ITEM ("\\bu @@PointProcess: To Sound (hum)...@")
NORMAL ("Conversion:")
LIST_ITEM ("\\bu ##PointProcess: To Matrix")
LIST_ITEM ("\\bu @@PointProcess: Up to TextTier...")
LIST_ITEM ("\\bu @@PointProcess: Up to PitchTier...")
LIST_ITEM ("\\bu @@PointProcess: Up to IntensityTier...")
MAN_END

MAN_BEGIN ("PointProcess: Add point...", "ppgb", 20010410)
INTRO ("A command to add a point to each selected @PointProcess.")
ENTRY ("Argument")
TAG ("%Time (s)")
DEFINITION ("the time at which a point is to be added.")
ENTRY ("Behaviour")
NORMAL ("The point process is modified so that it contains the new point. "
	"If a point at the specified time was already present in the point process, nothing happens.")
MAN_END

MAN_BEGIN ("PointProcesses: Difference", "ppgb", 20021212)
INTRO ("A command to compute the difference of two selected @PointProcess objects.")
ENTRY ("Behaviour")
NORMAL ("The resulting #PointProcess will contain only those points of the first selected original point process "
	"that do not occur in the second.")
NORMAL ("The time domain of the resulting point process is equal to the time domain of the first original point process.")
MAN_END

MAN_BEGIN ("PointProcess: Draw...", "ppgb", 20021212)
INTRO ("A command to draw every selected @PointProcess into the @@Picture window@.")
MAN_END

MAN_BEGIN ("PointProcess: Get high index...", "ppgb", 20021212)
INTRO ("A @query to the selected @PointProcess object.")
ENTRY ("Return value")
NORMAL ("the index of the nearest point at or after the specified time, "
	"0 if the point process contains no points, "
	"or a number higher than the number of points if the specified time is after the last point.")
ENTRY ("Argument")
TAG ("%Time (seconds)")
DEFINITION ("the time from which a point is looked for.")
MAN_END

MAN_BEGIN ("PointProcess: Get interval...", "ppgb", 20021212)
INTRO ("A @query to the selected @PointProcess object.")
ENTRY ("Return value")
NORMAL ("the duration of the interval around a specified time. "
	"if the point process contains no points or if the specified time falls before the first point "
	"or not before the last point, the value is @undefined. Otherwise, the result is the distance between "
	"the nearest points to the left and to the right of the specified time. "
	"If the point process happens to contain a point at exactly the specified time, "
	"the duration of the interval following this point is returned.")
ENTRY ("Argument")
TAG ("%Time (seconds)")
DEFINITION ("the time around which a point is looked for.")
MAN_END

MAN_BEGIN ("PointProcess: Get jitter (local)...", "ppgb", 20030521)
INTRO ("A @query to the selected @PointProcess object. See @@Voice 2. Jitter@.")
MAN_END

MAN_BEGIN ("PointProcess: Get jitter (local, absolute)...", "ppgb", 20030521)
INTRO ("A @query to the selected @PointProcess object. See @@Voice 2. Jitter@.")
MAN_END

MAN_BEGIN ("PointProcess: Get jitter (rap)...", "ppgb", 20030521)
INTRO ("A @query to the selected @PointProcess object. See @@Voice 2. Jitter@.")
MAN_END

MAN_BEGIN ("PointProcess: Get jitter (ppq5)...", "ppgb", 20030521)
INTRO ("A @query to the selected @PointProcess object. See @@Voice 2. Jitter@.")
MAN_END

MAN_BEGIN ("PointProcess: Get jitter (ddp)...", "ppgb", 20030521)
INTRO ("A @query to the selected @PointProcess object.")
ENTRY ("Return value")
NORMAL ("the periodic jitter, which is defined as the relative mean absolute "
	"third-order difference of the point process (= the second-order difference of the interval process):")
FORMULA ("%jitter = \\su__%i=2_^^%N-1^ |2%T__%i_ - %T__%i-1_ - %T__%i+1_|  /  \\su__%i=2_^^%N-1^ %T__%i_")
NORMAL ("where %T__%i_ is the %%i%th interval and %N is the number of intervals. "
	"If no sequences of three intervals can be found whose durations "
	"are between %%Shortest period% and %%Longest period%, the result is @undefined.")
ENTRY ("Arguments")
TAG ("%%Shortest period% (seconds)")
DEFINITION ("the shortest possible interval that will be considered. For intervals %T__%i_ shorter than this, "
	"the (%i-1)st, %%i%th, and (%i+1)st terms in the formula are taken as zero. "
	"This argument will normally be very small, say 0.1 ms.")
TAG ("%%Longest period% (seconds)")
DEFINITION ("the shortest possible interval that will be considered. For intervals %T__%i_ longer than this, "
	"the (%i-1)st, %%i%th, and (%i+1)st terms in the formula are taken as zero. "
	"For example, if the minimum frequency of periodicity is 50 Hz, set this argument to 20 milliseconds; "
	"intervals longer than that will be considered voiceless.")
ENTRY ("Usage")
NORMAL ("The periodic jitter can be used as a measure of voice quality. See @@Voice 2. Jitter@.")
MAN_END

MAN_BEGIN ("PointProcess: Get low index...", "ppgb", 20021212)
INTRO ("A @query to the selected @PointProcess object.")
ENTRY ("Return value")
NORMAL ("the index of the nearest point before or at the specified time, "
	"or 0 if the point process contains no points or the specified time is before the first point.")
ENTRY ("Argument")
TAG ("%Time (seconds)")
DEFINITION ("the time from which a point is looked for.")
MAN_END

MAN_BEGIN ("PointProcess: Get nearest index...", "ppgb", 20021212)
INTRO ("A @query to the selected @PointProcess object.")
ENTRY ("Return value")
NORMAL ("the index of the point nearest to the specified time, "
	"or 0 if the point process contains no points.")
ENTRY ("Argument")
TAG ("%Time (seconds)")
DEFINITION ("the time around which a point is looked for.")
/*
form Get nearest raising zero
   real Time_(s) 0.5
endform
To PointProcess (zeroes)... yes no
index = Get nearest index... Time
if index = 0
   # Geen punten gevonden: default-actie.
   time = 'Time'
else
   time = Get time from index... index
endif
echo 'time'
*/
MAN_END

MAN_BEGIN ("PointProcess: Hum", "ppgb", 19970330)
INTRO ("A command to hear a @PointProcess.")
ENTRY ("Algorithm")
NORMAL ("A @Sound is created with the algorithm described at @@PointProcess: To Sound (hum)...@.")
NORMAL ("This sound is then played.")
MAN_END

MAN_BEGIN ("PointProcesses: Intersection", "ppgb", 20021212)
INTRO ("A command to merge two selected @PointProcess objects into one.")
ENTRY ("Behaviour")
NORMAL ("The resulting #PointProcess will contain only those points that occur in both original point processes.")
NORMAL ("The time domain of the resulting point process is the intersection of the time domains of the original point processes.")
MAN_END

MAN_BEGIN ("PointProcess: Play", "ppgb", 19970330)
INTRO ("A command to hear a @PointProcess.")
ENTRY ("Algorithm")
NORMAL ("A @Sound is created with the algorithm described at @@PointProcess: To Sound (pulse train)...@.")
NORMAL ("This sound is then played.")
MAN_END

MAN_BEGIN ("PointProcess: Remove point...", "ppgb", 20021212)
INTRO ("A command to remove a point from every selected @PointProcess.")
ENTRY ("Arguments")
TAG ("%Index")
DEFINITION ("the index of the point that is to be removed.")
ENTRY ("Behaviour")
NORMAL ("Does nothing if %index is less than 1 or greater than the number of points %nt in the point process. "
	"Otherwise, one point is removed (e.g., if %index is 3, the third point is removed), and the other points stay the same.")
MAN_END

MAN_BEGIN ("PointProcess: Remove point near...", "ppgb", 20021212)
INTRO ("A command to remove a point from every selected @PointProcess.")
ENTRY ("Arguments")
TAG ("%Time (seconds)")
DEFINITION ("the time around which a point is to be removed.")
ENTRY ("Behaviour")
NORMAL ("Does nothing if there are no points in the point process. "
	"Otherwise, the point nearest to %time is removed, and the other points stay the same.")
MAN_END

MAN_BEGIN ("PointProcess: Remove points...", "ppgb", 20021212)
INTRO ("A command to remove a range of points from every selected @PointProcess.")
ENTRY ("Arguments")
TAG ("%%From index% (\\>_ 1)")
DEFINITION ("the first index of the range of points that are to be removed.")
TAG ("%%To index%")
DEFINITION ("the last index of the range of points that are to be removed.")
ENTRY ("Behaviour")
NORMAL ("All points that originally fell in the range [%fromIndex, %toIndex] are removed, and the other points stay the same.")
MAN_END

MAN_BEGIN ("PointProcess: Remove points between...", "ppgb", 20021212)
INTRO ("A command to remove a range of points from every selected @PointProcess.")
ENTRY ("Arguments")
TAG ("%%From time% (seconds)")
DEFINITION ("the start of the domain from which all points are to be removed.")
TAG ("%%To time% (seconds)")
DEFINITION ("the end of the domain from which all points are to be removed.")
ENTRY ("Behaviour")
NORMAL ("All points that originally fell in the domain [%fromTime, %toTime], including the edges, are removed, "
	"and the other points stay the same.")
MAN_END

MAN_BEGIN ("PointProcess: To PitchTier...", "ppgb", 19970402)
INTRO ("A command to compute a @PitchTier from a @PointProcess.")
ENTRY ("Argument")
TAG ("%%Maximum interval% (s)")
DEFINITION ("the maximum duration of a period; intervals longer than this are considered voiceless.")
ENTRY ("Algorithm")
NORMAL ("A pitch point is constructed between each consecutive pair of points in the #PointProcess, "
	"if these are more than %maximumInterval apart. "
	"The associated pitch value will be the inverse of the duration of the interval between the two points.")
MAN_END

MAN_BEGIN ("PointProcess: To Sound (hum)...", "ppgb", 19970330)
INTRO ("A command to convert every selected @PointProcess into a @Sound.")
ENTRY ("Algorithm")
NORMAL ("A @Sound is created with the algorithm described at @@PointProcess: To Sound (pulse train)...@. "
	"This sound is then run through a sequence of second-order filters that represent five formants.")
MAN_END

MAN_BEGIN ("PointProcess: To Sound (pulse train)...", "ppgb", 20010309)
INTRO ("A command to convert every selected @PointProcess into a @Sound.")
ENTRY ("Algorithm")
NORMAL ("A pulse is generated at every point in the point process. This pulse is filtered at the Nyquist frequency "
	"of the resulting #Sound by converting it into a sampled #sinc function.")
ENTRY ("Arguments")
TAG ("%%Sampling frequency")
DEFINITION ("the sample rate of the resulting Sound object, e.g. 22050 Hertz.")
TAG ("%%Adaptation factor")
DEFINITION ("the factor by which a pulse height will be multiplied if the pulse time is not within "
	"%adaptationTime from the pre-previous pulse, and by which a pulse height will again be multiplied "
	"if the pulse time is not within %adaptationTime from the previous pulse. This factor is against "
	"abrupt starts of the pulse train after silences, and is 1.0 if you do want abrupt starts after silences.")
TAG ("%%Adaptation time")
DEFINITION ("the minimal period that will be considered a silence, e.g. 0.05 seconds.")
TAG ("%%Interpolation depth")
DEFINITION ("the extent of the sinc function to the left and to the right of the peak, e.g. 2000 samples.")
NORMAL ("Example: if %adaptationFactor is 0.6, and %adaptationTime is 0.02 s, "
	"then the heights of the first two pulses after silences of at least 20 ms "
	"will be multiplied by 0.36 and 0.6, respectively.")
MAN_END

MAN_BEGIN ("PointProcess: To TextGrid...", "ppgb", 19980113)
INTRO ("A command to create an empty @TextGrid from every selected @PointProcess.")
NORMAL ("The only information in the PointProcess that is used, is its starting and finishing times.")
ENTRY ("Arguments")
TAG ("%%Tier names")
DEFINITION ("a list of the names of the tiers that you want to create, separated by spaces.")
TAG ("%%Point tiers")
DEFINITION ("a list of the names of the tiers that you want to be %%point tiers%; "
	"the rest of the tiers will be %%interval tiers%.")
ENTRY ("Example")
NORMAL ("If %%Tier names% is \"a b c\", and %%Point tiers% is \"b\", "
	"the resulting TextGrid object will contain an interval tier named \"a\", "
	"a point tier named \"b\", and another interval tier named \"c\".")
MAN_END

MAN_BEGIN ("PointProcess: To TextGrid (vuv)...", "ppgb", 19980210)
INTRO ("A command to create a @TextGrid with voiced/unvoiced information "
	"from every selected @PointProcess.")
ENTRY ("Arguments")
TAG ("%%Maximum period% (s)")
DEFINITION ("the maximum interval that will be consider part of a larger voiced interval.")
TAG ("%%Mean period% (s)")
DEFINITION ("half of this value will be taken to be the amount to which a voiced interval "
	"will extend beyond its initial and final points. %%Mean period% must be less than "
	"%%Maximum period%, or you may get intervals with negative durations.")
ENTRY ("Example")
NORMAL ("If %%Maximum period% is 0.02 s, and %%Mean period% is 0.01 s, "
	"and the point process is 0.1 seconds long, with points at 20, 28, 39, 61, and 72 milliseconds, "
	"the resulting TextGrid object will contain an interval tier "
	"with \"U\" intervals at [0 ms, 15 ms], [44 ms, 56 ms], and [77 ms, 100 ms], "
	"and \"V\" intervals at [15 ms, 44 ms] and [56 ms, 77 ms].")
MAN_END

MAN_BEGIN ("PointProcesses: Union", "ppgb", 20021212)
INTRO ("A command to merge two selected @PointProcess objects into one.")
ENTRY ("Behaviour")
NORMAL ("The resulting #PointProcess will contain all the points of the two original point processes, sorted by time. "
	"Points that occur in both original point processes, will occur only once in the resulting point process.")
NORMAL ("The time domain of the resulting point process is the union of the time domains of the original point processes.")
MAN_END

MAN_BEGIN ("PointProcess: Up to IntensityTier...", "ppgb", 19970329)
INTRO ("A command to promote every selected @PointProcess to an @IntensityTier.")
ENTRY ("Argument")
TAG ("%Intensity (dB)")
DEFINITION ("the intensity that will be associated with every point.")
ENTRY ("Behaviour")
NORMAL ("The times of all the points are trivially copied, and so is the time domain. "
	"The intensity information will be the same for every point.")
MAN_END

MAN_BEGIN ("PointProcess: Up to PitchTier...", "ppgb", 19970329)
INTRO ("A command to promote every selected @PointProcess to a @PitchTier.")
ENTRY ("Argument")
TAG ("%Frequency (Hz)")
DEFINITION ("the pitch frequency that will be associated with every point.")
ENTRY ("Behaviour")
NORMAL ("The times of all the points are trivially copied, and so is the time domain. "
	"The pitch information will be the same for every point.")
MAN_END

MAN_BEGIN ("PointProcess: Up to TextTier...", "ppgb", 19970329)
INTRO ("A command to promote every selected @PointProcess to a @TextTier.")
ENTRY ("Argument")
TAG ("%Text")
DEFINITION ("the text that will be placed in every point.")
ENTRY ("Behaviour")
NORMAL ("The times of all the points are trivially copied, and so is the time domain. "
	"The text information will be the same for every point.")
MAN_END

MAN_BEGIN ("Polygon", "ppgb", 20030316)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}.")
NORMAL ("A Polygon object represents a sequence of points (%%x__i_, %%y__i_) in a two-dimensional space.")
MAN_END

MAN_BEGIN ("PSOLA", "ppgb", 20010330)
INTRO ("Pitch-Synchronous Overlap and Add, a method "
	"for manipulating the pitch and duration of an acoustic speech signal.")
ENTRY ("PSOLA synthesis")
NORMAL ("When a @Sound is created from a @Manipulation object, the following steps are performed:")
LIST_ITEM ("1. From the @PitchTier, new points are generated along the entire time domain, "
	"with the method of @@PitchTier: To PointProcess@.")
LIST_ITEM ("2. The period information in the pulses is used to remove from the new %pulses all points "
	"that lie within voiceless intervals (i.e., places where the distance between adjacent points "
	"in the original %pulses is greater than 20 ms.")
LIST_ITEM ("3. The voiceless parts are copied from the source Sound to the target Sound, "
	"re-using some parts if the local duration is greater than 1.")
LIST_ITEM ("4. For each %target point, we look up the nearest source point. A piece of the source Sound, "
	"centred around the source point, is copied to the target Sound at a location determined by "
	"the target point, using a bell-shaped window whose left-hand half-length is the minimum "
	"of the left-hand periods adjacent to the source and target points "
	"(and analogously for the right-hand half-length).")
MAN_END

MAN_BEGIN ("Quantile algorithm", "ppgb", 19980101)
INTRO ("An algorithm to compute the specified quantile of a sorted array of real numbers.")
NORMAL ("The %n\\%  %quantile of a continuous real-valued distribution is the value below which %n\\%  of the values "
	"is expected to lie. If we are given an array of real numbers that we want to interpret as having been drawn from a "
	"distribution, we can %estimate the quantiles of the underlying distribution.")
ENTRY ("1. The median")
NORMAL ("The %median is a special case of a quantile: it is the 50\\%  quantile. It is usually estimated as follows: "
	"from an odd number of values, take the middle value; form an even number, take the average of "
	"the two midmost values. For instance, if our values are 15, 20, and 32, the median is 20; "
	"if our values are 15, 20, 32, and 60, the median is 26.")
NORMAL ("This estimate is direction-independent: if we multiply all values by -1 (i.e., they become -60, -32, -20, and -15), "
	"the median is also multiplied by -1 (it becomes -26).")
ENTRY ("2. Percentiles?")
NORMAL ("The %%n%th %percentile of a set of values is usually defined as the highest attested value "
	"for which at most %n\\%  of all attested values are less or equal. "
	"For instance, if our values are 15, 20, 32, and 60, the 30th percentile is 15. Here is an extensive list:")
LIST_ITEM ("\tPercentile number\tValue")
LIST_ITEM ("\t0\t-")
LIST_ITEM ("\t10\t-")
LIST_ITEM ("\t20\t-")
LIST_ITEM ("\t30\t15")
LIST_ITEM ("\t40\t15")
LIST_ITEM ("\t50\t20")
LIST_ITEM ("\t60\t20")
LIST_ITEM ("\t70\t20")
LIST_ITEM ("\t80\t32")
LIST_ITEM ("\t90\t32")
LIST_ITEM ("\t100\t60")
NORMAL ("However, this procedure does not yield an estimate of the quantiles of the underlying distribution. "
	"For instance, the estimate is direction-dependent: if we multiply all values by -1, the 50th percentile "
	"becomes -32 instead of -20, and the 70th percentile becomes -32 instead of the expected -15, "
	"which is minus the 30th percentile of the original data set.")
ENTRY ("3. Unbiased quantiles")
NORMAL ("To get a better estimate of the quantiles of the underlying distribution, the interpolation that we used "
	"to determine the median, is generalized to %any quantile.")
NORMAL ("We assume that the attested values 15, 20, 32, and 60 each take up one quarter of the \"quantile space\". "
	"These four values are in the middles of those quarters, so they are at the 0.125, 0.375, 0.625, and 0.875 quantiles.")
NORMAL ("Quantiles in between 0.125 and 0.875 are evaluated by linear interpolation: the 0.25, 0.50, and 0.75 quantiles "
	"are 17.5, 26, and 46, respectively. Note that the 0.50 quantile is the median. The 0.40 quantile, for example, "
	"is estimated as 20 + (32 - 20)\\.c(0.40 - 0.375)/(0.625 - 0.375) = 21.2.")
NORMAL ("Quantiles between 0 and 0.125 or between 0.875 and 1 are evaluated by linear extrapolation from the "
	"lowest or highest pair of values: the 0\\%  quantile is estimated as 15 - 1/2 (20 - 15) = 12.5, "
	"and the 100\\%  quantile is estimated as 60 + 1/2 (60 - 32) = 74. The 0.10 quantile is estimated as "
	"12.5 + (15 - 12.5)\\.c(0.10 - 0.0)/(0.125 - 0.0) = 14.5.")
NORMAL ("Note that the estimated values for the very low or high quantiles can lie outside the range of attested values. "
	"In fact, the computed 0\\%  and 100\\%  quantiles are thought to be estimates of the minimum and maximum values "
	"of the distribution. For uniform distributions, these estimates are reasonable; for a normal distribution, of course, "
	"the 0\\%  and 100\\%  quantiles are meaningless.")
MAN_END

MAN_BEGIN ("Read Matrix from raw text file...", "ppgb", 19980322)
INTRO ("A command to read a @Matrix object from a file on disk.")
ENTRY ("File format")
NORMAL ("The file should contain each row of the matrix on a separate line. Within each row, "
	"the elements must be separated by spaces or tabs.")
NORMAL ("For instance, the following text file will be read as a Matrix with three rows and four columns:")
CODE ("0.19 3 245 123")
CODE ("18e-6 -3e18 0 0.0")
CODE ("1.5 2.5 3.5 4.5")
NORMAL ("The resulting Matrix will have the same domain and sampling as Matrices created with "
	"##Create simple Matrix...#. In the above example, this means that the Matrix will have "
	"%x__%min_ = 0.5, %x__%max_ = 4.5, %n__%x_ = 4, %dx = 1.0, %x__1_ = 1.0, "
	"%y__%min_ = 0.5, %y__%max_ = 3.5, %n__%y_ = 3, %dy = 1.0, %y__1_ = 1.0.")
MAN_END

MAN_BEGIN ("Read Strings from raw text file...", "ppgb", 19990502)
INTRO ("A command to read a @Strings object from a simple text file. "
	"Each line is read as a separate string. See @Strings for an example.")
MAN_END

MAN_BEGIN ("Record mono Sound...", "ppgb", 20021212)
INTRO ("A command in the @@New menu@ to record a @Sound. Creates a @SoundRecorder window, "
	"except on very old Macintoshes with 8-bit audio, where it presents a native Macintosh sound-recorder window.")
MAN_END

MAN_BEGIN ("Record stereo Sound...", "ppgb", 20021212)
INTRO ("A command in the @@New menu@ to record a @Sound. Creates a @SoundRecorder window.")
MAN_END


/*
NORMAL ("The following classes inherit directly or indirectly the attributes of #Sampled:")
LIST_ITEM ("\\bu @Matrix:")
LIST_ITEM ("        \\bu @Sound")
LIST_ITEM ("        \\bu @Spectrum")
LIST_ITEM ("        \\bu @Spectrogram")
LIST_ITEM ("        \\bu @Intensity")
LIST_ITEM ("        \\bu @Harmonicity")
LIST_ITEM ("        \\bu @Ltas")
LIST_ITEM ("        \\bu @Confusion")
LIST_ITEM ("        \\bu @Excitation")
LIST_ITEM ("        \\bu @Cochleagram")
LIST_ITEM ("        \\bu @VocalTract")
LIST_ITEM ("\\bu @Pitch")
LIST_ITEM ("\\bu @Formant")
LIST_ITEM ("\\bu @LongSound")
MAN_END
*/

MAN_BEGIN ("Shift-drag", "ppgb", 19980823)
INTRO ("Shift-dragging is one of the ways to control @Editors.")
ENTRY ("How to Shift-drag")
LIST_ITEM ("1. Position the mouse above any of the objects that you want to drag "
	"(the objects were probably selected first).")
LIST_ITEM ("2. Press a Shift key.")
LIST_ITEM ("3. Press the (left) mouse button.")
LIST_ITEM ("4. Keeping the mouse button pressed, move the mouse across the window. "
	"A shadow of the objects will follow.")
LIST_ITEM ("5. Release the mouse button when it is above the location where you want your objects "
	"to be moved. If this %%drop site% makes any sense, the objects will move there.")
ENTRY ("Usage in the Praat program")
NORMAL ("While plain @@drag@ging is used for moving objects that were selected first by clicking, "
	"##Shift-dragging# is used for manipulating the times and values of more marks, targets, "
	"or boundaries simultaneously:")
MAN_END

MAN_BEGIN ("Shift-click", "ppgb", 19960913)
INTRO ("One of the ways to control @Editors.")
ENTRY ("How to Shift-click")
LIST_ITEM ("1. Position the mouse above the object that you want to Shift-click.")
LIST_ITEM ("2. Press a Shift key.")
LIST_ITEM ("3. Press and release the (left) mouse button.")
ENTRY ("Usage in the Praat program")
NORMAL ("Whereas plain @@click@ing is used for selecting only one object while deselecting "
	"all previously selected objects, ##Shift-click# is used for selecting a mark, target, "
	"or boundary, %without deselecting the previously selected objects:")
MAN_END

MAN_BEGIN ("Sound", "ppgb", 20040113)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}. For tutorial information, see all of the @Intro.")
ENTRY ("Commands")
NORMAL ("Creation:")
LIST_ITEM ("\\bu @@Record mono Sound...@ (from microphone or line input, with the @SoundRecorder)")
LIST_ITEM ("\\bu @@Record stereo Sound...@")
LIST_ITEM ("\\bu @@Create Sound...@ (from a formula)")
LIST_ITEM ("\\bu @@Create Sound from tone complex...")
LIST_ITEM ("\\bu @@Create Sound from gamma-tone...")
LIST_ITEM ("\\bu @@Create Sound from Shepard tone...")
NORMAL ("Reading and writing:")
LIST_ITEM ("\\bu @@Sound files")
NORMAL ("You can also use the text and binary (real-valued) formats for Sounds, like for any other class:")
LIST_ITEM ("\\bu @@Write to text file...")
LIST_ITEM ("\\bu @@Write to binary file...")
NORMAL ("Playing:")
LIST_ITEM ("\\bu @@Sound: Play")
LIST_ITEM ("\\bu @@PointProcess: Hum")
LIST_ITEM ("\\bu @@PointProcess: Play")
NORMAL ("Viewing and editing:")
LIST_ITEM ("\\bu @SoundEditor, @ManipulationEditor, @TextGridEditor, @PointEditor, @PitchTierEditor, "
	"@SpectrumEditor")
NORMAL ("Queries:")
LIST_ITEM ("structure:")
LIST_ITEM1 ("\\bu @@Get starting time")
LIST_ITEM1 ("\\bu @@Get finishing time")
LIST_ITEM1 ("\\bu @@Get duration")
LIST_ITEM1 ("\\bu @@Sound: Get number of samples")
LIST_ITEM1 ("\\bu @@Sound: Get sample period")
LIST_ITEM1 ("\\bu @@Sound: Get sample rate")
LIST_ITEM1 ("\\bu @@Sound: Get time from index...")
LIST_ITEM1 ("\\bu @@Sound: Get index from time...")
LIST_ITEM ("content:")
LIST_ITEM1 ("\\bu @@Sound: Get value at time...")
LIST_ITEM1 ("\\bu @@Sound: Get value at index...")
LIST_ITEM ("shape:")
LIST_ITEM1 ("\\bu @@Sound: Get minimum...")
LIST_ITEM1 ("\\bu @@Sound: Get time of minimum...")
LIST_ITEM1 ("\\bu @@Sound: Get maximum...")
LIST_ITEM1 ("\\bu @@Sound: Get time of maximum...")
LIST_ITEM1 ("\\bu @@Sound: Get absolute extremum...")
LIST_ITEM1 ("\\bu @@Sound: Get nearest zero crossing...")
LIST_ITEM ("statistics:")
LIST_ITEM1 ("\\bu @@Sound: Get mean...")
LIST_ITEM1 ("\\bu @@Sound: Get root-mean-square...")
LIST_ITEM1 ("\\bu @@Sound: Get standard deviation...")
LIST_ITEM ("energy:")
LIST_ITEM1 ("\\bu @@Sound: Get energy...")
LIST_ITEM1 ("\\bu @@Sound: Get power...")
LIST_ITEM ("in air:")
LIST_ITEM1 ("\\bu @@Sound: Get energy in air")
LIST_ITEM1 ("\\bu @@Sound: Get power in air")
LIST_ITEM1 ("\\bu @@Sound: Get intensity (dB)")
NORMAL ("Modification:")
LIST_ITEM ("\\bu @@Matrix: Formula...")
LIST_ITEM ("\\bu @@Sound: Set value at index...")
LIST_ITEM ("\\bu @@Sound: Filter with one formant (in-line)...")
LIST_ITEM ("\\bu @@Sound: Pre-emphasize (in-line)...")
LIST_ITEM ("\\bu @@Sound: De-emphasize (in-line)...")
NORMAL ("Annotation (see @@Intro 7. Annotation@):")
LIST_ITEM ("\\bu @@Sound: To TextGrid...")
NORMAL ("Periodicity analysis:")
LIST_ITEM ("\\bu @@Sound: To Pitch...")
LIST_ITEM ("\\bu @@Sound: To Pitch (ac)...")
LIST_ITEM ("\\bu @@Sound: To Pitch (cc)...")
LIST_ITEM ("\\bu @@Sound: To Pitch (shs)...")
LIST_ITEM ("\\bu @@Sound: To Harmonicity (ac)...")
LIST_ITEM ("\\bu @@Sound: To Harmonicity (cc)...")
LIST_ITEM ("\\bu @@Sound: To PointProcess (periodic, cc)...")
LIST_ITEM ("\\bu @@Sound: To PointProcess (periodic, peaks)...")
LIST_ITEM ("\\bu @@Sound & Pitch: To PointProcess (cc)")
LIST_ITEM ("\\bu @@Sound & Pitch: To PointProcess (peaks)...")
LIST_ITEM ("\\bu @@Sound: To Intensity...")
NORMAL ("Spectral analysis:")
LIST_ITEM ("\\bu @@Sound: To Spectrum (fft)")
LIST_ITEM ("\\bu @@Sound: To Spectrogram...")
LIST_ITEM ("\\bu @@Sound: To Formant (burg)...")
LIST_ITEM ("\\bu @@Sound: To Formant (sl)...")
LIST_ITEM ("\\bu @@Sound: LPC analysis")
LIST_ITEM1 ("\\bu @@Sound: To LPC (autocorrelation)...")
LIST_ITEM1 ("\\bu @@Sound: To LPC (covariance)...")
LIST_ITEM1 ("\\bu @@Sound: To LPC (burg)...")
LIST_ITEM1 ("\\bu @@Sound: To LPC (marple)...")
NORMAL ("Filtering (see @Filtering tutorial):")
LIST_ITEM ("\\bu @@Sound: Filter (pass Hann band)...")
LIST_ITEM ("\\bu @@Sound: Filter (stop Hann band)...")
LIST_ITEM ("\\bu @@Sound: Filter (formula)...")
LIST_ITEM ("\\bu @@Sound: Filter (one formant)...")
LIST_ITEM ("\\bu @@Sound: Filter (pre-emphasis)...")
LIST_ITEM ("\\bu @@Sound: Filter (de-emphasis)...")
LIST_ITEM ("\\bu @@LPC & Sound: Filter...")
LIST_ITEM ("\\bu @@LPC & Sound: Filter (inverse)")
LIST_ITEM ("\\bu @@Sound & Formant: Filter")
LIST_ITEM ("\\bu @@Sound & FormantTier: Filter")
NORMAL ("Conversion:")
LIST_ITEM ("\\bu @@Sound: Resample...")
NORMAL ("Enhancement:")
LIST_ITEM ("\\bu @@Sound: Lengthen (PSOLA)...@: lengthen by a constant factor")
LIST_ITEM ("\\bu @@Sound: Deepen band modulation...@: strenghten intensity modulations in each critical band")
NORMAL ("Combination:")
LIST_ITEM ("\\bu @@Sounds: Convolve")
LIST_ITEM ("\\bu @@Sounds: Concatenate")
NORMAL ("Synthesis")
LIST_ITEM ("\\bu @@Source-filter synthesis@ tutorial")
LIST_ITEM ("\\bu @Manipulation (@PSOLA etc.)")
LIST_ITEM ("\\bu @@Spectrum: To Sound (fft)")
LIST_ITEM ("\\bu ##Pitch: To Sound...")
LIST_ITEM ("\\bu @@PointProcess: To Sound (pulse train)...")
LIST_ITEM ("\\bu @@PointProcess: To Sound (hum)...")
LIST_ITEM ("\\bu ##Pitch & PointProcess: To Sound...")
LIST_ITEM ("\\bu @@Articulatory synthesis@ tutorial")
LIST_ITEM ("\\bu @@Artword & Speaker: To Sound...")
ENTRY ("Inside a Sound")
NORMAL ("With @Inspect, you will see that a Sound contains the following data:")
TAG ("%x__%min_")
DEFINITION ("starting time, in seconds.")
TAG ("%x__%max_ > %x__%min_")
DEFINITION ("end time, in seconds.")
TAG ("%n__%x_")
DEFINITION ("the number of samples (\\>_ 1).")
TAG ("%dx")
DEFINITION ("sample period, in seconds. The inverse of the sample rate (in Hz).")
TAG ("%x__1_")
DEFINITION ("the time associated with the first sample (in seconds). "
	"This will normally be in the range [%xmin, %xmax]. "
	"The time associated with the last sample (i.e., %x__1_ + (%nx \\-- 1) %dx)) "
	"will also normally be in that range. Mostly, the sound starts at %t = 0 seconds "
	"and %x__1_ = %dx / 2. Also, usually, %x__%max_ = %n__%x_ %dx.")
TAG ("%z [1] [1..%n__%x_]")
DEFINITION ("the amplitude of the sound (stored as single-precision floating-point numbers). "
	"For the most common applications (playing and file I-O), Praat assumes that "
	"the amplitude is greater than -1 and less than +1. "
	"For some applications (modelling of the inner ear; "
	"articulatory synthesis), Praat assumes that the amplitude is expressed in Pascal units. "
	"If these interpretations are combined, we see that the maximum peak amplitude of "
	"a calibrated sound is 1 Pascal; for a sine wave, this means 91 dB SPL.")
ENTRY ("Limitations")
NORMAL ("Since the Sound object completely resides in memory, its size is limited "
	"to the amount of RAM in your computer. For sounds longer than a few minutes, "
	"you could use the @LongSound object instead, which you can view in the @LongSoundEditor.")
MAN_END

MAN_BEGIN ("Sound: De-emphasize (in-line)...", "ppgb", 20030309)
INTRO ("A command to change the spectral slope of every selected @Sound object.")
NORMAL ("The reverse of @@Sound: Pre-emphasize (in-line)...@. For an example, see @@Source-filter synthesis@.")
NORMAL ("This is the in-line version of @@Sound: Filter (de-emphasis)...@, "
	"i.e., it does not create a new Sound object but modifies an existing object.")
ENTRY ("Argument")
TAG ("%%From frequency% (Hz)")
DEFINITION ("the frequency %F above which the spectral slope will decrease by 6 dB/octave.")
ENTRY ("Algorithm")
NORMAL ("The de-emphasis factor %\\al is computed as")
FORMULA ("%\\al = exp (-2 %\\pi %F \\De%t)")
NORMAL ("where \\De%t is the sampling period of the sound. Every sample %x__%i_ of the sound, "
	"except %x__1_, is then changed, going up from the second sample:")
FORMULA ("%x__%i_ = %x__%i_ + %\\al %x__%i-1_")
MAN_END

MAN_BEGIN ("Sound: Deepen band modulation...", "ppgb", 20030916)
INTRO ("A command to enhance the fast spectral changes, like %F__2_ movements, in each selected @Sound object.")
ENTRY ("Arguments")
TAG ("%Enhancement (dB)")
DEFINITION ("the maximum increase in the level within each critical band. The standard value is 20 dB.")
TAG ("%%From frequency% (Hz)")
DEFINITION ("the lowest frequency that shall be manipulated. The bottom frequency of the first critical band that is to be enhanced. "
	"The standard value is 300 Hertz.")
TAG ("%%To frequency% (Hz)")
DEFINITION ("the highest frequency that shall be manipulated (the last critical band may be narrower than the others). The standard value is 8000 Hz.")
TAG ("%%Slow modulation% (Hz)")
DEFINITION ("the frequency %f__%slow_ below which the intensity modulations in the bands should not be expanded. The standard value is 3 Hz.")
TAG ("%%Fast modulation% (Hz)")
DEFINITION ("the frequency %f__%fast_ above which the intensity modulations in the bands should not be expanded. The standard value is 30 Hz.")
TAG ("%%Band smoothing% (Hz)")
DEFINITION ("the degree of overlap of each band into its adjacent bands. Prevents %ringing. The standard value is 100 Hz.")
ENTRY ("Algorithm")
NORMAL ("Suppose we have the standard settings of the arguments. The resulting sound will composed of the unfiltered part of the original sound, "
	"plus all manipulated bands.")
NORMAL ("First, the resulting sound becomes the original sound, stop-band filtered between 300 and 8000 Hz: "
	"after a forward Fourier transform, all values in the @Spectrum at frequencies between 0 and 200 Hz and "
	"between 8100 Hz and the Nyquist frequency of the sound are retained unchanged. "
	"The spectral values at frequencies between 400 and 7900 Hz are set to zero. "
	"Between 200 and 400 Hz and between 7900 and 8100 Hz, the values are multiplied by a raised sine, "
	"so as to give a smooth transition without ringing in the time domain (the raised sine also allows us to view "
	"the spectrum as a sum of spectral bands). Finally, a backward Fourier transform gives us the filtered sound.")
NORMAL ("The remaining part of the spectrum is divided into %%critical bands%, i.e. frequency bands one Bark wide. "
	"For instance, the first critical band run from 300 to 406 Hz, the second from 406 to 520 Hz, and so on. "
	"Each critical band is converted to a pass-band filtered sound by means of the backward Fourier transform.")
NORMAL ("Each filtered sound will be manipulated, and the resulting manipulated sounds are added to the stop-band filtered sound "
	"we created earlier. If the manipulation is the identity transformation, the resulting sound will be equal to the original sound. "
	"But, of course, the manipulation does something different. Here are the steps.")
NORMAL ("First, we compute the local intensity of the filtered sound %x (%t):")
FORMULA ("%intensity (%t) = 10 log__10_ (%x^2 (%t) + 10^^-6^)")
NORMAL ("This intensity is subjected to a forward Fourier transform. In the frequency domain, we administer a band filter. "
	"We want to enhance the intensity modulation in the range between 3 and 30 Hz. "
	"We can achieve this by comparing the very smooth intensity contour, low-pass filtered at %f__%slow_ = 3 Hz, "
	"with the intensity contour that has enough temporal resolution to see the place-discriminating %F__2_ movements, "
	"which is low-pass filtered at %f__%fast_ = 30 Hz. In the frequency domain, the filter is")
FORMULA ("%H (%f) = exp (- (%\\al%f / %f__%fast_)^2) - exp (- (%\\al%f / %f__%slow_)^2)")
NORMAL ("where %\\al equals \\Vrln 2 \\~~ 1 / 1.2011224, so that %H (%f) has its -6 dB points at %f__%slow_ and %f__%fast_:")
PICTURE (5, 3, draw_SoundDeepen_filter)
NORMAL ("Now, why do we use such a flat filter? Because a steep filter would show ringing effects in the time domain, "
	"dividing the sound into 30-ms chunks. If our filter is a sum of exponentials in the frequency domain, it will also "
	"be a sum of exponentials in the time domain. The backward Fourier transform of the frequency response %H (%f) "
	"is the impulse response %h (%t). It is given by")
FORMULA ("%h (%t) = 2%\\pi\\Vr%\\pi %f__%fast_/%\\al exp (-(%\\pi%t%f__%fast_/%\\al)^2) - "
	"2%\\pi\\Vr%\\pi %f__%slow_/%\\al exp (-(%\\pi%t%f__%slow_/%\\al)^2)")
NORMAL ("This impulse response behaves well:")
PICTURE (5, 3, draw_SoundDeepen_impulse)
NORMAL ("We see that any short intensity peak will be enhanced, and that this enhancement will suppress the intensity "
	"around 30 milliseconds from the peak. Non-Gaussian frequency-domain filters would have given several maxima and minima "
	"in the impulse response, clearly an undesirable phenomenon.")
NORMAL ("After the filtered band is subjected to a backward Fourier transform, we convert it into power again:")
FORMULA ("%power (%t) = 10^^%filtered / 2^")
NORMAL ("The relative enhancement has a maximum that is smoothly related to the basilar place:")
FORMULA ("%ceiling = 1 + (10^^%enhancement / 20^ - 1) \\.c (1/2 - 1/2 cos (%\\pi %f__%midbark_ / 13))")
NORMAL ("where %f__%midbark_ is the mid frequency of the band. Clipping is implemented as")
FORMULA ("%factor (%t) = 1 / (1 / %power (%t) + 1 / %ceiling)")
NORMAL ("Finally, the original filtered sound %x (%t), multiplied by this factor, is added to the output.")
/*
form Consonantversterker
	positive Enhancement_(dB) 20
	choice Algoritme: 3
		button (1) Luide stukken spreiden in de tijd
		button (2) Versterken bij beweging
		button (3) Intensiteitscontour filteren
	comment Al deze algoritmen werken binnen alle frequentiebanden!
endform
smooth = 100
low = 300
high = 8000
maximumFactor = 10^(Enhancement/20)

Copy... original

# Remove filter bands.
To Spectrum (fft)
Formula... if x<'low'-'smooth' then self else
... if x<'low'+'smooth' then self*(0.5+0.5*cos(pi*(x-('low'-'smooth'))/(2*'smooth'))) else
... if x<'high'-'smooth' then 0 else
... if x<'high'+'smooth' then self*(0.5-0.5*cos(pi*(x-('high'-'smooth'))/(2*'smooth'))) else
... self fi fi fi fi
To Sound (fft)
Rename... enhanced

min = low
while min < high
	mid_bark = hertzToBark (min) + 0.5
	max = round (barkToHertz (hertzToBark (min) + 1))
	if max > high
		max = high
	endif
	call enhance_one_band
	min = max
endwhile

select Spectrum original
plus Sound original
Remove

select Sound enhanced
Rename... 'Algoritme'_'Enhancement'
Scale... 0.99

procedure enhance_one_band
	select Sound original
	To Spectrum (fft)
	Formula... if x<'min'-'smooth'then 0 else
	... if x<'min'+'smooth' then self*(0.5-0.5*cos(pi*(x-('min'-'smooth'))/(2*'smooth'))) else
	... if x<'max'-'smooth' then self else
	... if x<'max'+'smooth' then self*(0.5+0.5*cos(pi*(x-('max'-'smooth'))/(2*'smooth'))) else
	... 0 fi fi fi fi
	Rename... band
	To Sound (fft)
if Algoritme = 1
	To Intensity... 120 0.01
	select Intensity band
	Erase all
	Viewport... 0 6 0 4
	Draw... 0 5 0 80 yes
	Down to Matrix
	Rename... factor
	Formula... if Intensity_band [col-2] > self then Intensity_band [col-2] else self fi
	Formula... if Intensity_band [col-1] > self then Intensity_band [col-1] else self fi
	Formula... if Intensity_band [col+1] > self then Intensity_band [col+1] else self fi
	Formula... if Intensity_band [col+2] > self then Intensity_band [col+2] else self fi
	Red
	Draw rows... 0 5 0 0 0 80
	Black
	Formula... self - Intensity_band []
	Formula... if self > 'Enhancement' then 'Enhancement' else self fi
	Formula... 10^(self/20)
	Viewport... 0 6 4 8
	Draw rows... 0 5 0 0 0 Enhancement
	Draw inner box
	Text top... yes Band from 'min' to 'max' Hertz
	Marks bottom... 2 yes yes no
	Marks left every... 1 5 yes yes yes
	select Intensity band
	Remove
elsif Algoritme = 2
	To Intensity... 120 0.01
	# Enhance contour
	Erase all
	Viewport... 0 6 0 4
	Draw... 0 5 0 80 yes
	Down to Matrix
	Rename... factor
	Formula... if col = 1 or col = ncol then 1 else
		... (abs (Intensity_band [col-1] - Intensity_band []) +
		... abs (Intensity_band [col+1] - Intensity_band []))*0.5 fi
	Formula... if self < 1 then 1 else if self > 'maximumFactor' then 'maximumFactor' else self fi fi
	Red
	Draw rows... 0 5 0 0 1 maximumFactor
	Black
	Text top... yes Band from 'min' to 'max' Hertz
	Marks right every... 1 1 yes yes yes
	select Intensity band
	Remove
elsif Algoritme = 3
	Copy... intensity
	Formula... self^2+1e-6
Formula... 10*log10(self)
	To Spectrum (fft)
	Rename... intensityfilt
	Formula... self*exp(-(x/35)^2)-self*exp(-(x/3.5)^2); if x<3 or x>30 then 0 else self fi;
	To Sound (fft)
	Erase all
	Viewport... 0 6 0 4
	Text top... no Band van 'min' tot 'max' Hertz
	Draw... 0 5 -10 10 yes
	Down to Matrix
	Rename... factor
	Formula... 10^(Sound_intensityfilt[]/2)
ceiling = 1+(maximumFactor -1)*(0.5-0.5*cos(pi*mid_bark/13))
	Formula... 1/(1/self+1/'ceiling')
	Viewport... 0 6 4 8
	Draw rows... 0 5 0 0 0 ceiling
	Draw inner box
	Marks bottom... 2 yes yes no
	Marks left every... 1 1 yes yes yes
	select Sound intensity
	plus Spectrum intensityfilt
	plus Sound intensityfilt
	Remove
endif
	select Sound band
	Formula... self*Matrix_factor()

	select Sound enhanced
	Formula... self+Sound_band[]

	select Matrix factor
	plus Spectrum band
	plus Sound band
	Remove
endproc
*/
MAN_END

/*
Sound: Filter (freq. domain):
>> Nog iets anders. Ik heb het een tijdje geleden met jou gehad over 'troep'
>> die met jouw eenvoudige filtertechniek in geluidsfiles terechtkomt. In de
>> attachment zit een (synthetische) spraakuiting met hier en daar een (echte)
>> stilte erin. Filter die maar eens met een 'telefoonfilter'(alles 0 voor
>> x<300 or x>3400). Hier in Nijmegen krijg ik er dan een hele vieze zoemtoon
>> in, die ook duidelijk te zien is in de stilten van het signaal.
>
>Je bedoelt met de formule if x<300 or x>3400 then 0 else self fi ?

Ja


>De top van de 300-Hz-ringing is bij mij -40 dB bij 0.54 seconde,
>en -46 dB bij 1.89 seconde. Hoort dat niet?
*/

MAN_BEGIN ("Sound: Filter (de-emphasis)...", "ppgb", 20030309)
INTRO ("A command to filter every selected @Sound object. The resulting Sound object has a lower spectral slope.")
NORMAL ("The reverse of @@Sound: Filter (pre-emphasis)...@. For an example, see @@Source-filter synthesis@.")
ENTRY ("Argument")
TAG ("%%From frequency% (Hz)")
DEFINITION ("the frequency %F above which the spectral slope will decrease by 6 dB/octave.")
ENTRY ("Algorithm")
NORMAL ("The de-emphasis factor %\\al is computed as")
FORMULA ("%\\al = exp (-2 %\\pi %F \\De%t)")
NORMAL ("where \\De%t is the sampling period of the sound. The new sound %y is then computed recursively as:")
FORMULA ("%y__1_ = %x__1_")
FORMULA ("%y__%i_ = %x__%i_ + %\\al %y__%i-1_")
MAN_END

MAN_BEGIN ("Sound: Filter (formula)...", "ppgb", 20030916)
INTRO ("A command to convert every selected @Sound object into a filtered sound.")
NORMAL ("The filtering is done in the frequency domain. This command is equivalent to the following sequence:")
LIST_ITEM ("1. @@Sound: To Spectrum (fft)")
LIST_ITEM ("2. @@Matrix: Formula...")
LIST_ITEM ("3. @@Spectrum: To Sound (fft)")
NORMAL ("For a comparative discussion of various filtering methods, see the @Filtering tutorial.")
NORMAL ("The example formula is the following:")
CODE ("if x<500 or x>1000 then 0 else self fi; rectangular band")
NORMAL ("This formula represents a rectangular pass band between 500 Hz and 1000 Hz (%x is the frequency). "
	"Rectangular bands are %not recommended, since they may lead to an appreciable amount of %#ringing in the time domain. "
	"The transition between stop and pass band should be smooth, as e.g. in @@Sound: Filter (pass Hann band)...@.")
MAN_END

MAN_BEGIN ("Sound: Filter (one formant)...", "ppgb", 20030309)
INTRO ("A command to filter every selected @Sound object, with a single formant of a specified frequency and bandwidth.")
ENTRY ("Algorithm")
NORMAL ("Two recursive filter coefficients are computed as follows:")
FORMULA ("%p = \\--2 exp (\\--%\\pi %bandwidth %dt) cos (2%\\pi %frequency %dt)")
FORMULA ("%q = exp (\\--2%\\pi %bandwidth %dt)")
NORMAL ("where %dt is the sample period. The new signal %y is then computed from the old signal %x and itself as")
FORMULA ("%y__1_ := %x__1_")
FORMULA ("%y__2_ := %x__2_ \\-- %p %y__1_")
FORMULA ("\\At%n \\>_ 3:   %y__n_ := %x__n_ \\-- %p %y__%n-1_ \\-- %q %y__%n-2_")
NORMAL ("After filtering, the sound %y is scaled so that its absolute extremum is 0.9.")
NORMAL ("For a comparative discussion of various filtering methods, see the @Filtering tutorial.")
NORMAL ("This filter has an in-line version: @@Sound: Filter with one formant (in-line)...@.")
MAN_END

MAN_BEGIN ("Sound: Filter with one formant (in-line)...", "ppgb", 20030309)
INTRO ("A command to filter every selected @Sound object in-line, with a single formant of a specified frequency and bandwidth.")
NORMAL ("This is the in-line version of @@Sound: Filter (one formant)...@, "
	"i.e. it does not create a new Sound object but modifies the selected object.")
MAN_END

MAN_BEGIN ("Sound: Filter (pass Hann band)...", "ppgb", 20020526)
INTRO ("A command to convert every selected @Sound object into a filtered sound.")
NORMAL ("The filtering is done in the frequency domain. This command is equivalent to the following sequence:")
LIST_ITEM ("1. @@Sound: To Spectrum (fft)")
LIST_ITEM ("2. @@Spectrum: Filter (pass Hann band)...")
LIST_ITEM ("3. @@Spectrum: To Sound (fft)")
NORMAL ("For a comparative discussion of various filtering methods, see the @Filtering tutorial.")
NORMAL ("For a complementary filter, see @@Sound: Filter (stop Hann band)...@.")
MAN_END

MAN_BEGIN ("Sound: Filter (stop Hann band)...", "ppgb", 20020526)
INTRO ("A command to convert every selected @Sound object into a filtered sound.")
NORMAL ("The filtering is done in the frequency domain. This command is equivalent to the following sequence:")
LIST_ITEM ("1. @@Sound: To Spectrum (fft)")
LIST_ITEM ("2. @@Spectrum: Filter (stop Hann band)...")
LIST_ITEM ("3. @@Spectrum: To Sound (fft)")
NORMAL ("For a comparative discussion of various filtering methods, see the @Filtering tutorial.")
NORMAL ("For a complementary filter, see @@Sound: Filter (pass Hann band)...@.")
MAN_END

MAN_BEGIN ("Sound: Formula...", "ppgb", 20021206)
INTRO ("A command for changing the data in all selected @Sound objects.")
NORMAL ("See the @Formulas tutorial for examples and explanations.")
MAN_END

MAN_BEGIN ("Sound: Get absolute extremum...", "ppgb", 20030916)
INTRO ("A @query to the selected @Sound object.")
ENTRY ("Return value")
NORMAL ("the absolute extremum (in Pascal) within a specified time window.")
ENTRY ("Arguments")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the time window. Values outside this window are ignored, except for interpolation. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the sound is considered.")
TAG ("%%Interpolation")
DEFINITION ("the interpolation method (None, Parabolic, Sinc) of the @@vector peak interpolation@. "
	"The standard is Sinc70 because a Sound object is normally a sampled band-limited signal, "
	"which can be seen as a sum of sinc functions.")
MAN_END

MAN_BEGIN ("Sound: Get energy...", "ppgb", 19991016)
INTRO ("A @query to the selected @Sound object.")
ENTRY ("Return value")
NORMAL ("the energy. If the unit of sound amplitude is Pa (Pascal), the unit of energy will be Pa^2\\.cs.")
ENTRY ("Arguments")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the selected time domain. Values outside this domain are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the sound is considered.")
ENTRY ("Algorithm")
NORMAL ("The energy is defined as")
FORMULA ("\\in%dt %x^2(%t)")
NORMAL ("where %x(%t) is the amplitude of the sound. For our discrete Sound object, "
	"the energy is computed as")
FORMULA ("\\De%t \\su__%i=1..%n_ %x__%i_^2")
NORMAL ("where \\De%t is the sampling period and %n is the number of samples.")
ENTRY ("See also")
NORMAL ("For an interpretation of the energy as the sound energy in air, see @@Sound: Get energy in air@. "
	"For the power, see @@Sound: Get power...@.")
MAN_END

MAN_BEGIN ("Sound: Get energy in air", "ppgb", 19991016)
INTRO ("A @query to the selected @Sound object.")
ENTRY ("Return value")
NORMAL ("The energy in air, expressed in Joule/m^2.")
ENTRY ("Algorithm")
NORMAL ("The energy of a sound in air is defined as")
FORMULA ("1 / (%\\roc) \\in%dt %x^2(%t)")
NORMAL ("where %x(%t) is the sound pressure in units of Pa (Pascal), %\\ro is the air density "
	"(apx. 1.14 kg/m^3), and %c is the velocity of sound in air (apx. 353 m/s). For our discrete Sound object, "
	"the energy is computed as")
FORMULA ("\\De%t / (%\\roc)  \\su__%i=1..%n_ %x__%i_^2")
NORMAL ("where \\De%t is the sampling period and %n is the number of samples.")
ENTRY ("See also")
NORMAL ("For an air-independent interpretation of the energy, see @@Sound: Get energy...@. "
	"For the power, see @@Sound: Get power in air@.")
MAN_END

MAN_BEGIN ("Sound: Get index from time...", "ppgb", 19991016)
INTRO ("A @query to the selected @Sound object.")
ENTRY ("Return value")
NORMAL ("the sample index belonging to a specified time. The result is presented as a real number.")
ENTRY ("Example")
NORMAL ("If the sound has a sample rate of 10 kHz, the index associated with a time of 0.1 seconds "
	"will usually be 1000.5.")
ENTRY ("Scripting")
NORMAL ("You can use this command to put the nearest sample index into a script variable:")
CODE ("select Sound hallo")
CODE ("index = Get index from time... 0.1")
CODE ("nearestSample = round (index)")
NORMAL ("In this case, the value will not be written into the Info window. To round down or up, use")
CODE ("leftSample = floor (index)")
CODE ("rightSample = ceiling (index)")
MAN_END

MAN_BEGIN ("Sound: Get intensity (dB)", "ppgb", 19991016)
INTRO ("A @query to the selected @Sound object.")
ENTRY ("Return value")
NORMAL ("the intensity in air, expressed in dB relative to the auditory threshold.")
ENTRY ("Algorithm")
NORMAL ("The intensity of a sound in air is defined as")
FORMULA ("10 log__10_ ( 1 / (%T %P__0_^2) \\in%dt %x^2(%t) )")
NORMAL ("where %x(%t) is the sound pressure in units of Pa (Pascal), %T is the duration of the sound, "
	"and %P__0_ = 2\\.c10^^-5^ Pa is the auditory threshold pressure. "
	"For our discrete Sound object, the intensity is computed as")
FORMULA ("10 log__10_ ( 1 / (%n %P__0_^2)  \\su__%i=1..%n_ %x__%i_^2 )")
NORMAL ("where %n is the number of samples.")
ENTRY ("See also")
NORMAL ("For the intensity in Watt/m^2, see @@Sound: Get power in air@. For an auditory intensity, "
	"see @@Excitation: Get loudness@.")
MAN_END

MAN_BEGIN ("Sound: Get maximum...", "ppgb", 20030916)
INTRO ("A @query to the selected @Sound object.")
ENTRY ("Return value")
NORMAL ("the maximum amplitude (sound pressure in Pascal) within a specified time window.")
ENTRY ("Arguments")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the time window. Values outside this window are ignored, except for purposes of interpolation. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the sound is considered.")
TAG ("%%Interpolation")
DEFINITION ("the interpolation method (None, Parabolic, Cubic, Sinc) of the @@vector peak interpolation@. "
	"The standard is Sinc70 because a Sound object is normally a sampled band-limited signal, "
	"which can be seen as a sum of sinc functions.")
MAN_END

MAN_BEGIN ("Sound: Get mean...", "ppgb", 19991016)
INTRO ("A @query to the selected @Sound object.")
ENTRY ("Return value")
NORMAL ("the mean amplitude (sound pressure in Pascal) within a specified time window.")
ENTRY ("Arguments")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the time window. Values outside this window are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the sound is considered.")
ENTRY ("Algorithm")
NORMAL ("The mean amplitude between the times %t__1_ and %t__2_ is defined as")
FORMULA ("1/(%t__2_ - %t__1_)  \\in__%%t%1_^^%%t%2 %dt %x(%t)")
NORMAL ("where %x(%t) is the amplitude of the sound. "
	"For our discrete Sound object, this mean is approximated by")
FORMULA ("1/%n \\su__%i=%m..%m+%n-1_ %x__%i_")
NORMAL ("where %n is the number of sample centres between %t__1_ and %t__2_.")
MAN_END

MAN_BEGIN ("Sound: Get minimum...", "ppgb", 20030916)
INTRO ("A @query to the selected @Sound object.")
ENTRY ("Return value")
NORMAL ("the minimum amplitude (sound pressure in Pascal) within a specified time window.")
ENTRY ("Arguments")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the time window. Values outside this window are ignored, except for purposes of interpolation. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the sound is considered.")
TAG ("%%Interpolation")
DEFINITION ("the interpolation method (None, Parabolic, Cubic, Sinc) of the @@vector peak interpolation@. "
	"The standard is Sinc70 because a Sound object is normally a sampled band-limited signal, "
	"which can be seen as a sum of sinc functions.")
MAN_END

MAN_BEGIN ("Sound: Get nearest zero crossing...", "ppgb", 20021212)
INTRO ("A @query to the selected @Sound object.")
ENTRY ("Return value")
NORMAL ("the time associated with the zero crossing nearest to a specified time. "
	"It is @undefined if there are no zero crossings or if the specified time is outside the time domain of the sound. "
	"Linear interpolation is used between sample points.")
ENTRY ("Argument")
TAG ("%Time (s)")
DEFINITION ("the time for which you want to get the time of the nearest zero crossing.")
MAN_END

MAN_BEGIN ("Sound: Get number of samples", "ppgb", 19991016)
INTRO ("A @query to the selected @Sound object.")
ENTRY ("Return value")
NORMAL ("the sample count.")
MAN_END

MAN_BEGIN ("Sound: Get power...", "ppgb", 19991016)
INTRO ("A @query to the selected @Sound object.")
ENTRY ("Return value")
NORMAL ("the power within a specified time window. If the unit of sound amplitude is Pa (Pascal), "
	"the unit of power will be Pa^2.")
ENTRY ("Arguments")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the time window. Values outside this window are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the sound is considered.")
ENTRY ("Algorithm")
NORMAL ("The power is defined as")
FORMULA ("1/%T  \\in%dt %x^2(%t)")
NORMAL ("where %x(%t) is the amplitude of the sound, and %T its duration. For our discrete Sound object, "
	"the power is computed as")
FORMULA ("1/%n \\su__%i=1..%n_ %x__%i_^2")
NORMAL ("where %n is the number of samples.")
ENTRY ("See also")
NORMAL ("For an interpretation of the power as the sound power in air, see @@Sound: Get power in air@. "
	"For the total energy, see @@Sound: Get energy...@.")
MAN_END

MAN_BEGIN ("Sound: Get power in air", "ppgb", 19991016)
INTRO ("A @query to the selected @Sound object.")
ENTRY ("Return value")
NORMAL ("the power in air, expressed in Watt/m^2.")
ENTRY ("Algorithm")
NORMAL ("The power of a sound in air is defined as")
FORMULA ("1 / (%\\rocT) \\in%dt %x^2(%t)")
NORMAL ("where %x(%t) is the sound pressure in units of Pa (Pascal), %\\ro is the air density "
	"(apx. 1.14 kg/m^3), %c is the velocity of sound in air (apx. 353 m/s), and %T is the duration of the sound. "
	"For our discrete Sound object, the power is computed as")
FORMULA ("1 / (%\\rocn)  \\su__%i=1..%n_ %x__%i_^2")
NORMAL ("where %n is the number of samples.")
NORMAL ("For an air-independent interpretation of the power, see @@Sound: Get power...@. "
	"For the energy, see @@Sound: Get energy in air@. For the intensity in dB, "
	"see @@Sound: Get intensity (dB)@.")
MAN_END

MAN_BEGIN ("Sound: Get root-mean-square...", "ppgb", 19991016)
INTRO ("A @query to the selected @Sound object.")
ENTRY ("Return value")
NORMAL ("the root-mean-square (rms) value of the sound pressure, expressed in Pascal.")
ENTRY ("Arguments")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the time window. Values outside this domain are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the sound is considered.")
ENTRY ("Algorithm")
NORMAL ("The root-mean-square value is defined as")
FORMULA ("\\Vr( 1/%T  \\in%dt %x^2(%t) )")
NORMAL ("where %x(%t) is the amplitude of the sound, and %T its duration. For our discrete Sound object, "
	"the rms value is computed as")
FORMULA ("\\Vr( 1/%n \\su__%i=1..%n_ %x__%i_^2 )")
NORMAL ("where %n is the number of samples.")
MAN_END

MAN_BEGIN ("Sound: Get sample period", "ppgb", 19991016)
INTRO ("A @query to the selected @Sound object.")
ENTRY ("Return value")
NORMAL ("the sample period (%dx attribute), in seconds.")
MAN_END

MAN_BEGIN ("Sound: Get sample rate", "ppgb", 19991016)
INTRO ("A @query to the selected @Sound object.")
ENTRY ("Return value")
NORMAL ("the sample rate in Hertz.")
ENTRY ("Algorithm")
NORMAL ("The sample rate is defined as 1 / (\\De%t), where \\De%t is the sample period. "
	"See @@Sound: Get sample period@.")
MAN_END

MAN_BEGIN ("Sound: Get standard deviation...", "ppgb", 19991016)
INTRO ("A @query to the selected @Sound object.")
ENTRY ("Return value")
NORMAL ("the standard deviation (in Pascal) of the sound pressure within a specified window. "
	"If the sound contains less than 2 samples, the value is @undefined.")
ENTRY ("Arguments")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the selected time domain. Values outside this domain are ignored. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the sound is considered.")
ENTRY ("Algorithm")
NORMAL ("The standard deviation is defined as")
FORMULA ("1/(%t__2_ - %t__1_)  \\in%__%%t%1_^^%%t%2^ %dt (%x(%t) - %\\mu)^2")
NORMAL ("where %x(%t) is the amplitude of the sound, %T its duration, and %\\mu its mean. "
	"For our discrete Sound object, the standard deviation is approximated by")
FORMULA ("1/(%n-1) \\su__%i=%m..%m+%n-1_ (%x__%i_ - %\\mu)^2")
NORMAL ("where %n is the number of sample centres between %t__1_ and %t__2_. Note the \"minus 1\".")
MAN_END

MAN_BEGIN ("Sound: Get time from index...", "ppgb", 19991016)
INTRO ("A @query to the selected @Sound object.")
ENTRY ("Return value")
NORMAL ("the time (in seconds) associated with a specified sample index.")
ENTRY ("Argument")
TAG ("%%Sample index")
DEFINITION ("the sample index whose time is sought.")
ENTRY ("Algorithm")
NORMAL ("the result is")
FORMULA ("%t__1_ + (%index - 1) \\.c \\De%t")
NORMAL ("where %t__1_ is the time associated with the first sample (i.e., the %x1 attribute), "
	"and \\De%t is the sample period (the %dx attribute of the Sound object).")
MAN_END

MAN_BEGIN ("Sound: Get time of maximum...", "ppgb", 20030916)
INTRO ("A @query to the selected @Sound object.")
ENTRY ("Behaviour")
NORMAL ("the time (in seconds) associated with the maximum amplitude.")
ENTRY ("Arguments")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the selected time domain. Values outside this domain are ignored, except for interpolation. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the sound is considered.")
TAG ("%%Interpolation")
DEFINITION ("the interpolation method (None, Parabolic, Cubic, Sinc) of the @@vector peak interpolation@. "
	"The standard is Sinc70 because a Sound object is normally a sampled band-limited signal, "
	"which can be seen as a sum of sinc functions.")
MAN_END

MAN_BEGIN ("Sound: Get time of minimum...", "ppgb", 20030916)
INTRO ("A @query to the selected @Sound object.")
ENTRY ("Behaviour")
NORMAL ("the time (in seconds) associated with the minimum amplitude.")
ENTRY ("Arguments")
TAG ("%%From time% (s), %%To time% (s)")
DEFINITION ("the selected time domain. Values outside this domain are ignored, except for interpolation. "
	"If %%To time% is not greater than %%From time%, the entire time domain of the sound is considered.")
TAG ("%%Interpolation")
DEFINITION ("the interpolation method (None, Parabolic, Cubic, Sinc) of the @@vector peak interpolation@. "
	"The standard is Sinc70 because a Sound object is normally a sampled band-limited signal, "
	"which can be seen as a sum of sinc functions.")
MAN_END

MAN_BEGIN ("Sound: Get value at index...", "ppgb", 19991016)
INTRO ("A @query to the selected @Sound object.")
ENTRY ("Behaviour")
NORMAL ("the amplitude (sound pressure in Pascal) at a specified sample index. "
	"If the index is less than 1 or greater than the number of samples, the result is @undefined; "
	"otherwise, it is %z [1] [%index].")
ENTRY ("Argument")
TAG ("%%Sample index")
DEFINITION ("the sample index at which the value is to be evaluated.")
MAN_END

MAN_BEGIN ("Sound: Get value at time...", "ppgb", 20030916)
INTRO ("A @query to the selected @Sound object.")
ENTRY ("Return value")
NORMAL ("an estimate of the amplitude (sound pressure in Pascal) at a specified time. "
	"If that time is outside the samples of the Sound, the result is equal to the value of the nearest sample; "
	"otherwise, the result is an interpolated value.")
ENTRY ("Arguments")
TAG ("%Time (s)")
DEFINITION ("the time at which the value is to be evaluated.")
TAG ("%%Interpolation")
DEFINITION ("the interpolation method, see @@vector value interpolation@. "
	"The standard is Sinc70 because a Sound object is normally a sampled band-limited signal, "
	"which can be seen as a sum of sinc functions.")
MAN_END

MAN_BEGIN ("Sound: Lengthen (PSOLA)...", "ppgb", 20030916)
INTRO ("A command to convert each selected @Sound object into a longer new @Sound object.")
ENTRY ("Arguments")
TAG ("%%Minimum frequency% (Hz)")
DEFINITION ("the minimum pitch used in the periodicity analysis. The standard value is 75 Hz. For the voice of a young child, set this to 150 Hz."
	"The shortest voiceless interval in the PSOLA decomposition is taken as "
	"1.5 divided by %%minimum frequency%.")
TAG ("%%Maximum frequency% (Hz)")
DEFINITION ("the maximum pitch used in the periodicity analysis. The standard value is 600 Hz. For an adult male voice, set this to 300 Hz.")
TAG ("%Factor")
DEFINITION ("the factor with which the sound will be lengthened. The standard value is 1.5. If you take a value less than 1, "
	"the resulting sound will be shorter than the original. A value larger than 3 will not work.")
ENTRY ("Algorithm")
NORMAL ("Pitch-synchronous overlap-and-add.")
MAN_END

MAN_BEGIN ("Sound: Play", "ppgb", 19960911)
INTRO ("A command to play @Sound objects.")
ENTRY ("Availability")
NORMAL ("You can choose this command after selecting one or more Sounds.")
ENTRY ("Purpose")
NORMAL ("To play the selected Sounds through the internal or external loudspeakers, "
	"the headphones, or the analog or digital outputs of your computer.")
ENTRY ("Behaviour")
NORMAL ("All of the Sounds selected are played, "
	"in the order in which they appear in the list. If the sample rate of the Sound does not match any of "
	"the system's sample rates, a fast but inaccurate conversion is performed via linear interpolation.")
ENTRY ("Usage")
NORMAL ("The choice of the output device(s) depends on the settings in your Audio Control Panel "
	"or (on HP) the setting of the ##Use internal loudspeaker...# preference (in the `Control' menu.")
MAN_END

MAN_BEGIN ("Sound: Filter (pre-emphasis)...", "ppgb", 20030309)
INTRO ("A command to filter each selected @Sound object. The resulting Sound object has a higher spectral slope.")
NORMAL ("The reverse of @@Sound: Filter (de-emphasis)...@.")
ENTRY ("Argument")
TAG ("%%From frequency% (Hz)")
DEFINITION ("the frequency %F above which the spectral slope will increase by 6 dB/octave.")
ENTRY ("Algorithm")
NORMAL ("The pre-emphasis factor %\\al is computed as")
FORMULA ("%\\al = exp (-2 %\\pi %F \\De%t)")
NORMAL ("where \\De%t is the sampling period of the sound. The new sound %y is then computed as:")
FORMULA ("%y__%i_ = %x__%i_ - %\\al %x__%i-1_")
MAN_END

MAN_BEGIN ("Sound: Pre-emphasize (in-line)...", "ppgb", 20030309)
INTRO ("A command to change the spectral slope of every selected @Sound object.")
NORMAL ("The reverse of @@Sound: De-emphasize (in-line)...@.")
NORMAL ("This is the in-line version of @@Sound: Filter (pre-emphasis)...@, "
	"i.e., it does not create a new Sound object but modifies an existing object.")
ENTRY ("Algorithm")
NORMAL ("The pre-emphasis factor %\\al is computed as")
FORMULA ("%\\al = exp (-2 %\\pi %F \\De%t)")
NORMAL ("where \\De%t is the sampling period of the sound. Every sample %x__%i_ of the sound, "
	"except %x__1_, is then changed, going down from the last sample:")
FORMULA ("%x__%i_ = %x__%i_ - %\\al %x__%i-1_")
MAN_END

MAN_BEGIN ("Sound: Resample...", "ppgb", 20030916)
INTRO ("A command that creates new @Sound objects from the selected Sounds.")
ENTRY ("Purpose")
NORMAL ("High-precision resampling from any sample rate to any other sample rate.")
ENTRY ("Arguments")
TAG ("%%Sampling frequency")
DEFINITION ("the new sampling frequency, in Hertz.")
TAG ("%Precision")
DEFINITION ("the depth of the interpolation, in samples (standard is 50). "
	"This determines the quality of the interpolation used in resampling.")
ENTRY ("Algorithm")
NORMAL ("If %Precision is 1, the method is linear interpolation, which is inaccurate but fast.")
/* BUG */
NORMAL ("If %Precision is greater than 1, the method is sin(%x)/%x (\"%sinc\") interpolation, "
	"with a depth equal to %Precision. "
	"For higher %Precision, the algorithm is slower but more accurate.")
NORMAL ("If %%Sampling frequency% is less than the sampling frequency of the selected sound, "
	"an anti-aliasing low-pass filtering is performed prior to resampling.")
ENTRY ("Behaviour")
NORMAL ("A new Sound will appear in the list of objects, "
	"bearing the same name as the original Sound, followed by the sampling frequency. "
	"For instance, the Sound \"hallo\" will give a new Sound \"hallo_10000\".")
MAN_END

MAN_BEGIN ("Sound: Set value at index...", "ppgb", 20000210)
INTRO ("A command to change a specified sample of the selected @Sound object.")
ENTRY ("Arguments")
TAG ("%%Sample index")
DEFINITION ("the sample whose value is to be changed. Specify any value between 1 and the number of samples in the Sound. "
	"If you specify a value outside that range, you will get an error message.")
TAG ("%%New value")
DEFINITION ("the value that is to be put into the specified sample.")
ENTRY ("Scripting")
NORMAL ("Example:")
CODE ("select Sound hallo")
CODE ("Set value at index... 100 1/2")
NORMAL ("This sets the value of the 100th sample to 0.5.")
MAN_END

MAN_BEGIN ("Sound: To Formant (burg)...", "ppgb", 20031003)
INTRO ("A command that creates a @Formant object from every selected @Sound object. "
	"It performs a short-term spectral analysis, approximating the spectrum of each "
	"analysis frame by a number of formants.")
ENTRY ("Arguments")
TAG ("%%Time step% (seconds)")
DEFINITION ("the time between the centres of consecutive analysis frames. If the sound is 2 seconds long, "
	"and the time step is 0.01 seconds, there will be approximately 200 analysis frames. "
	"The actual number is somewhat lower (usually 195), because we cannot measure very well "
	"near the edges. If you set the time step to 0.0 (the standard), Praat will use a time step "
	"that is equal to 25 percent of the analysis window length (see below).")
TAG ("%%Maximum number of formants%")
DEFINITION ("for most analyses of human speech, you will want to extract 5 formants per frame. "
	"This, in combination with the %%Maximum formant% argument, is the only way "
	"in which this procedure will give you results compatible with how people "
	"tend to interpret formants for vowels, i.e. in terms of "
	"vowel height (F1) and vowel place (F2).")
TAG ("%%Maximum formant% (Hertz)")
DEFINITION ("the ceiling of the formant search range. It is crucial that you set this argument to a value suitable for your speaker. "
	"The standard value of 5500 Hz is suitable for an average adult female. For a male, use 5000 Hz; "
	"if you use 5500 Hz for an adult male, you may end up with too few formants in the low frequency region, "
	"e.g. analysing an [u] as having a single formant near 500 Hz whereas you want two formants at 300 and 600 Hz. "
	"For a young child, use a value much higher than 5500 Hz, for instance 8000 Hz (experiment with it on steady vowels).")
TAG ("%%Window length% (seconds)")
DEFINITION ("the effective duration of the analysis window. The actual length is twice this value, "
	"because Praat uses a Gaussian-like analysis window with sidelobes below -120 dB. "
	"For instance, if the %%Window length% is 0.025 seconds, the actual Gaussian window duration "
	"is 0.050 seconds. This window has values below 4\\%  outside the central 0.025 seconds, "
	"and its frequency resolution (-3 dB point) is 1.298 / (0.025 s) = 51.9 Hz, as computed "
	"with the formula given at @@Sound: To Spectrogram...@. This is comparable to the bandwidth "
	"of a Hamming window of 0.025 seconds, which is 1.303 / (0.025 s) = 52.1 Hz, "
	"but that window (which is the window most often used in other analysis programs) "
	"has three spectral lobes of about -42 dB on each side.")
TAG ("%%Pre-emphasis from% (Hertz)")
DEFINITION ("the +3 dB point for an inverted low-pass filter with a slope of +6 dB/octave. "
	"If this value is 50 Hz, then frequencies below 50 Hz are not enhanced, "
	"frequencies around 100 Hz are amplified by 6 dB, frequencies around 200 Hz are amplified by 12 dB, "
	"and so forth. The point of this is that vowel spectra tend to fall by 6 dB per octave; "
	"the pre-emphasis creates a flatter spectrum, which is better for formant analysis "
	"because we want our formants to match the local peaks, not the global spectral slope. "
	"See the @@source-filter synthesis@ tutorial for a technical explanation, "
	"and @@Sound: Pre-emphasize (in-line)...@ for the algorithm.")
ENTRY ("Algorithm")
NORMAL ("The sound will be resampled to a sample rate of twice the value of %%Maximum formant%, "
	"with the algorithm described at @@Sound: Resample...@. "
	"After this, pre-emphasis is applied with the algorithm described at @@Sound: Pre-emphasize (in-line)...@. "
	"For each analysis window, Praat applies a Gaussian-like window, "
	"and computes the LPC coefficients with the algorithm by Burg, as given by @@Childers (1978)@ "
	"and @@Press et al. (1992)@.")
NORMAL ("This algorithm can initially find formants at very low or high frequencies. "
	"In order for you to be able to identify the traditional F1 and F2, "
	"all formants below 50 Hz and all formants above %%Maximum formant% minus 50 Hz, "
	"are removed. If you don't want this, you may experiment with @@Sound: To Formant (keep all)...@ instead. "
	"If you prefer an algorithm that always yields the requested number of formants, nicely distributed "
	"across the frequency domain, you may try the otherwise rather unreliable Split-Levinson procedure @@Sound: To Formant (sl)...@.")
MAN_END

MAN_BEGIN ("Sound: To Formant (keep all)...", "ppgb", 20000210)
INTRO ("A command that creates a @Formant object from every selected @Sound object. Not recommended for general use.")
ENTRY ("Purpose")
NORMAL ("to perform a short-term spectral analysis, approximating the spectrum of each frame by a number of formants.")
ENTRY ("Arguments")
NORMAL ("The same as with @@Sound: To Formant (burg)...@.")
ENTRY ("Algorithm")
NORMAL ("The same as with @@Sound: To Formant (burg)...@. In contrast with that command, "
	"however, all formant values are kept, even those below 50 Hz and those above %%Maximum formant% minus 50 Hz. "
	"Although this makes the identification of the traditional F1 and F2 more difficult, "
	"this might give better results in resynthesis (see @@Sound & Formant: Filter@), but it usually generates funny values instead.")
MAN_END

MAN_BEGIN ("Sound: To Formant (sl)...", "ppgb", 20021215)
INTRO ("A command that creates a @Formant object from every selected @Sound object. Not recommended for general use.")
ENTRY ("Purpose")
NORMAL ("to perform a short-term spectral analysis, approximating the spectrum of each frame by a number of formants.")
ENTRY ("Arguments")
NORMAL ("The same as with @@Sound: To Formant (burg)...@.")
ENTRY ("Algorithm")
NORMAL ("The algorithm is based on the implementation of the `Split Levinson' algorithm by @@Willems (1986)@. "
	"This algorithm will always find the requested number of formants in every frame, even if they do not exist. "
	"The standard routine (@@Sound: To Formant (burg)...@) yields much more reliable formant values, though it is more sensitive "
	"to the %%Maximum formant% argument.")
NORMAL ("Because of the general funny behaviour of the Split-Levinson algorithm, we did not bother to implement an analysis "
	"of the bandwidths. They are all set arbitrarily to 50 Hz.")
MAN_END

MAN_BEGIN ("Sound: To Harmonicity (ac)...", "ppgb", 20030916)
INTRO ("A command that creates a @Harmonicity object from every selected @Sound object.")
ENTRY ("Purpose")
NORMAL ("to perform a short-term HNR analysis.")
ENTRY ("Algorithm")
NORMAL ("The algorithm performs an acoustic periodicity detection on the basis of an "
	"accurate autocorrelation method, as described in @@Boersma (1993)@.")
ENTRY ("Arguments")
TAG ("%%Time step% (standard value: 0.01 s)")
DEFINITION ("the measurement interval (frame duration), in seconds.")
TAG ("%%Minimum pitch% (standard value: 75 Hz)")
DEFINITION ("determines the length of the analysis window.")
TAG ("%%Silence threshold% (standard value: 0.1)")
DEFINITION ("frames that do not contain amplitudes above this threshold (relative to the global maximum amplitude), "
	"are considered silent.")
TAG ("%%Number of periods per window% (standard value: 4.5)")
DEFINITION ("4.5 is best for speech: "
	"HNR values up to 37 dB are guaranteed to be detected reliably; "
	"6 periods per window raises this figure to more than 60 dB, "
	"but the algorithm becomes more sensitive to dynamic changes in the signal.")
ENTRY ("Usage")
NORMAL ("You will normally use @@Sound: To Harmonicity (cc)...@ instead of this command, "
	"because that has a much better time resolution (though its sensitivity is 60, not 80 dB).")
MAN_END

MAN_BEGIN ("Sound: To Harmonicity (cc)...", "ppgb", 19961003)
INTRO ("A command that creates a @Harmonicity object from every selected @Sound object.")
ENTRY ("Purpose")
NORMAL ("to perform a short-term HNR analysis.")
ENTRY ("Algorithm")
NORMAL ("The algorithm performs an acoustic periodicity detection on the basis of a "
	"forward cross-correlation analysis. "
	"For information on the arguments, see @@Sound: To Harmonicity (ac)...@.")
MAN_END

MAN_BEGIN ("Sound: To Intensity...", "ppgb", 20030822)
INTRO ("A command to create an @Intensity object from every selected @Sound.")
ENTRY ("Arguments")
TAG ("%%Minimum pitch% (Hz)")
DEFINITION ("specifies the minimum periodicity frequency in your signal. If you set %%Minimum pitch% too high, "
	"you will end up with a pitch-synchronous intensity modulation. If you set it too low, "
	"your intensity contour may appear smeared, so you should set it as high as allowed by the signal "
	"if you want a sharp contour.")
TAG ("%%Time step% (s)")
DEFINITION ("the frame length of the resulting intensity contour. If you set it to zero, the time step is computed as "
	"one quarter of the effective window length, i.e. as 0.8 / (%%Minimum pitch%)")
ENTRY ("Algorithm")
NORMAL ("The values in the sound are squared and convolved with a Kaiser-20 window (sidelobes below -190 dB). "
	"The effective length of this window is 3.2 / (%%Minimum pitch%), which will guarantee that a periodic signal is analysed with a "
	"pitch-synchronous intensity ripple not greater than our 4-byte floating-point precision (i.e., < 0.00001 dB).")
MAN_END

MAN_BEGIN ("Sound: To Pitch...", "ppgb", 20030916)
INTRO ("A command that creates a @Pitch object from every selected @Sound object.")
ENTRY ("Purpose")
NORMAL ("to perform a pitch analysis, optimized for speech.")
ENTRY ("Arguments")
NORMAL ("The arguments that control the recruitment of the candidates are:")
TAG ("%%Time step% (standard value: 0.0)")
DEFINITION ("the measurement interval (frame duration), in seconds. If you supply 0, "
	"P\\s{RAAT} will use a time step of 0.75 / (%%pitch floor%), e.g. 0.01 seconds if the pitch floor is 75 Hz; "
	"in this example, P\\s{RAAT} computes 100 pitch values per second.")
TAG ("%%Pitch floor% (standard value: 75 Hz)")
DEFINITION ("candidates below this frequency will not be recruited. "
	"This parameter determines the length of the analysis window: it will be 3 longest periods long, "
	"i.e., if the pitch floor is 75 Hz, the window will be 3/75 = 0.04 seconds long.")
NORMAL ("Note that if you set the time step to zero, the analysis windows for consecutive measurements "
	"will overlap appreciably: P\\s{RAAT} will always compute 4 pitch values "
	"within one window length, i.e., the degree of %oversampling is 4.")
NORMAL ("A post-processing algorithm seeks the cheapest path through the candidates. "
	"The argument that determines the cheapest path is:")
TAG ("%%Pitch ceiling% (standard value: 600 Hz)")
DEFINITION ("candidates above this frequency will be ignored.")
ENTRY ("Algorithm")
NORMAL ("This is the algorithm described at @@Sound: To Pitch (ac)...@, "
	"with all the parameters not mentioned above set to their standard values.")
MAN_END

MAN_BEGIN ("Sound: To Pitch (ac)...", "ppgb", 20030916)
INTRO ("A command that creates a @Pitch object from every selected @Sound object.")
ENTRY ("Purpose")
NORMAL ("to perform a pitch analysis based on an autocorrelation method.")
ENTRY ("Usage")
NORMAL ("Normally, you will instead use @@Sound: To Pitch...@, which uses the same method. "
	"The command described here is mainly for experimenting with the parameters, "
	"or for the analysis of non-speech signals, which may require different "
	"standard settings of the parameters.")
ENTRY ("Algorithm")
NORMAL ("The algorithm performs an acoustic periodicity detection on the basis of an "
	"accurate autocorrelation method, as described in @@Boersma (1993)@. "
	"This method is more accurate, noise-resistant, and robust, than methods based on cepstrum or combs, "
	"or the original autocorrelation methods. The reason why other methods were invented, "
	"was the failure to recognize the fact that if you want to estimate a signal's short-term autocorrelation "
	"function on the basis of a windowed signal, you should divide the autocorrelation function of the "
	"windowed signal by the autocorrelation function of the window:")
NORMAL ("%r__%x_ (%\\ta) \\~~ %r__%xw_ (%\\ta) / %r__%w_ (%\\ta)")
ENTRY ("Arguments")
NORMAL ("The arguments that control the recruitment of the candidates are:")
TAG ("%%Time step% (standard value: 0.0)")
DEFINITION ("the measurement interval (frame duration), in seconds. If you supply 0, "
	"P\\s{RAAT} will use a time step of 0.75 / (%%pitch floor%), e.g. 0.01 seconds if the pitch floor is 75 Hz; "
	"in this example, P\\s{RAAT} computes 100 pitch values per second.")
TAG ("%%Pitch floor% (standard value: 75 Hz)")
DEFINITION ("candidates below this frequency will not be recruited. "
	"This parameter determines the effective length of the analysis window: it will be 3 longest periods long, "
	"i.e., if the pitch floor is 75 Hz, the window will be effectively 3/75 = 0.04 seconds long.")
NORMAL ("Note that if you set the time step to zero, the analysis windows for consecutive measurements "
	"will overlap appreciably: P\\s{RAAT} will always compute 4 pitch values "
	"within one window length, i.e., the degree of %oversampling is 4.")
TAG ("%%Very accurate% (standard value: %off)")
DEFINITION ("if %off, the window is a Hanning window with a physical length of  3 / (%%pitch floor%). "
	"If %on, the window is a Gaussian window with a physical length of  6 / (%%pitch floor%), "
	"i.e. twice the effective length.")
NORMAL ("A post-processing algorithm seeks the cheapest path through the candidates. "
	"The arguments that determine the cheapest path are:")
TAG ("%%Pitch ceiling% (standard value: 600 Hz)")
DEFINITION ("candidates above this frequency will be ignored.")
TAG ("%%Silence threshold% (standard value: 0.03)")
DEFINITION ("frames that do not contain amplitudes above this threshold (relative to the global maximum amplitude), "
	"are probably silent.")
TAG ("%%Voicing threshold% (standard value: 0.45)")
DEFINITION ("the strength of the unvoiced candidate, relative to the maximum possible autocorrelation. "
	"To increase the number of unvoiced decisions, increase this value.")
TAG ("%%Octave cost% (standard value: 0.01 per octave)")
DEFINITION ("degree of favouring of high-frequency candidates, relative to the maximum possible autocorrelation. "
	"This is necessary because even (or: especially) in the case of a perfectly periodic signal, "
	"all undertones of %F__0_ are equally strong candidates as %F__0_ itself. "
	"To more strongly favour recruitment of high-frequency candidates, increase this value.")
TAG ("%%Octave-jump cost% (standard value: 0.35)")
DEFINITION ("degree of disfavouring of pitch changes, relative to the maximum possible autocorrelation. "
	"To decrease the number of large frequency jumps, increase this value. In contrast with what is described "
	"in the article, this value will be corrected for the time step: multiply by 0.01 s / %TimeStep to get "
	"the value in the way it is used in the formulas in the article.")
TAG ("%%Voiced / unvoiced cost% (standard value: 0.14)")
DEFINITION ("degree of disfavouring of voiced/unvoiced transitions, relative to the maximum possible autocorrelation. "
	"To decrease the number of voiced/unvoiced transitions, increase this value. In contrast with what is described "
	"in the article, this value will be corrected for the time step: multiply by 0.01 s / %TimeStep to get "
	"the value in the way it is used in the formulas in the article.")
MAN_END

MAN_BEGIN ("Sound: To Pitch (cc)...", "ppgb", 20030916)
INTRO ("A command that creates a @Pitch object from every selected @Sound object.")
ENTRY ("Purpose")
NORMAL ("to perform a pitch analysis based on a cross-correlation method.")
ENTRY ("Algorithm")
NORMAL ("The algorithm performs an acoustic periodicity detection on the basis of a "
	"forward cross-correlation analysis.")
ENTRY ("Arguments")
TAG ("%%Time step% (standard value: 0.0)")
DEFINITION ("the measurement interval (frame duration), in seconds. If you supply 0, "
	"P\\s{RAAT} will use a time step of 0.25 / (%%pitch floor%), e.g. 0.00333333 seconds if the pitch floor is 75 Hz; "
	"in this example, P\\s{RAAT} computes 300 pitch values per second.")
TAG ("%%Pitch floor% (standard value: 75 Hz)")
DEFINITION ("candidates below this frequency will not be recruited. "
	"This parameter determines the length of the analysis window: it will be 1 longest period long, "
	"i.e., if the pitch floor is 75 Hz, the window will be 1/75 = 0.01333333 seconds long.")
NORMAL ("Note that if you set the time step to zero, the analysis windows for consecutive measurements "
	"will overlap appreciably: P\\s{RAAT} will always compute 4 pitch values "
	"within one window length, i.e., the degree of %oversampling is 4.")
NORMAL ("The other arguments are the same as for @@Sound: To Pitch (ac)...@.")
ENTRY ("Usage")
NORMAL ("The preferred method for speech is @@Sound: To Pitch...@. "
	"The command described here is mainly for experimenting, "
	"or for applications where you need short time windows.")
MAN_END

MAN_BEGIN ("Sound: To PointProcess (periodic, cc)...", "ppgb", 20030309)
INTRO ("A command that analyses the selected @Sound objects, and creates @PointProcess objects.")
NORMAL ("This command combines the actions of @@Sound: To Pitch (ac)...@ and @@Sound & Pitch: To PointProcess (cc)@.")
MAN_END

MAN_BEGIN ("Sound: To PointProcess (periodic, peaks)...", "ppgb", 20030309)
INTRO ("A command that analyses the selected @Sound objects, and creates @PointProcess objects.")
NORMAL ("This command combines the actions of @@Sound: To Pitch (ac)...@ and @@Sound & Pitch: To PointProcess (peaks)...@.")
MAN_END

MAN_BEGIN ("Sound: To Spectrogram...", "ppgb", 20030317)
INTRO ("A command that creates a @Spectrogram from every selected @Sound object. "
	"It performs a %%short-term spectral analysis%, which means that for a number of time points in the Sound, "
	"Praat computes an approximation of the spectrum at that time. Each such spectrum is called an %%analysis frame%.")
NORMAL ("For tutorial information, see @@Intro 3. Spectral analysis@.")
ENTRY ("Arguments")
TAG ("%%Window length")
DEFINITION ("the duration of the analysis window. If this is 0.005 seconds, Praat uses for each frame "
	"the part of the sound that lies between 0.0025 seconds before and 0.0025 seconds after the centre of that frame "
	"(for Gaussian windows, Praat actually uses a bit more than that). "
	"The window length determines the %bandwidth of the spectral analysis, i.e. the width of the horizontal line "
	"in the spectrogram of a pure sine wave. "
	"For a Gaussian window, the -3 dB bandwidth is 2*sqrt(6*ln(2))/(\\pi*%%Window length%), "
	"or 1.2982804 / %%Window length%. "
	"To get a `broad-band' spectrogram (bandwidth 260 Hz), set %%Window length% to 5 milliseconds; "
	"to get a `narrow-band' spectrogram (bandwidth 43 Hz), set it to 30 milliseconds. "
	"The other window shapes give slightly different values.")
TAG ("%%Maximum frequency")
DEFINITION ("the maximum frequency subject to analysis, e.g. 5000 Hertz. "
	"If it is higher than the Nyquist frequency of the Sound (which is half its sampling frequency), "
	"some values in the result will be zero (and will be drawn in white by @@Spectrogram: Paint...@).")
TAG ("%%Time step")
DEFINITION ("the distance between the centres of subsequent frames, e.g. 0.002 seconds. "
	"This determines the number of frames of the resulting Spectrogram. For instance, if the Sound is 1 second long, "
	"and the time step is 2 milliseconds, the Spectrogram will consist of almost 500 frames "
	"(not %exactly 500, because no reliable spectrum can be measured near the beginning and end of the sound). "
	"See below for cases in which the time step of the resulting Spectrogram is different from what you supply here.")
TAG ("%%Frequency step")
DEFINITION ("the frequency resolution, e.g. 20 Hertz. "
	"This determines the number of frequency bands (%bins) of the resulting Spectrogram. For instance, if the %%Maximum frequency% "
	"is 5000 Hz, and the frequency step is 20 Hz, the Spectrogram will consist of 250 frequency bands. "
	"See below for cases in which the frequency step of the resulting Spectrogram is different from what you supply here.")
TAG ("%%Window shape")
DEFINITION ("determines the shape of the analysis window. "
	"You can choose from: Gaussian, Square (none, rectangular), Hamming (raised sine-squared), "
	"Bartlett (triangular), Welch (parabolic), and Hanning (sine-squared). "
	"The Gaussian window is superior, as it gives no sidelobes in your spectrogram; "
	"it analyzes a factor of 2 slower than the other window shapes, "
	"because the analysis is actually performed on twice as many samples per frame.")
NORMAL ("For purposes of computation speed, Praat may decide to change the time step and the frequency step. "
	"This is because the time step never needs to be smaller than 1/(8\\Vr\\pi) of the window length, "
	"and the frequency step never needs to be smaller than (\\Vr\\pi)/8 of the inverse of the window length. "
	"For instance, if the window length is 29 ms, the actual time step will be never be less than 29/(8\\Vr\\pi) = 2.045 ms. "
	"And if the window length is 5 ms, the actual frequency step will never be less than (\\Vr\\pi)/8/0.005 = 44.32 Hz.")
ENTRY ("Tests of the bandwidth")
NORMAL ("You can check the bandwidth formula with the following procedure:")
CODE ("! create a 1000-Hz sine wave, windowed by a 0.2-seconds Gaussian window.")
CODE ("Create Sound... gauss 0 1 22050 sin(2*pi*1000*x) * exp(-3*((x-0.5)/0.1)\\^ 2)")
CODE ("! compute its spectrum and look at its bandwidth")
CODE ("To Spectrum (fft)")
CODE ("Draw... 980 1020 20 80 yes")
CODE ("Marks bottom every... 1 2 yes yes yes")
CODE ("Marks left every... 1 2 yes yes yes")
CODE ("! now you should see a peak at 1000 Hz with a 3 dB bandwidth of 7 Hz (20 dB: 17 Hz)")
CODE ("! more precise: compute the position and width of the peak, and write them to the console")
CODE ("Formula... if x<980 or x>1020 then 0 else self fi")
CODE ("To Formant (peaks)... 20")
CODE ("Write to console")
CODE ("! now you should be able to read that a peak was found at 999.99982 Hz")
CODE ("! with a bandwidth of 6.497 Hz; the theory above predicted 6.491 Hz")
CODE ("")
CODE ("! The same, windowed by a 0.1-seconds Hamming window.")
CODE ("Create Sound... Hamming 0 1 22050 if x<0.4 or x>0.6 then 0 else sin(2*pi*1000*x)*(0.54+0.46*cos(pi*(x-0.5)/0.1)) fi")
CODE ("To Spectrum (fft)")
CODE ("Formula... if x<970 or x>1030 then 0 else self fi")
CODE ("To Formant (peaks)... 20")
CODE ("Write to console")
CODE ("! peak at 999.99817 Hz, 3 dB bw 6.518 Hz, 20 dB bw 15 Hz, zero bw 20 Hz, sidelobe -42 dB")
CODE ("")
CODE ("! The same, windowed by a 0.1-seconds rectangular window.")
CODE ("Create Sound... rectangular 0 1 22050 if x<0.4 or x>0.6 then 0 else sin(2*pi*1000*x) fi")
CODE ("To Spectrum (fft)")
CODE ("Formula... if x<970 or x>1030 then 0 else self fi")
CODE ("To Formant (peaks)... 20")
CODE ("Write to console")
CODE ("! peak at 999.99506 Hz, 3 dB bw 4.440 Hz, 20 dB bw 27 Hz, zero bw 10 Hz, sidelobe -14 dB")
CODE ("")
CODE ("! The same, windowed by a 0.1-seconds Hanning window.")
CODE ("Create Sound... Hanning 0 1 22050 if x<0.4 or x>0.6 then 0 else sin(2*pi*1000*x)*(0.5+0.5*cos(pi*(x-0.5)/0.1)) fi")
CODE ("To Spectrum (fft)")
CODE ("Formula... if x<970 or x>1030 then 0 else self fi")
CODE ("To Formant (peaks)... 20")
CODE ("Write to console")
CODE ("! peak at 999.99945 Hz, 3 dB bw 7.212 Hz, 20 dB bw 16 Hz, zero bw 20 Hz, sidelobe -31 dB")
CODE ("")
CODE ("! The same, windowed by a 0.1-seconds triangular window.")
CODE ("Create Sound... triangular 0 1 22050 if x<0.4 or x>0.6 then 0 else sin(2*pi*1000*x)*(1-abs((x-0.5)/0.1)) fi")
CODE ("To Spectrum (fft)")
CODE ("Formula... if x<970 or x>1030 then 0 else self fi")
CODE ("To Formant (peaks)... 20")
CODE ("Write to console")
CODE ("! peak at 999.99933 Hz, 3 dB bw 6.384 Hz, 20 dB bw 15 Hz, zero bw 20 Hz, sidelobe -26 dB")
CODE ("")
CODE ("! The same, windowed by a 0.1-seconds parabolic window.")
CODE ("Create Sound... parabolic 0 1 22050 if x<0.4 or x>0.6 then 0 else sin(2*pi*1000*x)*(1-((x-0.5)/0.1)^2) fi")
CODE ("To Spectrum (fft)")
CODE ("Formula... if x<970 or x>1030 then 0 else self fi")
CODE ("To Formant (peaks)... 20")
CODE ("Write to console")
CODE ("! peak at 999.99921 Hz, 3 dB bw 5.786 Hz, 20 dB bw 12 Hz, zero bw 15 Hz, sidelobe -21 dB")
MAN_END

MAN_BEGIN ("Sound: To Spectrum (fft)", "ppgb", 20030910)
INTRO ("A command to create a @Spectrum object from every selected @Sound object, by an over-all spectral analysis.")
ENTRY ("Algorithm")
NORMAL ("The algorithm is the continuous interpretation of the @@Fast Fourier Transform@, with a negative exponent:")
FORMULA ("%X (%f) = __0_\\in^%T %x (%t) %e^^\\--2%%\\piift% %dt")
NORMAL ("where %T is the duration of the sound, and %t is taken relative to the time associated with the first sample.")
NORMAL ("If the Sound is expressed in Pascal (Pa), the Spectrum is expressed in Pa\\.cs, or Pa/Hz. "
	"The frequency integral over the Spectrum equals the time integral over the Sound.")
ENTRY ("Behaviour")
NORMAL ("If you perform @@Spectrum: To Sound (fft)@ on the resulting Spectrum object, "
	"a Sound is created that is equal to the original Sound.")
/*
Copy... square
Formula... self^2
To Spectrum (fft)
Formula... self * exp (- (x/50) ^ 2)
To Sound (fft)
Rename... smoothIntensity

the result is a smoothed version of your squared sound.
Perhaps divide the original by its square root:

select Sound square
Formula... self / sqrt (Sound_smoothIntensity [])
Play

> I also have a question about whether this would remove the contour or
> just normalize the loudness?

it removes the contour. I tested it. It works.
*/
MAN_END

MAN_BEGIN ("Sound: To TextGrid...", "ppgb", 19980730)
INTRO ("A command to create a @TextGrid without any labels, copying the time domain from the selected @Sound.")
ENTRY ("Arguments")
TAG ("%%Tier names")
DEFINITION ("a list of the names of the tiers that you want to create, separated by spaces.")
TAG ("%%Point tiers")
DEFINITION ("a list of the names of the tiers that you want to be %%point tiers%; "
	"the rest of the tiers will be %%interval tiers%.")
ENTRY ("Example")
NORMAL ("If %%Tier names% is \"a b c\", and \"Point tiers\" is \"b\", "
	"the resulting TextGrid object will contain an interval tier named \"a\", "
	"a point tier named \"b\", and another interval tier named \"c\".")
MAN_END

MAN_BEGIN ("Sound & Pitch: To PointProcess (cc)", "ppgb", 19980322)
INTRO ("A command to create a @PointProcess from the selected @Sound and @Pitch objects.")
ENTRY ("Purpose")
NORMAL ("to interpret an acoustic periodicity contour as the frequency of an underlying point process "
	"(such as the sequence of glottal closures in vocal-fold vibration).")
ENTRY ("Algorithm")
NORMAL ("The voiced intervals are determined on the basis of the voiced/unvoiced decisions in the @Pitch object. "
	"For every voiced interval, a number of %points (or glottal pulses) is found as follows:")
LIST_ITEM ("1. The first point %t__1_ is the absolute extremum of the amplitude of the #Sound, "
	"between %t__%mid_ \\-- %T__0_ / 2 and %t__%mid_ + %T__0_ / 2, where %t__%mid_ is the midpoint of the interval, "
	"and %T__0_ is the period at %t__%mid_, as can be interpolated from the #Pitch contour.")
LIST_ITEM ("2. From this point, we recursively search for points %t__%i_ to the left "
	"until we reach the left edge of the interval. These points must be located between "
	"%t__%i\\--1_ \\-- 1.2 %T__0_(%t__%i\\--1_) and %t__%i\\--1_ \\-- 0.8 %T__0_(%t__%i\\--1_), "
	"and the cross-correlation of the amplitude "
	"in its environment [%t__%i_ \\-- %T__0_(%t__%i_) / 2; %t__%i_ + %T__0_(%t__%i_) / 2] "
	"with the amplitude of the environment of the existing point %t__%i\\--1_ must be maximal "
	"(we use parabolic interpolation between samples of the correlation function).")
LIST_ITEM ("3. The same is done to the right of %t__1_.")
LIST_ITEM ("4. Though the voiced/unvoiced decision is initially taken by the #Pitch contour, "
	"points are removed if their correlation value is less than 0.3; "
	"furthermore, one extra point may be added at the edge of the voiced interval "
	"if its correlation value is greater than 0.7.")
MAN_END

MAN_BEGIN ("Sound & Pitch: To PointProcess (peaks)...", "ppgb", 20030309)
INTRO ("A command to create a @PointProcess from the selected @Sound and @Pitch objects.")
ENTRY ("Purpose")
NORMAL ("to interpret an acoustic periodicity contour as the frequency of an underlying point process "
	"(such as the sequence of glottal closures in vocal-fold vibration).")
ENTRY ("Algorithm")
NORMAL ("The voiced intervals are determined on the basis of the voiced/unvoiced decisions in the @Pitch object. "
	"For every voiced interval, a number of %points (or glottal pulses) is found as follows:")
LIST_ITEM ("1. The first point %t__1_ is the absolute extremum (or the maximum, or the minimum, depending on "
	"your %%Include maxima% and %%Include minima% settings) of the amplitude of the #Sound, "
	"between %t__%mid_ \\-- %T__0_ / 2 and %t__%mid_ + %T__0_ / 2, where %t__%mid_ is the midpoint of the interval, "
	"and %T__0_ is the period at %t__%mid_, as can be interpolated from the #Pitch contour.")
LIST_ITEM ("2. From this point, we recursively search for points %t__%i_ to the left "
	"until we reach the left edge of the interval. These points are the absolute extrema (or the maxima, or the minima) "
	"between the times "
	"%t__%i\\--1_ \\-- 1.2 %T__0_(%t__%i\\--1_) and %t__%i\\--1_ \\-- 0.8 %T__0_(%t__%i\\--1_).")
LIST_ITEM ("3. The same is done to the right of %t__1_.")
NORMAL ("The periods that are found in this way are much more variable than those found by "
	"@@Sound & Pitch: To PointProcess (cc)@, and therefore less useful for PSOLA analysis.")
MAN_END

MAN_BEGIN ("Sound & Formant: Filter", "ppgb", 19991119)
INTRO ("A command to create a new Sound from the selected @Sound and @Formant objects.")
NORMAL ("For examples, see @@Source-filter synthesis@.")
NORMAL ("The resulting Sound is scaled so that its maximum absolute amplitude is 0.99. "
	"If you don't want this, use @@Sound & Formant: Filter (no scale)@ instead.")
MAN_END

MAN_BEGIN ("Sound & Formant: Filter (no scale)", "ppgb", 19991119)
INTRO ("A command to create a new Sound from the selected @Sound and @Formant objects.")
NORMAL ("For examples, see @@Source-filter synthesis@.")
NORMAL ("Unlike what happens in @@Sound & Formant: Filter@, "
	"the resulting Sound is not scaled. This allows generation of a series "
	"of signals with controlled relative intensities.")
MAN_END

MAN_BEGIN ("Sound & FormantTier: Filter", "ppgb", 19991120)
INTRO ("A command to create a new Sound from the selected @Sound and @FormantTier objects.")
NORMAL ("For examples, see @@Source-filter synthesis@.")
NORMAL ("The resulting Sound is scaled so that its maximum absolute amplitude is 0.99. "
	"If you don't want this, use @@Sound & FormantTier: Filter (no scale)@ instead.")
MAN_END

MAN_BEGIN ("Sound & FormantTier: Filter (no scale)", "ppgb", 19991119)
INTRO ("A command to create a new Sound from the selected @Sound and @FormantTier objects.")
NORMAL ("For examples, see @@Source-filter synthesis@.")
NORMAL ("Unlike what happens in @@Sound & FormantTier: Filter@, "
	"the resulting Sound is not scaled. This allows generation of a series "
	"of signals with controlled relative intensities.")
MAN_END

MAN_BEGIN ("Sound & IntensityTier: Multiply", "ppgb", 20000724)
INTRO ("A command to create a new Sound from the selected @Sound and @Intensity objects.")
NORMAL ("The resulting Sound equals the original sound, multiplied by a linear interpolation of the intensity. "
	"Afterwards, the resulting Sound is scaled so that its maximum absolute amplitude is 0.9.")
MAN_END

MAN_BEGIN ("SoundEditor", "ppgb", 20030312)
INTRO ("An @@Editors|Editor@ for viewing and editing a @Sound object. "
	"Most of the functions of this editor are described in the @Intro.")
ENTRY ("The markers")
NORMAL ("To set the cursor, use the left mouse button. A horizontal line will also be shown; "
	"this line crosses the cursor line at the sound's function value. "
	"This function value is the sinc-interpolated value, and is generally different from the "
	"value that you would expect when looking at the linearly interpolated version of the sampled sound.")
NORMAL ("To select a part of the time domain, use the @@time selection@ mechanism.")
ENTRY ("Playing")
NORMAL ("To play any part of the sound, click on one of the rectangles "
	"below or above the sound window (there can be 1 to 8 of these rectangles), "
	"or choose a Play command from the View menu.")
ENTRY ("Publishing")
NORMAL ("To perform analyses on the selection, or save it to a file, "
	"create an independent Sound as a copy of the selection, "
	"by clicking on the button that will copy the selection to the List of Objects; "
	"the resulting Sound will be called \"Sound untitled\".")
ENTRY ("Editing")
LIST_ITEM ("\\bu Cut: cut the selection to the clipboard.")
LIST_ITEM ("\\bu Copy: copy the selection to the clipboard.")
LIST_ITEM ("\\bu Paste: paste the clipboard to the cursor.")
LIST_ITEM ("\\bu Zero: set the selected samples to zero.")
LIST_ITEM ("\\bu Reverse: reverse the selected part of the sound.")
NORMAL ("You can undo these commands with Undo (Command-Z).")
ENTRY ("The Group button")
NORMAL ("To synchronize a SoundEditor window with other windows that show a time signal, "
	"push the Group button in all the windows that you want to synchronize. "
	"You cannot Cut from or Paste into a synchronized SoundEditor window.")
MAN_END

MAN_BEGIN ("SoundRecorder", "ppgb", 20031117)
INTRO ("One of the windows in P\\s{RAAT}: a tool for recording a 16-bit sampled @Sound. "
	"It appears on your screen if you choose @@Record mono Sound...@ or @@Record stereo Sound...@ "
	"from the @@New menu@.")
NORMAL ("Depending on your system, the SoundRecorder window may allow you to choose "
	"the sample rate, the gain, and the input device (microphone, line, or digital). "
	"The sound input level is monitored continuously with two meters.")
ENTRY ("Usage")
NORMAL ("To record the sound, use the Record and Stop buttons in the SoundRecorder window. "
	"Click ##%%To list#% to copy the recorded sound to the List of Objects "
	"(or ##%%Left to list#% or ##%%Right to list#% to copy the left or right channel if you have a stereo sound). "
	"The name of the resulting Sound object will be taken from the text field next to the button clicked.")
ENTRY ("Size of the recording buffer")
NORMAL ("The size of the recording buffer determines how many seconds of sound you can record. "
	"For instance, if the recording buffer is 20 megabytes (the standard value), you can record 220 seconds in stereo "
	"(440 seconds in mono) at a sample rate of 22050 Hz, "
	"or 110 seconds in stereo (220 seconds in mono) at a sample rate of 44100 Hz. "
	"You can change the size of the recording buffer "
	"with ##Sound input prefs...# from the Preferences submenu in the Control menu "
	"(on Macintosh System 8 or 9 with virtual memory switched off, however, "
	"the buffer always fills the available temporary memory, i.e. the size of the largest unused block "
	"reported by \"About this computer\" in the Finder; to maximize this, quit some applications other than P\\s{RAAT}).")
NORMAL ("If you recorded a very long sound, it is probable that you cannot copy it to the list of objects. "
	"In such a case, you can still write the sound to disk with one of the six Write commands in the File menu. "
	"You can then open such a long sound file in P\\s{RAAT} with @@Open long sound file...@ from the Read menu.")
ENTRY ("Recording sounds on SGI")
NORMAL ("On SGI (Indigo, Indy, O2), you can record from microphone, line input, or digital input. "
	"Changes in most of the audio settings (sample rate, gain, input device) are reflected immediately in your system's Audio Control Panel; "
	"you can also change the settings from the Audio Control Panel: the SoundRecorder window will follow suit.")
ENTRY ("Recording sounds on Macintosh")
NORMAL ("On newer Macintoshes, you can record from the combined microphone / line input (on some computers, these are separate), "
	"or from the internal CD. "
	"From MacOS 8.1 on, changes in your choice of input device are reflected immediately in your Monitors & Sound control panel; "
	"you can also change the settings from this control panel: the SoundRecorder window will follow suit.")
ENTRY ("Recording sounds in Windows")
NORMAL ("In Windows, you can choose your input device with the help of the recording mixer that is supplied by Windows or comes with "
	"your sound card. There will usually be a loudspeaker icon in the Start bar; double-click it, and you will see the %playing mixer "
	"(if there is no loudspeaker icon, go to ##Control Panels#, then ##Sounds and Audio Devices#, then #Volume, then #Advanced; "
	"do not blame us for how Windows XP works). In the playing mixer, choose #Properties from the #Option menu, then click #Recording, "
	"then #OK. You are now in the %recording mixer.")
NORMAL ("You can watch the input level only while recording.")
ENTRY ("Calibration")
NORMAL ("Your computer's sound-recording software returns integer values between -32768 and 32767. "
	"Praat divides them by 32768 before putting them into a Sound object, "
	"so that the values in the Sound objects are always between -1 and +1.")
NORMAL ("The Praat program considers these numbers to be in units of Pascal.")
NORMAL ("If you record from your small Silicon Graphics microphone, and set your input-gain sliders at maximum sensitivity, "
	"the values in the resulting Sound object are smaller than the real sound pressure at the microphone. "
	"The difference is 4 dB for an Indigo, and 24 dB for an Indy. "
	"Therefore, the values in the Sound object represent the actual sound pressure "
	"at a distance of 1.6 times (Indigo) or 16 times (Indy) the distance "
	"between your mouth and your microphone at the time of recording.")
NORMAL ("For a speaker who holds the microphone at 30 centimetres (Indigo) or 3 centimetres (Indy), "
	"the dB values of sounds recorded from the microphone represent the actual sound pressure at 48 centimetres. "
	"To get the sound pressure at 1 metre, you divide by two (e.g., with $$Formula... self/2$).")
MAN_END

MAN_BEGIN ("Sounds: Concatenate", "ppgb", 20000123)
INTRO ("A command to concatenate all selected @Sound objects into a single large Sound.")
NORMAL ("All sounds must have equal sampling frequencies. "
	"They are concatenated in the order that they appear in the list of objects.")
ENTRY ("How to concatenate directly to a file")
NORMAL ("If the resulting sound does not fit into memory, use one of the "
	"commands in the @@Write menu@. See @@How to concatenate sound files@.")
MAN_END

MAN_BEGIN ("Sounds: Convolve", "ppgb", 19980323)
INTRO ("A command to convolve two @Sound objects with each other.")
NORMAL ("The convolution of two time signals %A(%t) and %B(%t) is defined as")
FORMULA ("(%A * %B) (%t) \\=3 \\in %A(%\\ta) %B(%t-%\\ta) %d%\\ta")
NORMAL ("Convolution is commutative, i.e. the convolution of %A and %B equals the convolution of %B and %A.")
ENTRY ("Algorithm")
NORMAL ("Since convolution in the time domain amounts to multiplication in the frequency domain, "
	"both sounds are FFT-ed, the resulting spectra are multiplied, and the resulting product spectrum "
	"is FFT-ed back to give the convoluted sound.")
MAN_END

MAN_BEGIN ("Spectrogram", "ppgb", 20030316)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}. For tutorial information, see @@Intro 3. Spectral analysis@.")
NORMAL ("A Spectrogram object represents  an acoustic time-frequency representation of a sound: "
	"the power spectral density %P (%f, %t), expressed in Pa^2/Hz. "
	"It is sampled into a number of points centred around equally spaced times %t__%i_ "
	"and frequencies %f__%j_.")
ENTRY ("Inside a Spectrogram")
NORMAL ("With @Inspect, you will see the following attributes:")
TAG ("%xmin")
DEFINITION ("starting time, in seconds.")
TAG ("%xmax")
DEFINITION ("end time, in seconds.")
TAG ("%nx")
DEFINITION ("the number of times (\\>_ 1).")
TAG ("%dx")
DEFINITION ("time step, in seconds.")
TAG ("%x1")
DEFINITION ("the time associated with the first column, in seconds. "
	"This will usually be in the range [%xmin, %xmax]. "
	"The time associated with the last column (i.e., %x1 + (%nx \\-- 1) %dx)) "
	"will also usually be in that range.")
TAG ("%ymin")
DEFINITION ("lowest frequency, in Hertz. Normally 0.")
TAG ("%ymax")
DEFINITION ("highest frequency, in Hertz.")
TAG ("%ny")
DEFINITION ("the number of frequencies (\\>_ 1).")
TAG ("%dy")
DEFINITION ("frequency step, in Hertz.")
TAG ("%y1")
DEFINITION ("the frequency associated with the first row, in Hertz. Usually %dy / 2. "
	"The frequency associated with the last row (i.e., %y1 + (%ny \\-- 1) %dy)) "
	"will often be %ymax - %dy / 2.")
TAG ("%z__%ij_, %i = 1 ... %ny, %j = 1 ... %nx")
DEFINITION ("the power spectral density, in Pa^2/Hz. ")
MAN_END

MAN_BEGIN ("Spectrogram: Formula...", "ppgb", 20021206)
INTRO ("A command for changing the data in all selected @Spectrogram objects.")
NORMAL ("See the @Formulas tutorial for examples and explanations.")
MAN_END

MAN_BEGIN ("Spectrogram: Paint...", "ppgb", 20030916)
INTRO ("A command to draw the selected @Spectrogram object(s) into the @@Picture window@ in shades of grey.")
ENTRY ("Arguments")
TAG ("%%From time%, %%To time% (seconds)")
DEFINITION ("the time domain along the %x axis.")
TAG ("%%From frequency%, %%To frequency% (Hertz)")
DEFINITION ("the frequency domain along the %y axis.")
TAG ("%%Dynamic range% (dB)")
DEFINITION ("The global maximum of the spectrogram (after preemphasis) will always be drawn in black; "
	"all values that are more than %%Dynamic range% dB below this maximum (after dynamic compression) "
	"will be drawn in white. Values in-between have appropriate shades of grey.")
TAG ("%%Preemphasis% (dB/octave)")
DEFINITION ("determines the steepness of a high-pass filter, "
	"i.e., how much the power of higher frequencies will be raised before drawing, as compared to lower frequencies. "
	"Since the spectral slope of human vowels is approximately -6 dB per octave, "
	"the standard value for this parameter is +6 dB per octave, "
	"so that the spectrum is flattened and the higher formants look as strong as the lower ones.")
TAG ("%%Dynamic compression")
DEFINITION ("determines how much stronger weak time frames should be made before drawing. "
	"Normally, this parameter is between 0 and 1. If it is 0, there is no dynamic compression. "
	"If it is 1, all time frames (vertical bands) will be drawn equally strong, "
	"i.e., all of them will contain frequencies that are drawn in black. "
	"If this parameter is 0.4 and the global maximum is at 80 dB, then a frame with a maximum at 20 dB "
	"(which will normally be drawn all white if the dynamic range is 50 dB), "
	"will be raised by 0.4 * (80 - 20) = 24 dB, "
	"so that its maximum will be seen at 44 dB (thus making this frame visible).")
MAN_END

MAN_BEGIN ("Spectrogram: To Spectrum (slice)...", "ppgb", 19961003)
INTRO ("A command to create a @Spectrum object from every selected @Spectrogram object.")
ENTRY ("Purpose")
NORMAL ("to extract the information contained in a Spectrogram at a certain time.")
ENTRY ("Algorithm")
NORMAL ("The Spectrum will be constructed from one frame of the Spectrogram, "
	"namely the frame whose centre is closed to the %time argument. ")
MAN_END

MAN_BEGIN ("Spectrum", "ppgb", 20030316)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}. A Spectrum object represents "
	"the complex spectrum as a function of frequency. "
	"If the spectrum was created from a sound (which is expressed in units of Pascal), "
	"the complex values are expressed in units Pa/Hz (Pascal per Hertz). ")
ENTRY ("Spectrum commands")
NORMAL ("Creation:")
LIST_ITEM ("\\bu @@Sound: To Spectrum (fft)")
NORMAL ("Queries:")
LIST_ITEM ("\\bu @@Spectrum: Get centre of gravity...")
LIST_ITEM ("\\bu @@Spectrum: Get standard deviation...")
LIST_ITEM ("\\bu @@Spectrum: Get skewness...")
LIST_ITEM ("\\bu @@Spectrum: Get kurtosis...")
LIST_ITEM ("\\bu @@Spectrum: Get central moment...")
NORMAL ("Modification:")
LIST_ITEM ("\\bu @@Spectrum: Filter (pass Hann band)...")
LIST_ITEM ("\\bu @@Spectrum: Filter (stop Hann band)...")
LIST_ITEM ("\\bu @@Formula...")
NORMAL ("Conversion:")
LIST_ITEM ("\\bu @@Spectrum: To Ltas (1-to-1)")
LIST_ITEM ("\\bu @@Spectrum: To Spectrogram")
NORMAL ("Synthesis:")
LIST_ITEM ("\\bu @@Spectrum: To Sound (fft)")
ENTRY ("Inside the Spectrum object")
NORMAL ("With @Inspect, you can see that a Spectrum object has the following attributes:")
TAG ("%x__%min_")
DEFINITION ("bottom of frequency domain, in Hertz. Usually 0.")
TAG ("%x__%max_")
DEFINITION ("top of frequency domain, in Hertz.")
TAG ("%n__%x_")
DEFINITION ("the number of frequencies (\\>_ 1).")
TAG ("%dx")
DEFINITION ("frequency step, in Hertz.")
TAG ("%x__1_")
DEFINITION ("the frequency associated with the first bin, in Hertz. Often 0. "
	"The frequency associated with the last bin (i.e., %x__1_ + (%n__%x_ \\-- 1) %dx)) "
	"will often be equal to %x__%max_.")
TAG ("%n__%y_")
DEFINITION ("the number of `rows' (if you regard a Spectrum as a sort of @Matrix). Always 2: the real part and the imaginary part.")
TAG ("%z__1%i_, %i = 1 ... %n__%x_")
DEFINITION ("the real part of the spectrum, often in Pa/Hz. ")
TAG ("%z__2%i_, %i = 1 ... %n__%x_")
DEFINITION ("the imaginary part of the spectrum, often in Pa/Hz. ")
MAN_END

MAN_BEGIN ("Spectrum: Filter (pass Hann band)...", "ppgb", 20030916)
INTRO ("A command to modify every selected @Spectrum object.")
NORMAL ("The complex values in the #Spectrum are multiplied by real-valued sine shapes and straight lines, according to the following figure:")
PICTURE (5, 3, draw_SpectrumPassHann)
ENTRY ("Arguments")
TAG ("%%From frequency% (standard value: 500 Hz)")
DEFINITION ("the lower edge of the pass band (%f__1_ in the figure). The value zero is special: the filter then acts as a low-pass filter.")
TAG ("%%To frequency% (standard value: 1000 Hz)")
DEFINITION ("the upper edge of the pass band (%f__2_ in the figure). The value zero is special: the filter then acts as a high-pass filter.")
TAG ("%Smoothing (standard value: 100 Hz)")
DEFINITION ("the width of the region between pass and stop (%w in the figure).")
ENTRY ("Usage")
NORMAL ("Because of its symmetric Hann-like shape, the filter is especially useful for decomposing the Spectrum into consecutive bands. "
	"For instance, we can decompose the spectrum into the bands 0-500 Hz, 500-1000 Hz, 1000-2000 Hz, and 2000-\"0\" Hz:")
PICTURE (5, 3, draw_SpectrumPassHann_decompose)
NORMAL ("By adding the four bands together, we get the original spectrum again.")
NORMAL ("A complementary filter is described at @@Spectrum: Filter (stop Hann band)...@.")
NORMAL ("See the @Filtering tutorial for information on the need for smoothing and a comparative discussion of various filters.")
MAN_END

MAN_BEGIN ("Spectrum: Filter (stop Hann band)...", "ppgb", 20030916)
INTRO ("A command to modify every selected @Spectrum object.")
NORMAL ("The complex values in the #Spectrum are multiplied by real-valued sine shapes and straight lines, according to the following figure:")
PICTURE (5, 3, draw_SpectrumStopHann)
ENTRY ("Arguments")
TAG ("%%From frequency% (standard value: 500 Hz)")
DEFINITION ("the lower edge of the stop band (%f__1_ in the figure). The value zero is special: the filter then acts as a high-pass filter.")
TAG ("%%To frequency% (standard value: 1000 Hz)")
DEFINITION ("the upper edge of the stop band (%f__2_ in the figure). The value zero is special: the filter then acts as a low-pass filter.")
TAG ("%Smoothing (standard value: 100 Hz)")
DEFINITION ("the width of the region between stop and pass (%w in the figure).")
ENTRY ("Usage")
NORMAL ("This filter is the complement from the pass-band filter (@@Spectrum: Filter (pass Hann band)...@). "
	"For instance, we can decompose the spectrum into the above stop-band spectrum and a band from 500 to 1000 Hz:")
PICTURE (5, 3, draw_SpectrumStopHann_decompose)
NORMAL ("By adding the two spectra together, we get the original spectrum again.")
NORMAL ("See the @Filtering tutorial for information on the need for smoothing and a comparative discussion of various filters.")
MAN_END

MAN_BEGIN ("Spectrum: Formula...", "ppgb", 20021206)
INTRO ("A command for changing the data in all selected @Spectrum objects.")
NORMAL ("See the @Formulas tutorial for examples and explanations.")
MAN_END

MAN_BEGIN ("Spectrum: Get central moment...", "ppgb", 20020323)
INTRO ("A command to query the selected @Spectrum object.")
NORMAL ("If the complex spectrum is given by %S(%f), the %%n%th central spectral moment is given by")
FORMULA ("\\in__0_^\\oo  (%f \\-- %f__%c_)^%n |%S(%f)|^%p %df")
NORMAL ("divided by the \"energy\"")
FORMULA ("\\in__0_^\\oo  |%S(%f)|^%p %df")
NORMAL ("In this formula, %f__%c_ is the spectral centre of gravity (see @@Spectrum: Get centre of gravity...@). "
	"Thus, the %%n%th central moment is the average of (%f \\-- %f__%c_)^%n over the entire frequency domain, "
	"weighted by |%S(%f)|^%p. For %p = 2, the weighting is done by the power spectrum, and for %p = 1, "
	"the weighting is done by the absolute spectrum. A value of %p = 2/3 has been seen as well.")
ENTRY ("Arguments")
TAG ("%Moment")
DEFINITION ("the number %n in the formulas above. A number of 3 gives you the third central spectral moment. "
	"It is not impossible to ask for fractional moments, e.g. %n = 1.5.")
TAG ("%Power")
DEFINITION ("the quantity %p in the formula above. Common values are 2, 1, or 2/3.")
ENTRY ("Usage")
NORMAL ("For %n = 1, the central moment should be zero, since the centre of gravity %f__%c_ is computed with "
	"the same %p. For %n = 2, you get the variance of the frequencies in the spectrum; the standard deviation "
	"of the frequency is the square root of this. For %n = 3, you get the non-normalized spectral skewness; "
	"to normalize it, you can divide by the 1.5 power of the second moment. For %n = 4, you get the "
	"non-normalized spectral kurtosis; to normalize it, you can divide by the square of the second moment "
	"and subtract 3. Praat can directly give you the quantities mentioned here:")
LIST_ITEM ("\\bu @@Spectrum: Get centre of gravity...")
LIST_ITEM ("\\bu @@Spectrum: Get standard deviation...")
LIST_ITEM ("\\bu @@Spectrum: Get skewness...")
LIST_ITEM ("\\bu @@Spectrum: Get kurtosis...")
MAN_END

MAN_BEGIN ("Spectrum: Get centre of gravity...", "ppgb", 20020323)
INTRO ("A command to query the selected @Spectrum object.")
NORMAL ("If the complex spectrum is given by %S(%f), where %f is the frequency, the %%centre of gravity% "
	"is given by")
FORMULA ("\\in__0_^\\oo  %f |%S(%f)|^%p %df")
NORMAL ("divided by the \"energy\"")
FORMULA ("\\in__0_^\\oo  |%S(%f)|^%p %df")
NORMAL ("Thus, the centre of gravity is the average of %f over the entire frequency domain, "
	"weighted by |%S(%f)|^%p. For %p = 2, the weighting is done by the power spectrum, and for %p = 1, "
	"the weighting is done by the absolute spectrum. A value of %p = 2/3 has been seen as well.")
ENTRY ("Argument")
TAG ("%Power")
DEFINITION ("the quantity %p in the formulas above. Common values are 2, 1, or 2/3.")
ENTRY ("Interpretation")
NORMAL ("The spectral centre of gravity is a measure for how high the frequencies in a spectrum are on average. "
	"For a sine wave with a frequency of 377 Hz, the centre of gravity is 377 Hz. You can easily check this "
	"in Praat by creating such a sine wave (@@Create Sound...@), then converting it to a Spectrum "
	"(@@Sound: To Spectrum (fft)@), then querying the mean frequency. For a white noise sampled at 22050 Hz, "
	"the centre of gravity is 5512.5 Hz, i.e. one half of the @@Nyquist frequency@.")
ENTRY ("Related measures")
NORMAL ("The centre of gravity is used in the computation of spectral moments:")
LIST_ITEM ("\\bu @@Spectrum: Get central moment...")
LIST_ITEM ("\\bu @@Spectrum: Get standard deviation...")
LIST_ITEM ("\\bu @@Spectrum: Get skewness...")
LIST_ITEM ("\\bu @@Spectrum: Get kurtosis...")
MAN_END

MAN_BEGIN ("Spectrum: Get kurtosis...", "ppgb", 20020323)
INTRO ("A command to query the selected @Spectrum object.")
NORMAL ("The (normalized) kurtosis of a spectrum is the fourth central moment of this spectrum, "
	"divided by the square of the second central moment, minus 3. "
	"See @@Spectrum: Get central moment...@.")
ENTRY ("Argument")
TAG ("%Power")
DEFINITION ("the quantity %p in the formula for the centre of gravity and the second and fourth central moment. "
	"Common values are 2, 1, or 2/3.")
ENTRY ("Interpretation")
NORMAL ("The kurtosis is a measure for how much the shape of the spectrum around the "
	"%%centre of gravity% is different from a Gaussian shape. "
	"For a white noise, the kurtosis is Ð6/5.")
ENTRY ("Related measures")
LIST_ITEM ("\\bu @@Spectrum: Get centre of gravity...")
LIST_ITEM ("\\bu @@Spectrum: Get central moment...")
LIST_ITEM ("\\bu @@Spectrum: Get standard deviation...")
LIST_ITEM ("\\bu @@Spectrum: Get skewness...")
MAN_END

MAN_BEGIN ("Spectrum: Get skewness...", "ppgb", 20020323)
INTRO ("A command to query the selected @Spectrum object.")
NORMAL ("The (normalized) skewness of a spectrum is the third central moment of this spectrum, "
	"divided by the 1.5 power of the second central moment. "
	"See @@Spectrum: Get central moment...@.")
ENTRY ("Argument")
TAG ("%Power")
DEFINITION ("the quantity %p in the formula for the centre of gravity and the second and third central moment. "
	"Common values are 2, 1, or 2/3.")
ENTRY ("Interpretation")
NORMAL ("The skewness is a measure for how much the shape of the spectrum below the "
	"%%centre of gravity% is different from the shape above the mean frequency. "
	"For a white noise, the skewness is zero.")
ENTRY ("Related measures")
LIST_ITEM ("\\bu @@Spectrum: Get centre of gravity...")
LIST_ITEM ("\\bu @@Spectrum: Get central moment...")
LIST_ITEM ("\\bu @@Spectrum: Get standard deviation...")
LIST_ITEM ("\\bu @@Spectrum: Get kurtosis...")
MAN_END

MAN_BEGIN ("Spectrum: Get standard deviation...", "ppgb", 20020323)
INTRO ("A command to query the selected @Spectrum object.")
NORMAL ("The standard deviation of a spectrum is the square root of the second central moment of this spectrum. "
	"See @@Spectrum: Get central moment...@.")
ENTRY ("Argument")
TAG ("%Power")
DEFINITION ("the quantity %p in the formula for the centre of gravity and the second central moment. "
	"Common values are 2, 1, or 2/3.")
ENTRY ("Interpretation")
NORMAL ("The standard deviation is a measure for how much the frequencies in a spectrum can deviate from "
	"the %%centre of gravity%. "
	"For a sine wave, the standard deviation is zero. For a white noise, the standard deviation "
	"is the @@Nyquist frequency@ divided by \\Vr12.")
ENTRY ("Related measures")
LIST_ITEM ("\\bu @@Spectrum: Get centre of gravity...")
LIST_ITEM ("\\bu @@Spectrum: Get central moment...")
LIST_ITEM ("\\bu @@Spectrum: Get skewness...")
LIST_ITEM ("\\bu @@Spectrum: Get kurtosis...")
MAN_END

MAN_BEGIN ("Spectrum: To Ltas (1-to-1)", "ppgb", 19980327)
INTRO ("A command for converting each selected @Spectrum object into an @Ltas object without loss of frequency resolution.")
ENTRY ("Algorithm")
NORMAL ("Each band %b__%i_ in the Ltas is computed from a single frequency sample %s__%i_ in the Spectrum as follows:")
FORMULA ("%b__%i_ = 2 ((Re (%s__%i_))^2 + (Im (%s__%i_))^2) / 4.0\\.c10^^-10^")
NORMAL ("If the original Spectrum is expressible in Pa / Hz (sound pressure in air), the Ltas values "
	"are in \"dB/Hz\" relative to the auditory threshold at 1000 Hz (2\\.c10^^-5^ Pa).")
MAN_END

MAN_BEGIN ("Spectrum: To Sound (fft)", "ppgb", 20020526)
INTRO ("A command for creating a @Sound object from every selected @Spectrum object.")
ENTRY ("Algorithm")
NORMAL ("The algorithm is the continuous interpretation of the inverse @@Fast Fourier Transform@. "
	"If the Spectrum is expressed in Pa/Hz, the Sound will be in Pascal. "
	"The frequency integral over the Sound equals the time integral over the Spectrum.")
ENTRY ("Behaviour")
NORMAL ("If you perform this command on a Spectrum object that was created earlier with @@Sound: To Spectrum (fft)@, "
	"the resulting Sound is equal to the Sound that was input to ##Sound: To Spectrum (fft)#.")
MAN_END

MAN_BEGIN ("Spectrum: To Spectrogram", "ppgb", 19961003)
INTRO ("A command to create a @Spectrogram object from every selected @Spectrum object.")
ENTRY ("Purpose")
NORMAL ("Format conversion.")
ENTRY ("Behaviour")
NORMAL ("The Spectrogram will have only one frame (time slice).")
ENTRY ("Algorithm")
NORMAL ("The values are computed as the sum of the squares of the real and imaginary parts of the Spectrum.")
MAN_END

MAN_BEGIN ("SpectrumEditor", "ppgb", 20030316)
INTRO ("One of the @editors in P\\s{RAAT}. It allows you to view, "
	"zoom, and play a @Spectrum object.")
NORMAL ("Clicking on one of the (maximally) 8 rectangles above or below the drawing area "
	"lets you play a @Sound that is synthesized from a band-filtered part of the @Spectrum. "
	"You can also copy the Spectrum, band-filtered with the @@frequency selection@, "
	"or the Sound synthesized from this Spectrum, to the list of objects.")
MAN_END

MAN_BEGIN ("SpellingChecker", "ppgb", 20030916)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}. For checking the spelling in texts and @TextGrid objects.")
ENTRY ("1. How to create a SpellingChecker object")
NORMAL ("You normally read in a SpellignChecker with @@Read from file...@ from the Read menu.")
ENTRY ("2. How to check the spelling of a @TextGrid")
NORMAL ("A SpellingChecker object can be used fur purposes of spelling checking. In order "
	"to check the spellings in a @TextGrid object, you first view the TextGrid in an editor window by selecting "
	"the TextGrid together with the SpellingChecker object, and clicking Edit. In most cases, you will also want "
	"to select a @Sound or @LongSound object before clicking Edit, so that a representation of the sound "
	"is also visible (and audible) in the editor. Thus, you typically select three objects and click Edit. "
	"The editor then allows you to check the spellings (command ##Check spelling# from the Search menu).")
ENTRY ("3. How to create a SpellingChecker object for the first time")
NORMAL ("If you are the maintainer of a word list for spelling checking, you will want "
	"to convert this list to a SpellingChecker object that you can distribute among the transcribers of your corpus.")
NORMAL ("The first step is to create a @WordList object from your text file, as described on the @WordList man page. "
	"Then you simply click ##To SpellingChecker#. A button labelled ##Edit...# appears. "
	"This command allows you to set the following attributes of the SpellingChecker object:")
/*TAG ("%%Check matching parentheses")
DEFINITION ("determines whether it is considered a spelling error if parentheses do not match, as in the string \"Hi) there\".")*/
TAG ("%%Allow all parenthesized")
DEFINITION ("this flag determines whether text between parentheses is ignored in spelling checking. "
	"This would allow the transcriber to mark utterances in foreign languages, which cannot be found in the lexicon.")
TAG ("%%Separating characters")
DEFINITION ("determines the set of characters (apart from the space character) that separate words. "
	"The standard is \".,;:()\". If a string like \"error-prone\" should be considered two separate words, "
	"you will like to change this to \".,;:()-\". "
	"For the Corpus of Spoken Dutch (CGN), the hyphen is not a separator, since words like \"mee-eter\" should be checked as a whole. "
	"If a string like \"Mary's\" should be considered two separate words, include the apostrophe.")
/*TAG ("%%Forbidden strings")
DEFINITION ("this will mainly contain characters that are not allowed in your corpus. For the CGN, this is \": ; \\\" \".")*/
TAG ("%%Allow all names")
DEFINITION ("determines whether all words that start with a capital are allowed. For the CGN, this is on, "
	"since the lexicon does not contain many names.")
TAG ("%%Name prefixes")
DEFINITION ("a space-separated list that determines what small groups of characters can precede names. For the CGN, "
	"this is \"'s- d' l'\", since names like %%'s-Gravenhage%, %%d'Ancona%, and %%l'H\\o^pital% should be ignored by the spelling checker.")
TAG ("%%Allow all words containing")
DEFINITION ("a space-separated list of strings that make a word correct even if not in the lexicon. "
	"For the CGN, this is \"* xxx\", since words like %%keuje*d% and %%verxxxing% should be ignored by the spelling checker.")
TAG ("%%Allow all words starting with")
DEFINITION ("a space-separated list of prefixes that make a word correct even if not in the lexicon. "
	"For the CGN, this is empty.")
TAG ("%%Allow all words ending in")
DEFINITION ("a space-separated list of suffixes that make a word correct even if not in the lexicon. "
	"For the CGN, this is \"-\", since the first word in %%verzekerings- en bankwezen% should be ignored by the spelling checker.")
MAN_END

MAN_BEGIN ("Strings", "ppgb", 20030316)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}. Represents an ordered list of strings.")
ENTRY ("Creation")
NORMAL ("The difficult way is to create a #Strings object from a generic Praat text file:")
CODE ("File type = \"ooTextFile\"")
CODE ("Object class = \"Strings\"")
CODE ("5 (number of strings)")
CODE ("\"Hello\"")
CODE ("\"Goodbye\"")
CODE ("\"Auf wiedersehen\"")
CODE ("\"Tsch\\bsu\\\" \\\" ss\"")
CODE ("\"Arrivederci\"")
NORMAL ("In this example, we see that a double quote within a string should be written twice; "
	"the fourth string will therefore be read as ##Tsch\\bsu\\\" ss#, "
	"and will be shown in info messages or in graphical text as ##Tsch\\u\"ss# (see @@special symbols@). "
	"This file can be read simply with the generic @@Read from file...@ command from the Read menu.")
NORMAL ("An easier way is to use the special command @@Read Strings from raw text file...@. "
	"The file can then simply look like this:")
CODE ("Hello")
CODE ("Goodbye")
CODE ("Auf wiedersehen")
CODE ("Tsch\\bsu\\\" ss")
CODE ("Arrivederci")
NORMAL ("In this example, all the strings are in the generic system-independent ASCII format that is used "
	"everywhere in Praat (messages, graphical text) "
	"for @@special symbols@. You could also have supplied the strings in a native format, which is "
	"ISO-Latin1 encoding on Unix and Windows computers, or Mac encoding on Macintosh computers. "
	"The file would then have simply looked like:")
CODE ("Hello")
CODE ("Goodbye")
CODE ("Auf wiedersehen")
CODE ("Tsch\\u\"ss")
CODE ("Arrivederci")
NORMAL ("To convert this into the generic system-independent ASCII format, use the #Genericize command.")
NORMAL ("You can also create a #Strings object from a directory listing or from some other objects:")
LIST_ITEM ("\\bu @@Create Strings as file list...")
LIST_ITEM ("\\bu @@Distributions: To Strings...@")
LIST_ITEM ("\\bu @@OTGrammar: Generate inputs...@")
LIST_ITEM ("\\bu @@OTGrammar & Strings: Inputs to outputs...@")
LIST_ITEM ("\\bu @@OTAnyGrammar: Generate inputs...@")
LIST_ITEM ("\\bu @@OTAnyGrammar & Strings: Inputs to outputs...@")
MAN_END

MAN_BEGIN ("Strings: To Distributions", "ppgb", 19971025)
INTRO ("A command to analyse each selected @Strings object into a @Distributions object.")
NORMAL ("The resulting #Distributions will collect the occurrences of every string in the #Strings object, "
	"and put the number of occurrences in its first and only column.")
ENTRY ("Example")
NORMAL ("We start from the following #Strings:")
CODE ("6 (number of strings)")
CODE ("\"hallo\"")
CODE ("\"dag allemaal\"")
CODE ("\"hallo\"")
CODE ("\"tot morgen\"")
CODE ("\"hallo\"")
CODE ("\"tot morgen\"")
NORMAL ("This will give us the following #Distributions:")
CODE ("1 (number of columns) \"\" (no column name)")
CODE ("\"hallo\"         3")
CODE ("\"dag allemaal\"  1")
CODE ("\"tot morgen\"    2")
MAN_END

MAN_BEGIN ("Table", "ppgb", 20030316)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}. See the @Statistics tutorial.")
MAN_END

MAN_BEGIN ("TableOfReal", "ppgb", 20030316)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}.")
NORMAL ("A TableOfReal object contains a number of %cells. Each cell belongs to a %row and a %column. "
	"For instance, a TableOfReal with 10 rows and 3 columns has 30 cells.")
NORMAL ("Each row and each column may be labeled with a %title.")
ENTRY ("Creating a TableOfReal from data in a text file")
NORMAL ("Suppose you have F1 and F2 data for vowels. "
	"You can create a simple text file like the following:")
CODE ("\"ooTextFile\"  ! The line by which Praat can recognize your file")
CODE ("\"TableOfReal\" ! The line that tells Praat about the contents")
CODE ("2   \"F1\"  \"F2\"      ! Number of columns, and column labels")
CODE ("3                   ! Number of rows")
CODE ("\"a\" 800 1100         ! Row label (vowel), F1 value, F2 value")
CODE ("\"i\" 280 2800         ! Row label (vowel), F1 value, F2 value")
CODE ("\"u\" 260  560         ! Row label (vowel), F1 value, F2 value")
NORMAL ("Praat is rather forgiving about the use of spaces, tabs, and newlines. "
	"See @@Write to text file...@ for general information.")
NORMAL ("You will often have your data in a file with a self-describing format, "
	"i.e. in which the number of values on a line equals the number of columns "
	"of the table:")
CODE ("800 1100")
CODE ("280 2800")
CODE ("260 560")
NORMAL ("Such a file can be read with @@Read Matrix from raw text file...@. "
	"This creates a Matrix object, which can be cast to a TableOfReal object "
	"by @@Matrix: To TableOfReal@. The resulting TableOfReal does not have "
	"any row or column labels yet. You could add column labels with:")
CODE ("Set column label (index)... 1 F1")
CODE ("Set column label (index)... 2 F2")
NORMAL ("Of course, if the row labels contain crucial information, "
	"and the number of rows is large, this is not a feasible method.")
MAN_END

MAN_BEGIN ("TableOfReal: Set value...", "ppgb", 19980105)
INTRO ("A command to change the value of one table cell in each selected @TableOfReal object.")
ENTRY ("Arguments")
TAG ("%%Row number")
DEFINITION ("the number of the row of the cell whose value you want to change.")
TAG ("%%Column number")
DEFINITION ("the number of the column of the cell whose value you want to change.")
TAG ("%%New value")
DEFINITION ("the value that you want the specified cell to have.")
MAN_END

MAN_BEGIN ("TextGrid", "ppgb", 20030316)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}, for segmentation and labelling.")
ENTRY ("Description")
NORMAL ("A #TextGrid object consists of a number of %tiers. "
	"Each of these tiers is either an %%interval tier% (class @IntervalTier) "
	"or a %%point tier% (class @TextTier).")
NORMAL ("An interval tier is a connected sequence of labelled intervals, with %boundaries in between. "
	"A point tier is a sequence of labelled points.")
ENTRY ("How to create a TextGrid")
TAG ("From scratch:")
LIST_ITEM ("@@Sound: To TextGrid...@ (takes the time domain from the Sound)")
LIST_ITEM ("@@LongSound: To TextGrid...@ (takes the time domain from the LongSound)")
LIST_ITEM ("@@PointProcess: To TextGrid...@ (takes the time domain from the PointProcess)")
LIST_ITEM ("@@PointProcess: To TextGrid (vuv)...@ (labels voiced and unvoiced intervals)")
LIST_ITEM ("@@Create TextGrid...@")
TAG ("From merging any number of existing tiers:")
LIST_ITEM ("@@TextTier(s): To TextGrid@")
LIST_ITEM ("@@IntervalTier(s): To TextGrid@")
LIST_ITEM ("@@TextTier(s) & IntervalTier(s): To TextGrid@")
TAG ("From merging an existing TextGrid with existing tiers or TextGrids:")
LIST_ITEM ("@@TextGrid & TextTier: Append@")
LIST_ITEM ("@@TextGrid & IntervalTier: Append@")
LIST_ITEM ("@@TextGrid & TextGrid: Merge@")
TAG ("Conversion from an old-style Label object:")
LIST_ITEM ("@@Label & Sound: To TextGrid@")
ENTRY ("How to edit a TextGrid")
NORMAL ("You select a TextGrid alone or together with a @Sound or @LongSound, and click #Edit. "
	"A @TextGridEditor will appear on your screen, containing the TextGrid "
	"and an optional copy of the Sound or LongSound.")
ENTRY ("How to draw a TextGrid")
TAG ("You can draw a TextGrid to the @@Picture window@ with:")
LIST_ITEM ("##TextGrid: Draw...")
LIST_ITEM ("##TextGrid & Sound: Draw...")
LIST_ITEM ("##TextGrid & Pitch: Draw...")
LIST_ITEM ("##TextGrid & Pitch: Draw separately...")
MAN_END

MAN_BEGIN ("TextGrid: Count labels...", "ppgb", 19980630)
INTRO ("A command to ask the selected @TextGrid object how many of the specified labels "
	"it contains in the specified tier.")
ENTRY ("Arguments")
TAG ("%%Tier number")
DEFINITION ("the number (1, 2, 3...) of the tier whose labels you want to investigate.")
TAG ("%%Label text")
DEFINITION ("the text on the labels that you want to count.")
ENTRY ("Behaviour")
NORMAL ("The number of intervals or points with label %%Label text% in tier %%Tier number% "
	"is written into the @@Info window@. If the specified tier does not exist, the number will be 0.")
ENTRY ("Scripting")
NORMAL ("You can use this command to put the number into a script variable:")
CODE ("select TextGrid hallo")
CODE ("number_of_a = Count labels... 1 a")
NORMAL ("In this case, the value will not be written into the Info window.")
MAN_END
 
MAN_BEGIN ("TextGrid & IntervalTier: Append", "ppgb", 19970317)
INTRO ("A command to append the selected @IntervalTier to the selected @TextGrid.")
MAN_END

MAN_BEGIN ("TextGrid & TextGrid: Merge", "ppgb", 19970317)
INTRO ("A command to merge two selected @TextGrid objects into a new @TextGrid.")
MAN_END

MAN_BEGIN ("TextGrid & TextTier: Append", "ppgb", 19970317)
INTRO ("A command to append the selected @TextTier to the selected @TextGrid.")
MAN_END

MAN_BEGIN ("TextGridEditor", "ppgb", 20030316)
INTRO ("One of the @Editors in P\\s{RAAT}, for editing a @TextGrid object.")
NORMAL ("You can optionally include a copy of a @Sound or @LongSound in this editor, "
	"by selecting both the TextGrid and the Sound or LongSound before clicking #Edit. "
	"The Sound or LongSound is shown in the upper part of the window, the tiers in the lower part. "
	"A text window at the top shows the text of the %#selected interval or point, "
	"i.e. the interval or point at the location of the cursor. "
	"All tiers are visible, and if you do not zoom in, all boundaries, points, and texts are visible, too. "
	"You can do many of the same things that you can do with a @SoundEditor or @LongSoundEditor.")
ENTRY ("Positioning the cursor or the selection marks")
NORMAL ("To position the cursor hair, @click in the #Sound, on a boundary, on a point, or inside an interval.")
NORMAL ("To select any part of the time domain, use the @@time selection@ mechanism; "
	"if you do this by clicking in a tier, "
	"the selected time domain will snap to the nearest boundary or point.")
ENTRY ("Creating new intervals, boundaries, points, or tiers")
NORMAL ("To create a new interval, create a new boundary in an interval tier.")
NORMAL ("To create a new boundary or point in a tier, @click inside the cursor circle in that tier, "
	"or choose one of the commands in the Boundary/Point menu to insert a boundary at the cursor time "
	"on the selected tier (shortcut: Enter) or on any tier (shortcuts: Command-F1 through Command-F9). The original text "
	"in the interval that is split, is divided up between the two resulting intervals, depending on "
	"the position of the text cursor in the text window.")
NORMAL ("To create a new tier, choose ##Add interval tier# or ##Add point tier# from the #Tier menu.")
ENTRY ("Playing an entire interval, or part of it")
NORMAL ("As in many other editors, you can play a stretch of sound by clicking in any of the rectangles "
	"around the drawing area.")
NORMAL ("To play an interval of an interval tier, you first @click inside it. This will make the interval %selected, "
	"which means that the visible part of the interval will be drawn in yellow. The cursor will be positioned "
	"at the start of the interval, and the time selection will comprise exactly the interval. This means that "
	"you can use the Tab key to play the interval. If you press it while a sound is playing, "
	"the Tab key will halt the playing sound, and the cursor will move to the time at which the sound stopped playing. "
	"This helps you to divide up a long sentence into parts that you can remember long enough to write them "
	"down.")
NORMAL ("The Tab key will play the selected interval.")
ENTRY ("Editing the text in an interval or at a point")
NORMAL ("To edit the label text of an interval or point:")
LIST_ITEM ("1. Select that interval or point by clicking in or on it. The text currently in the interval or point "
	"will appear in the text window.")
LIST_ITEM ("2. Just type the text, and use the mouse and the arrow keys to navigate the text window. "
	"Everything you type will become visible immediately in the text window as well as in the selected "
	"interval or point.")
NORMAL ("You can use all the @@Special symbols@ "
	"that you can use elsewhere in Praat, including mathematical symbols, Greek letters, superscripts, "
	"and phonetic symbols.")
ENTRY ("Selecting a tier")
NORMAL ("To select a tier, click anywhere inside it. Its number and name will be drawn in red, "
	"and a pointing finger symbol (\\pf) will appear on its left.")
ENTRY ("Selecting a boundary or point")
NORMAL ("To select a boundary on an interval tier, @click in its vicinity or inside the following interval; "
	"the boundary will be drawn in red. The text in the interval will appear in the text window.")
NORMAL ("To select a point on a point tier, @click in its vicinity; it will be drawn in red. "
	"The text of the point will appear in the text window.")
ENTRY ("Moving one or more boundaries or points")
NORMAL ("To move a boundary or point to another time position, @drag it with the mouse.")
NORMAL ("To move all the boundaries and points with the same time (on different tiers) to another time position, "
	"@@Shift-drag@ them.")
NORMAL ("To move boundaries or points to the exact time position of a boundary or point on an other tier, "
	"@drag them into that other tier and into the vicinity of that boundary or point.")
NORMAL ("To move boundaries or points to the exact time position of the cursor, "
	"@drag them into the vicinity of the cursor.")
ENTRY ("Removing a boundary, point, or tier")
NORMAL ("To remove a selected #boundary, choose #Remove from the #Boundary menu. "
	"This creates a new interval which is the union of the two intervals originally adjoining the boundary; "
	"the new text of this interval is the concatenation of the two original texts, "
	"except if these were equal, in which case the new text equals both original texts.")
NORMAL ("To remove a selected #point, choose #Remove from the #Point menu.")
NORMAL ("To remove a selected #tier, choose ##Remove entire tier# from the #Tier menu.")
/*"To rename a selected tier, choose 'Rename...' from the 'Tier' menu. "*/
/*"To remove all the boundaries and labels in a selected tier, "
"   choose 'Clear entire tier' from the 'Tier' menu. "*/
ENTRY ("Extracting a part of the sound")
NORMAL ("To copy the selected part of the Sound or LongSound as a Sound to the @@List of Objects@, "
	"choose ##Extract sound selection# from the #File menu. You can specify whether you want "
	"the time domain of the resulting Sound to match the starting and finishing times of the "
	"selection or whether you want the time domain of the resulting Sound to start at zero seconds.")
NORMAL ("If you are viewing a LongSound, you can save the selected part of it to a 16-bit sound file "
	"(AIFF, AIFC, WAV, NeXT/Sun, NIST) with a command from the File menu.")
ENTRY ("Accelerations")
NORMAL ("To write the @TextGrid object to a text file without going to the @@Object window@: "
	"choose ##Write TextGrid to text file...# from the #File menu.")
ENTRY ("Searching")
NORMAL ("The Search menu contains the command #Find (Command-F), which will allow you to specify "
	"a text whose first occurrence will then be looked for in the currently selected tier "
	"(starting from the currently selected text in the currently selected interval). "
	"The command ##Find again# (Command-G) will search for the next occurrence of the same search text.")
ENTRY ("Checking the spelling")
NORMAL ("You can check the spelling of the intervals in your tiers by including a @SpellingChecker "
	"object as you launch the editor: select TextGrid + (Long)Sound + SpellingChecker, "
	"then click Edit. The Search menu will contain the command ##Check spelling# (Command-L), "
	"which will search for the next word that does not occur in its lexicon.")
MAN_END

MAN_BEGIN ("TextTier", "ppgb", 20030316)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}.")
NORMAL ("A TextTier object represents a marked point process, i.e., it contains a series of (%time, %text) points, "
	"sorted by time.")
NORMAL ("Each point is marked with a text string. Though this is a system-independent ASCII text string, "
	"it may, as everywhere in Praat, contain @@Special symbols@ "
	"like Greek letters, mathematical symbols, style information, "
	"and Phonetic symbols, which will be visible when the string is drawn "
	"into the Picture window or viewed in a @TextGridEditor.")
ENTRY ("Creating a TextTier object in Praat")
NORMAL ("A TextTier object is usually extracted from a @TextGrid object, "
	"which may contain several tiers.")
TAG ("From scratch:")
LIST_ITEM ("1. Select an object with a time domain, e.g., a Sound or a Pitch.")
LIST_ITEM ("2. Click \"To TextTier\".")
NORMAL ("The resulting TextTier will have the same time domain "
	"as the original Sound (or Pitch), e.g., if the Sound object starts at 0.0 seconds "
	"and has a duration of 2.1 seconds, "
	"the resulting TextTier will also have an %xmin of 0.0 "
	"and an %xmax of 2.1 seconds.")
NORMAL ("The resulting TextTier will have 0 points in it.")
ENTRY ("Editing a TextTier in Praat")
NORMAL ("To edit a TextTier, first convert it into a @TextGrid. "
	"You invoke a @TextGridEditor in either of two ways:")
LIST_ITEM ("\\bu Select a TextGrid and click ##Edit#.")
LIST_ITEM ("\\bu Select a TextGrid and a @Sound and click ##Edit#.")
NORMAL ("In the latter case, a copy of the Sound object will be visible in the editor.")
NORMAL ("The @TextGridEditor will allow you to add marks to a TextTier object, "
	"move marks around, edit the texts in the marks, and remove marks.")
ENTRY ("Drawing a TextTier")
NORMAL ("You can draw a TextTier together with a Pitch object, "
	"by selecting one TextTier and one Pitch object, "
	"and choosing \"Draw...\". The mark texts will appear just above the pitch contour.")
ENTRY ("Class description")
NORMAL ("If you select a TextTier and click ##Inspect# or ##Write to console#, "
	" you will see that a TextTier object contains the following attributes:")
TAG ("%x__%min_")
DEFINITION ("the starting time.")
TAG ("%x__%max_")
DEFINITION ("the end of the time domain.")
TAG ("%points")
DEFINITION ("a collection of text points, sorted by their times.")
MAN_END

MAN_BEGIN ("TextTier: Add point...", "ppgb", 19980324)
INTRO ("A command to add a point to each selected @TextTier.")
ENTRY ("Arguments")
TAG ("%Time (s)")
DEFINITION ("the time at which a point is to be added.")
TAG ("%Text")
DEFINITION ("the text of the requested new point.")
ENTRY ("Behaviour")
NORMAL ("The tier is modified so that it contains the new point. "
	"If a point at the specified time was already present in the tier, nothing happens.")
MAN_END

MAN_BEGIN ("TextTier: Down to PointProcess", "ppgb", 20010410)
INTRO ("A command to degrade every selected @TextTier to a @PointProcess.")
ENTRY ("Behaviour")
NORMAL ("The times of all the text points are trivially copied, and so is the time domain. The text information is lost.")
MAN_END

MAN_BEGIN ("TextTier(s): To TextGrid", "ppgb", 19970317)
INTRO ("A command to merge all selected @TextTier objects into a new @TextGrid object.")
TAG ("You can also merge with @IntervalTier objects:")
LIST_ITEM ("@@TextTier(s) & IntervalTier(s): To TextGrid@")
MAN_END

MAN_BEGIN ("TextTier(s) & IntervalTier(s): To TextGrid", "ppgb", 19970317)
INTRO ("A command to merge all selected @TextTier and @IntervalTier objects into a new @TextGrid object.")
MAN_END

MAN_BEGIN ("Time selection", "ppgb", 20030216)
INTRO ("The ways to select a part of the time (or frequency) domain in some @Editors in the ##Praat program#, "
	"namely those that contain a function of time (or frequency).")
NORMAL ("The ##time selection# is used for selecting the time (or frequency) interval that will be played, "
	"copied, cut, modified, or questioned:")
ENTRY ("1. How to make a selection")
NORMAL ("The easiest way is to @drag the mouse across the part that you want to select. "
	"This is analogous to how selection works in a text processor.")
NORMAL ("Also see point 3 below.")
ENTRY ("2. How to extend or shrink a selection")
NORMAL ("The easiest way is to click with the Shift key pressed. "
	"The nearest edge of the selection will move to the time position where you clicked. "
	"This is analogous to how extending a selection works in a text processor.")
NORMAL ("For instance, if the currently selected time interval runs from 2 to 5 seconds, "
	"and you shift-click at a time position of 4 seconds, the end of the selection will move "
	"from 5 to 4 seconds, thus shrinking the selection.")
NORMAL ("You can also shift-drag, i.e. hold the Shift key and the mouse button down while moving the mouse.")
NORMAL ("Also see point 3 below.")
ENTRY ("3. How to move beginning and end separately")
NORMAL ("@@Click@ing with the %middle mouse button (on Mac: clicking while keeping the Option key pressed) "
	"inside the drawing area will move the \"B\" hair to the time where you click. "
	"\"B\" stands for %%Begin selection%.")
NORMAL ("Clicking with the %right mouse button (on Mac: clicking while keeping the Command key pressed) "
	"will move the \"E\" hair. \"E\" stands for %%End selection%.")
NORMAL ("If you use a left-hand mouse (on SGI: %%##Desktop - Customize - Mouse%#), "
	"the left button will be \"B\" and the middle button will be \"E\".")
NORMAL ("To move one of the marks to the other mark, or to an absolute or relative position, use the Select menu.")
MAN_END

MAN_BEGIN ("Vector peak interpolation", "ppgb", 20010410)
INTRO ("An algorithm for finding a maximum or a minimum in a sampled signal.")
ENTRY ("Overview")
NORMAL ("The signal is described with the sequence %y__%i_, %i = 1...%n, where %n is the number of samples. "
	"Each sample %i is associated with an %x value (typically, time) given by %x__%i_ = %x__1_ + (%i - 1) %dx, "
	"where %dx is the sample period.")
NORMAL ("The maximum is looked for in two kinds of locations:")
LIST_ITEM ("1. At the left and right edge, i.e. at %i = 1 and at %i = %n.")
LIST_ITEM ("2. At or %near all local maxima, i.e. at or %near those %i that satisfy %y__%i-1_ < %y__%i_ \\<_ %y__%i+1_.")
NORMAL ("The greatest of the following values, therefore, will be the maximum:")
LIST_ITEM ("1. %y__1_.")
LIST_ITEM ("2. The local maxima, which are at or %near %y__%i_, where %y__%i-1_ < %y__%i_ \\<_ %y__%i+1_.")
LIST_ITEM ("3. %y__%n_.")
NORMAL ("We will now see what %near means. The precision of the result depends on the %%interpolation method% of this algorithm.")
ENTRY ("1. Lowest precision: round to sample")
NORMAL ("If the interpolation method is None, the local maxima are %at the samples %m that satisfy %y__%m-1_ < %y__%m_ \\<_ %y__%m+1_. "
	"Thus, their %x values are at %x__%m_ = %x__1_ + (%m - 1) %dx, and their %y values are %y__%m_.")
NORMAL ("This kind of precision is appropriate for an unordered sequence of values %y__%i_: the result is simply the greatest available value.")
ENTRY ("2. Middle precision: parabolic interpolation")
NORMAL ("If the interpolation method is Parabolic, the algorithm uses one point on each side of every local maximum %y__%m_ "
	"to estimate the location and value of the local maximum. Because a Taylor expansion shows that any smooth curve "
	"can be approximated as a parabola in the vicinity of any local maximum, the location %x__%max_ and value %y__%max_ can be found "
	"with the following procedure:")
FORMULA ("%dy \\=3 1/2 (%y__%m+1_ - %y__%m-1_)")
FORMULA ("%d^2%y \\=3 2 %y__%m_ - %y__%m-1_ - %y__%m+1_")
FORMULA ("%m\\'p \\=3 %m + %dy/%d^2%y")
FORMULA ("%x__%max_ = %x__1_ + (%m\\'p - 1) %dx")
FORMULA ("%y__%max_ = %y__%m_ + 1/2 %dy^2 / %d^2%y")
NORMAL ("This kind of precision is appropriate if %y is considered a smooth function of %x, as in:")
LIST_ITEM ("@@Formant: Get minimum...")
LIST_ITEM ("@@Formant: Get time of minimum...")
LIST_ITEM ("@@Formant: Get maximum...")
LIST_ITEM ("@@Formant: Get time of maximum...")
LIST_ITEM ("@@Intensity: Get minimum...")
LIST_ITEM ("@@Intensity: Get time of minimum...")
LIST_ITEM ("@@Intensity: Get maximum...")
LIST_ITEM ("@@Intensity: Get time of maximum...")
ENTRY ("3. Higher precision: cubic interpolation")
NORMAL ("If the interpolation method is Cubic, the interpolation is performed over four points (see @@vector value interpolation@). "
	"The results are similar to those of the parabolic interpolation method, but you can use it (or sinc interpolation) if you want the result of a "
	"command like ##Get maximum...# to be equal to the result of a sequence of commands like "
	"##Get time of maximum...# and ##Get value at time...#.")
ENTRY ("4. Highest precision: sinc interpolation")
NORMAL ("If the interpolation method is Sinc70 or Sinc700, the algorithm assumes that the signal "
	"is a sum of sinc functions, so that a number of points (namely, 70 or 700) on each side of the initial guess %m must be taken into account "
	"(see @@vector value interpolation@). The algorithm finds the maximum of this continuous function by Brent's method (see @@Press et al. (1992)@).")
NORMAL ("This method is appropriate for signals that result from sampling a continuous signal after it has been low-pass filtered "
	"at the @@Nyquist frequency@. See:")
LIST_ITEM ("@@Sound: Get minimum...")
LIST_ITEM ("@@Sound: Get time of minimum...")
LIST_ITEM ("@@Sound: Get maximum...")
LIST_ITEM ("@@Sound: Get time of maximum...")
LIST_ITEM ("@@Sound: Get absolute extremum...")
MAN_END

MAN_BEGIN ("Vector value interpolation", "ppgb", 19980104)
INTRO ("An algorithm for estimating the value of a sampled signal at a specified location.")
ENTRY ("Overview")
NORMAL ("The signal is described with the sequence %y__%i_, %i = 1...%n, where %n is the number of samples. "
	"Each sample %i is associated with an %x location (typically, time) given by %x__%i_ = %x__1_ + (%i - 1) %dx, "
	"where %dx is the sample period, so that the real-valued sample number associated with a given time %x is")
FORMULA ("%s = (%x - %x__1_) / %dx + 1")
NORMAL ("If the resulting %s is an integer number, the %y value must be %y__%s_. Otherwise, the estimated %y value %y(%s) must be interpolated "
	"from nearby values of %y. The precision of the result depends on the %%interpolation method% of this algorithm.")
ENTRY ("1. Lowest precision: round to sample")
NORMAL ("If the interpolation method is Nearest, we take the value of the nearest point:")
FORMULA ("%near \\=3 round (%s)")
FORMULA ("%y(%s) \\~~ %y__%near_")
ENTRY ("2. Middle precision: linear interpolation")
NORMAL ("If you know or assume that the function that underlies your points is continuous, the \"rounding\" interpolation would be poor, "
	"because the rounded value would abruptly change at the centres between the sample points.")
NORMAL ("For a linear interpolation, therefore, we use the attested values on both sides (%left and %right) of %s:")
FORMULA ("%s__%l_ \\=3 floor (%s) ;   %s__%r_ \\=3 %s__%l_ + 1")
FORMULA ("%y(%s) \\~~ %y__%l_ + (%s - %s__%l_) \\.c (%y__%r_ - %y__%l_)")
NORMAL ("where #floor (%x) computes the greatest integer not greater than %x. This interpolation is continuous.")
ENTRY ("3. Higher precision: cubic interpolation")
NORMAL ("If you know or assume that the function that underlies your points is %smooth, i.e. its derivative is defined for every %x, "
	"linear interpolation would probably be poor, because the derivative of the interpolated function would abruptly change at every "
	"sample point.")
NORMAL ("The next higher interpolation (Cubic), therefore, is differentiable at sample points. To enforce this, we define the "
	"derivatives %y\\'p__%l_ and %y\\'p__%r_ at the left and right sample points on the basis of %their immediate neighbours "
	"(i.e., the algorithm needs four sample points), perhaps by a parabolic interpolation through these three points. "
	"A parabolic interpolation has the advantage that the extrema will be computed correctly if "
	"the underlying function can be approximated by a parabola near its extremes (see @@vector peak interpolation@).")
NORMAL ("Because the derivative of a parabolic function is a linear function of %x, "
	"the derivatives at the left and right sample points are simply estimated as")
FORMULA ("%y\\'p__%l_ \\~~ (%y__%r_ - %y__%l-1_) / 2 ;   %y\\'p__%r_ \\~~ (%y__%r+1_ - %y__%l_) / 2")
NORMAL ("Now that we know %y__%l_, %y__%r_, %y\\'p__%l_, and %y\\'p__%r_, we can fit these values with a "
	"third-degree (%cubic) polynomial:")
FORMULA ("%As__%l_^3 + %Bs__%l_^2 + %Cs__%l_ + %D = %y__%l_")
FORMULA ("%As__%r_^3 + %Bs__%r_^2 + %Cs__%r_ + %D = %y__%r_")
FORMULA ("3%As__%l_^2 + 2%Bs__%l_ + %C = %y\\'p__%l_")
FORMULA ("3%As__%r_^2 + 2%Bs__%r_ + %C = %y\\'p__%r_")
NORMAL ("If we shift the %x axis to the left sample point, we can reduce the four equations to")
FORMULA ("%D = %y__%l_")
FORMULA ("%A + %B + %C + %D = %y__%r_")
FORMULA ("%C = %y\\'p__%l_")
FORMULA ("3%A + 2%B + %C = %y\\'p__%r_")
NORMAL ("so that the interpolated value %y(%s) at any point %s between %s__%l_ and %s__%r_ is estimated as")
FORMULA ("(%y\\'p__%r_ + %y\\'p__%l_ - 2%y__%r_ + 2%y__%l_) %\\fi__%l_^3 + "
	"(3%y__%r_ - 3%y__%l_ - 2%y\\'p__%l_ - %y\\'p__%r_) %\\fi__%l_^2 + %y\\'p__%l_ %\\fi__%l_ + %y__%l_")
NORMAL ("where %\\fi__%l_ \\=3 %s - %s__%l_. Some rearrangement gives")
FORMULA ("%y(%s) \\~~ %y__%l_ %\\fi__%r_ + %y__%r_ %\\fi__%l_ +")
FORMULA ("- %\\fi__%l_ %\\fi__%r_ [1/2 (%y\\'p__%r_ - %y\\'p__%l_) + (%\\fi__%l_ - 1/2) "
	"(%y\\'p__%l_ + %y\\'p__%r_ - 2(%y__%r_ - %y__%l_))]")
NORMAL ("where %\\fi__%r_ \\=3 1 - %\\fi__%l_. From this formula we see:")
LIST_ITEM ("1. The first two terms define the linear interpolation.")
LIST_ITEM ("2. If the underlying function is linear, so that %y\\'p__%l_ equals %y\\'p__%r_ and both equal %y__%r_ - %y__%l_, "
	"the higher-degree terms are zero.")
LIST_ITEM ("3. If %y\\'p__%l_ + %y\\'p__%r_ equals 2(%y__%r_ - %y__%l_), the third-degree term is zero, "
	"so that the interpolated function is parabolic.")
LIST_ITEM ("4. At the left and right points, one of the %\\fi is 0 and the other is 1, so that at these boundary points, "
	"%y is computed with exact precision.")
ENTRY ("4. Highest precision: sinc interpolation")
NORMAL ("If the interpolation method is Sinc70 or Sinc700, the algorithm assumes that the signal "
	"is a sum of sinc functions, so that a number of points (the %%interpolation depth%: 70 or 700) on each side of %s must be taken into account.")
NORMAL ("Because the interpolation depth must be finite, the sum of sinc functions is multiplied by a Hanning window:")
FORMULA ("%s__%l_ \\=3 floor (%s);   %s__%r_ \\=3 %s__%l_ + 1")
FORMULA ("%\\fi__%l_ \\=3 %s - %s__%l_;   %\\fi__%r_ \\=3 1 - %\\fi__%l_")
FORMULA ("%y(%s) \\~~ \\su__%i=1...%N_ %y__%r-%i_ sinc (%\\pi(%\\fi__%l_+%i-1)) (1/2 + 1/2 cos (%\\pi(%\\fi__%l_+%i-1)/(%\\fi__%l_+%N))) +")
FORMULA ("+ \\su__%i=1...%N_ %y__%l+%i_ sinc (%\\pi(%\\fi__%r_+%i-1)) (1/2 + 1/2 cos (%\\pi(%\\fi__%r_+%i-1)/(%\\fi__%r_+%N)))")
NORMAL ("where the sinc function is defined as")
FORMULA ("sinc (0) \\=3 1;   sinc (%x) \\=3 sin %x / %x   for %x \\=/ 0")
NORMAL ("If %s is less than the interpolation depth or greater than %n + 1 minus the interpolation depth, "
	"the depth is reduced accordingly.")
NORMAL ("This method is appropriate for signals that result from sampling a continuous signal after it has been low-pass filtered "
	"at the @@Nyquist frequency@. See:")
LIST_ITEM ("@@Sound: Get value at time...")
MAN_END

MAN_BEGIN ("Wavelet", "ppgb", 20030316)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}. Undocumented.")
MAN_END

MAN_BEGIN ("WordList", "ppgb", 19991129)
INTRO ("One of the @@types of objects@ in P\\s{RAAT}. "
	"An object of class WordList contains a sorted list of strings in a system-independent format. "
	"WordList objects can be used for spelling checking after conversion to a @SpellingChecker object.")
ENTRY ("1. How to create a WordList object")
NORMAL ("You will normally create a WordList object by reading a binary WordList file. "
	"You'll use the generic @@Read from file...@ command from the Read menu.")
NORMAL ("See below under 3 for how to create such a file.")
ENTRY ("2. What you can do with a Wordlist object")
NORMAL ("The main functionality of a WordList is its ability to tell you whether it contains a certain string. "
	"If you select a WordList, you can query the existence of a specific word by using the ##Has word# "
	"command. You supply the word and press OK. If the WordList does contain the word, "
	"the value \"1\" will be written to the Info window; otherwise, the value \"0\" will be written.")
ENTRY ("3. How to create a binary WordList file")
NORMAL ("You can create a binary (compressed) WordList file from a simple text file that contains a long list of words. "
	"Perhaps such a text file has been supplied by a lexicographic institution in your country; "
	"because of copyright issues, such word lists cannot be distributed with the Praat program. "
	"To convert the simple text file into a compressed WordList file, you basically take the following steps:")
CODE ("Read Strings from raw text file... lexicon.iso")
CODE ("Genericize")
CODE ("Sort")
CODE ("To WordList")
CODE ("Write to binary file... lexicon.WordList")
NORMAL ("I'll explain these steps in detail. "
	"For instance, a simple text file may contain the following list of words:")
CODE ("cook")
CODE ("cooked")
CODE ("cookie")
CODE ("cookies")
CODE ("cooking")
CODE ("cooks")
CODE ("Copenhagen")
CODE ("K\\o/bnhavn")
CODE ("M\\u\"nchen")
CODE ("Munich")
CODE ("\\aongstr\\o\"m")
NORMAL ("These are just 11 words, but the procedure will work fine if you have a million of them, "
	"and enough memory in your computer.")
NORMAL ("You can read the file into a @Strings object with @@Read Strings from raw text file...@ "
	"from the Read menu in the Objects window. The resulting @Strings object contains 11 strings in the above order, "
	"as you can verify by viewing them with @Inspect.")
NORMAL ("In general, the Strings object will occupy a lot of memory, and be slow to read in. "
	"For instance, a certain list of more than 300,000 Dutch word forms occupies 3.6 MB on disk, "
	"and will occupy at least 7 MB of memory after it is read in. The extra 3.4 MB arise because the Strings object "
	"contains a pointer to each of the strings, and each of the strings is in a separately allocated part of "
	"the memory heap. Moreover, it takes 8 seconds on an average 1999 computer to read this object into memory. "
	"For these reasons, we will use the WordList object if we need a sorted list for spelling checking.")
NORMAL ("If you select the Strings, you can click the ##To WordList# button. "
	"However, you will get the following complaint:")
CODE ("String \"K\\o/bnhavn\" not generic. Please genericize first.")
NORMAL ("This complaint means that the strings are still in your computer's native text format, "
	"which is ISO-Latin1 for Unix and Windows computers, or Mac encoding for Macintosh computers.")
NORMAL ("So you press the #Genericize button. You can see that the Strings object changes to")
CODE ("cook")
CODE ("cooked")
CODE ("cookie")
CODE ("cookies")
CODE ("cooking")
CODE ("cooks")
CODE ("Copenhagen")
CODE ("K\\bso/bnhavn")
CODE ("M\\bsu\\\" nchen")
CODE ("Munich")
CODE ("\\bsaongstr\\bso\\\" m")
NORMAL ("The strings are now in the generic system-independent format that is used everywhere in Praat "
	"to draw strings (see @@Special symbols@).")
NORMAL ("You can again try to click the ##To WordList# button. However, you will get a complaint again:")
CODE1 ("String \"Copenhagen\" not sorted. Please sort first.")
NORMAL ("This complaint means that the strings have not been sorted in ASCII sorting order. "
	"So you click #Sort, and the Strings object becomes:")
CODE ("Copenhagen")
CODE ("K\\bso/bnhavn")
CODE ("M\\bsu\\\" nchen")
CODE ("Munich")
CODE ("\\bsaongstr\\bso\\\" m")
CODE ("cook")
CODE ("cooked")
CODE ("cookie")
CODE ("cookies")
CODE ("cooking")
CODE ("cooks")
NORMAL ("The strings are now in the ASCII order, in which capitals come before lower-case letters, "
	"and backslashes come in between these two series.")
NORMAL ("Clicking ##To WordList# now succeeds, and a WordList object appears in the list. "
	"If you write it to a text file (with the Write menu), you will get the following file:")
CODE ("File type = \"ooTextFile\"")
CODE ("Object class = \"WordList\"")
CODE ("")
CODE ("string = \"Copenhagen")
CODE ("K\\bso/bnhavn")
CODE ("M\\bsu\\\" \\\" nchen")
CODE ("Munich")
CODE ("\\bsaongstr\\bso\\\" \\\" m")
CODE ("cook")
CODE ("cooked")
CODE ("cookie")
CODE ("cookies")
CODE ("cooking")
CODE ("cooks\\\"r")
NORMAL ("Note that the double quotes (\\\" ) that appear inside the strings, have been doubled, "
	"as is done everywhere inside strings in Praat text files.")
NORMAL ("After you have created a WordList text file, you can create a WordList object just by reading this file "
	"with @@Read from file...@ from the Read menu.")
NORMAL ("The WordList object has two advantages over the Strings object. First, it won't take up more "
	"memory than the original word list. This is because the WordList is stored as a single string: "
	"a contiguous list of strings, separated by new-line symbols. Thus, our 300,000-word list "
	"will take up only 3.6 MB, and be read in 4 seconds.")
NORMAL ("However, disk storage and reading can again be improved by compressing the word list. "
	"We can take advantage of the sorting, by noting for each entry how many leading characters "
	"are equal to those of the previous entry. The list then becomes something equivalent to")
CODE ("Copenhagen")
CODE ("0 K\\bso/bnhavn")
CODE ("0 M\\bsu\\\" nchen")
CODE ("1 unich")
CODE ("0 \\bsaongstr\\bso\\\" m")
CODE ("0 cook")
CODE ("4 ed")
CODE ("4 ie")
CODE ("6 s")
CODE ("5 ng")
CODE ("4 s")
NORMAL ("You can write the WordList compressed in this way to a binary file with "
	"@@Write to binary file...@. For our 300,000-word list, this file takes up only 1.1 MB "
	"and can be read into memory (with @@Read from file...@) in a single second. "
	"When read into memory, the WordList object is again expanded to 3.6 MB to allow rapid searching.")
MAN_END

/*
longSound = selected ("LongSound")
longSoundNaam$ = selected$ ("LongSound")
textGrid = selected ("TextGrid")
select 'textGrid'
aantalIntervallen = Get number of intervals... 1
for interval to aantalIntervallen
   select 'textGrid'
   begintijd = Get starting point... 1 interval
   eindtijd = Get end point... 1 interval
   select 'longSound'
   Extract part... begintijd eindtijd no
   Write to WAV file... C:\Geluiden\'longSoundNaam$'_'interval'.wav
   Remove
endfor


# This is a Praat script that assumes that a single TextGrid is selected,
# and that the data in the first (or only) tier is in the form
# silence-text-silence-text and so on. The script will then write
# the durations of the silences and the texts into the Info window.

form Tabulate speech and silences
   comment Give the output file name:
   text fileName c:\windows\desktop\kim\out.txt
endform

# The following line provides the header,
# separated by tabs for easy inclusion in Excel.
echo Pause'tab$'Speech'tab$'Text

# Every next line writes three pieces of data,
# separated by tabs again.

# The following is a command from the Query submenu
# that appears when you select a TextGrid object.
numberOfIntervals = Get number of intervals... 1

# The number of silence-speech pairs is half of that number,
# disregarding any silence at the end.
numberOfPairs = numberOfIntervals div 2

# Cycle through all the silence-speech pairs.

for pair to numberOfPairs
   silenceInterval = 2 * pair - 1   ; interval 1, 3, 5, and so on
   speechInterval = 2 * pair   ; interval 2, 4, 6, and so on
   # Check that the silence interval is indeed empty.
   silenceText$ = Get label of interval... 1 silenceInterval
   if silenceText$ <> ""
      exit Interval 'silenceInterval' should be a silence, but isn't.
   endif
   # Also check that the speech interval contains some text.
   speechText$ = Get label of interval... 1 speechInterval
   if speechText$ = ""
      exit Interval 'speechInterval' should contain text, but doesn't.
   endif
   # So now we have checked that the intervals contain the data
   # that Kim wanted them to contain. We're ready to write the data!
   silenceBegin = Get starting point... 1 silenceInterval
   silenceEnd = Get end point... 1 silenceInterval
   silenceDuration_ms = (silenceEnd - silenceBegin) * 1000
   speechBegin = Get starting point... 1 speechInterval
   speechEnd = Get end point... 1 speechInterval
   speechDuration_ms = (speechEnd - speechBegin) * 1000
   printline 'silenceDuration_ms:0''tab$'
   ...'speechDuration_ms:0''tab$'
   ...'speechText$'
endfor
filedelete 'fileName$'
fappendinfo 'fileName$'

*/

/* pitch measurements: medians instead of averages */

}

/* End of file manual_Fon.c */
