<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [

<!--

Process this file with an XSLT processor: `xsltproc \
-''-nonet /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/\
manpages/docbook.xsl manpage.dbk'.  A manual page
<package>.<section> will be generated.  You may view the
manual page with: nroff -man <package>.<section> | less'.  A
typical entry in a Makefile or Makefile.am is:

DB2MAN=/usr/share/sgml/docbook/stylesheet/xsl/nwalsh/\
manpages/docbook.xsl
XP=xsltproc -''-nonet

manpage.1: manpage.dbk
        $(XP) $(DB2MAN) $<

The xsltproc binary is found in the xsltproc package.  The
XSL files are in docbook-xsl.  Please remember that if you
create the nroff version in one of the debian/rules file
targets (such as build), you will need to include xsltproc
and docbook-xsl in your Build-Depends control field.

-->

  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
  <!ENTITY dhfirstname "<firstname>Rafael</firstname>">
  <!ENTITY dhsurname   "<surname>Laboissiere</surname>">
  <!-- Please adjust the date whenever revising the manpage. -->
  <!ENTITY dhdate      "<date>April 22, 2013</date>">
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
       allowed: see man(7), man(1). -->
  <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
  <!ENTITY dhemail     "<email>rafael@laboissiere.net</email>">
  <!ENTITY dhusername  "Rafael Laboissiere">
  <!ENTITY dhucpackage "<refentrytitle>SENDPRAAT</refentrytitle>">
  <!ENTITY dhpackage   "sendpraat">

  <!ENTITY debian      "Debian">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
]>

<refentry>
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    <author>
      &dhfirstname;
      &dhsurname;
    </author>
    <copyright>
      <year>2003</year>
      <holder>&dhusername;</holder>
    </copyright>
    &dhdate;
  </refentryinfo>
  <refmeta>
    &dhucpackage;
    &dhsection;
    <refmiscinfo class="manual">User Commands</refmiscinfo>
    <refmiscinfo class="source">Praat</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>&dhpackage;</refname>

    <refpurpose>doing phonetics by computer</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>&dhpackage;</command>
      <arg choice="opt">
        <replaceable class="parameter">timeOut</replaceable>
      </arg>
      <arg choice="req">
         <replaceable class="parameter">program</replaceable>
      </arg>
      <arg choice="req" rep="repeat">
        <replaceable class="parameter">message</replaceable>
      </arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>

    <para>This manual page documents the <command>&dhpackage;</command>
    command. It was written for the &debian; distribution because the
    original program does not have a manual page.</para>

    <para><command>&dhpackage;</command> is a program for sendings messages
    to a running program that uses the Praat shell, like
    <citerefentry><refentrytitle>praat</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
    </para>

  </refsect1>

  <refsect1>
    <title>ARGUMENTS</title>

    <variablelist>
      <varlistentry>
        <term><replaceable class="parameter">program</replaceable></term>
        <listitem>
          <para>
            the name of a running program that uses the Praat shell.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><replaceable class="parameter">message ...</replaceable></term>
        <listitem>
          <para>
            a sequence of Praat shell lines (commands and directives).
            Each line is a separate argument.  Lines that contain spaces
            should be put inside double quotes.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><replaceable class="parameter">timeOut</replaceable></term>
        <listitem>
          <para>
            the number of seconds that sendpraat will wait for an answer
            before writing an error message. A <replaceable
            class="parameter">timeOut</replaceable> of 0 means that the
            message will be sent asynchronously, i.e., that sendpraat will
            return immediately without issuing any error message.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>EXAMPLES</title>

    <programlisting>sendpraat 0 praat Quit</programlisting>
    
    <para>Causes the program <command>praat</command> to quit
    (gracefully).  This works because "Quit" is a fixed command in
    Praat's Control menu.  Sendpraat will return immediately.</para>    
    
    <programlisting>sendpraat 1000 praat "Play reverse"</programlisting>
    
    <para>Causes the program <command>praat</command>, which can play
    sounds, to play the selected Sound objects backwards.  This works
    because "Play reverse" is an action command that becomes available in
    Praat's dynamic menu when Sounds are selected.  Sendpraat will allow
    "praat" at most 1000 seconds to perform this.</para>
    
    <programlisting>sendpraat praat "execute ~/MyResearch/MyProject/MyScript.praat"</programlisting>
    
    <para>Causes the program "praat" to execute a script.  Sendpraat will
    allow <command>praat</command> at most 10 seconds (the default time
    out).</para>
    
    <programlisting>sendpraat als "for i from 1 to 5" "Draw circle... 0.5 0.5 0.1*i" "endfor"</programlisting>
    
    <para>Causes the program <command>als</command> to draw five concentric
    circles into its Picture window.</para>
    
  </refsect1>

  <refsect1>
    <title>AUTHOR</title>

    <para>This manual page was written by &dhusername; &lt;&dhemail;&gt; for
    the &debian; system (but may be used by others).  It was based on
    the information provided by the help message of the
    <command>&dhpackage;</command> program itself. Permission is
    granted to copy, distribute and/or modify this document under the
    terms of the &gnu; General Public License, Version 3 any later
    version published by the Free Software Foundation.</para>
    
    <para>On Debian systems, the complete text of the GNU General Public
    License can be found in /usr/share/common-licenses/GPL-3.</para>

  </refsect1>

  <refsect1>

    <title>SEE ALSO</title>

    <para>For further information, see the Praat website
    (http://www.praat.org).</para>

  </refsect1>

</refentry>

