/* manual_programming.c */
/* by Paul Boersma */

#include "ManPagesM.h"

void manual_programming_init (ManPages me);
void manual_programming_init (ManPages me) {

MAN_BEGIN ("Programming with Praat", "ppgb", 20020526)
INTRO ("You can extend the functionality of the @@Praat program@ or just the @@Praat shell@ "
	"by adding modules written in C to it.")
ENTRY ("1. Warning")
NORMAL ("Before trying the task of learning how to write Praat extensions, "
	"you should be well aware of the possibilities of @scripting. "
	"Many built-in commands in the Praat program have started their "
	"lives as Praat scripts, and scripts are easier to write than C extensions.")
ENTRY ("2. Getting the existing source code")
NORMAL ("You obtain the Praat source code via ##www.praat.org#, perhaps in the file "
	"##praat3.8.75_sources.tar.gz#, and unpack this with #gunzip and ##tar xvf# "
	"(on Unix), or ##StuffIt^\\re Expander^\\tm# (on Macintosh), "
	"or ##Aladdint^\\re Expander^\\tm# (on Windows). The result will be a set of directories "
	"called #ipa, #sys, #dwsys, #fon, #dwtools, #LPC, #FFNet, #artsynth, #main, and #makefiles, "
	"plus a makefile and Codewarrior projects for Macintosh and Windows.")
ENTRY ("3. Building Praat on Unix")
NORMAL ("To compile and link #Praat on Unix, you go to the directory that "
	"contains the source directories and the makefile, and copy a ##makefile.defs# "
	"file from the #makefiles directory. On Linux, for instance, you type")
CODE ("> cp makefiles/makefile.defs.linux ./makefile.defs")
NORMAL ("The file ##makefile.defs# may require some editing after this, "
	"since you may prefer dynamic instead of static linking, or the libraries "
	"in your Linux distribution are different than in mine, or your Motif library (Xm.a "
	"or Xm.so) is in a different location. On Silicon Graphics Irix, you will use "
	"##makefile.defs.sgi#; on Sparc Solaris, you will probably use "
	"##makefile.defs.solaris.cde#; on HPUX, you will use ##makefile.defs.hpux#; "
	"on Intel Solaris, ##makefile.defs.solaris.cde.up.ac#.")
NORMAL ("Praat has to be linked with a real Motif version (%not Lesstif), "
	"i.e., there must be a library Xm.so or Xm.a and an Xm include directory. "
	"Fortunately, there is now a free Motif library for Linux "
	"(##openmotif-devel-2.1.30-1_ICS.i386.rpm# from ICT); "
	"on SGI, Solaris, and HPUX, Motif libraries are included with the system, "
	"and the include directory comes with the development package.")
ENTRY ("4. Building Praat on Macintosh")
NORMAL ("Unpack ##main/praat_mac.rsrc.sit# to ##main/praat_mac.rsrc#. "
	"Then open ##praatmac.mcp# in CodeWarrior (version 7.0 or higher) and choose Make or Run.")
ENTRY ("5. Building Praat on Windows")
NORMAL ("Go to the directory #win_pch, then open ##win_pch.mcp# in CodeWarrior (version 7.0 or higher) "
	"and choose Make. This will create the precompiled header file ##win_pch.mch#."
	"Then open ##praatmac.mcp# in CodeWarrior and choose Make or Run.")
NORMAL ("Praat may compile under Visual C++ as well.")
ENTRY ("6. Extending Praat")
NORMAL ("You can edit ##main/main_Praat.c#. "
	"This example shows you how to create a very simple program with all the functionality "
	"of the Praat program, and a single bit more:")
CODE ("\\# include \"praat.h\"")
CODE ("")
CODE ("DIRECT (HelloFromJane)")
CODE1 ("Melder_information (\"Hello, I am Jane.\");")
CODE ("END")
CODE ("")
CODE ("void main (int argc, char **argv) {")
CODE1 ("praat_init (\"Praat_Jane\", argc, argv);")
CODE1 ("INCLUDE_LIBRARY (praat_uvafon_init)")
CODE1 ("praat_addMenuCommand (\"Objects\", \"Control\", \"Hello from Jane...\", NULL, 0, DO_HelloFromJane);")
CODE1 ("praat_run ();")
CODE1 ("return 0;")
CODE ("}")
ENTRY ("7. Learning how to program")
NORMAL ("To see how objects are defined, take a look at ##sys/Thing.h#, ##sys/Data.h#, "
	"##sys/oo.h#, the ##XXX_def.h# files in the #fon directory, and the corresponding "
	"##XXX.c# files in the #fon directory. To see how commands show up on the buttons "
	"in the fixed and dynamic menus, take a look at the large interface description file "
	"##fon/praat_Fon.c#.")
ENTRY ("8. Using the Praat shell only")
NORMAL ("For building the Praat shell only, you need only the code in the three directories "
	"#ipa, #sys, and #dwsys. You delete the inclusion of praat_uvafon_init from #main. "
	"You will be able to build a Praat shell, i.e. an Objects and a Picture window, "
	"which has no knowledge of the world, i.e., which does not know any objects "
	"that can be included in the list of objects. You could use this Praat shell "
	"for modelling your own world and defining your own classes of objects.")
MAN_END

}

/* End of file manual_Prog.c */
