X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=guile18%2Fdoc%2Fsources%2Fold-intro.texi;fp=guile18%2Fdoc%2Fsources%2Fold-intro.texi;h=0774f64d40547198254e4d055bbce622d3c1bc0e;hb=139c38d9204dd07f6b235f83bae644faedbc63fd;hp=0000000000000000000000000000000000000000;hpb=652ed35a2013489d0a14fede6307cd2595abb2c4;p=lilypond.git

diff --git a/guile18/doc/sources/old-intro.texi b/guile18/doc/sources/old-intro.texi
new file mode 100644
index 0000000000..0774f64d40
--- /dev/null
+++ b/guile18/doc/sources/old-intro.texi
@@ -0,0 +1,290 @@
+@node Introduction
+@chapter Introduction
+
+Guile is an interpreter for Scheme, a clean, economical programming
+language in the Lisp family.  You can invoke Guile from the shell to
+evaluate Scheme expressions interactively, or use it as an interpreter
+for script files.  However, Guile is also packaged as a library, to be
+embedded as an extension language into other applications.  The
+application can supplement the base language with special-purpose
+functions and datatypes, allowing the user to customize and extend it by
+writing Scheme code.
+
+In its simplest form, Guile is an ordinary interpreter.  The
+@code{guile} program can read and evaluate Scheme expressions entered
+from the terminal.  Here is a sample interaction between Guile and a
+user; the user's input appears after the @code{$} and @code{guile>}
+prompts:
+
+@example
+$ guile
+guile> (+ 1 2 3)                ; add some numbers
+6
+guile> (define (factorial n)    ; define a function
+         (if (zero? n) 1 (* n (factorial (- n 1)))))
+guile> (factorial 20)
+2432902008176640000
+guile> (getpwnam "jimb")        ; find my entry in /etc/passwd
+#("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb"
+  "/usr/local/bin/bash")
+guile> @kbd{C-d}
+$
+@end example
+
+Guile can also interpret script files.  For example, here is a Guile script
+containing a script which displays the 
+
+
+application can
+supplement the base language with its own functions, datatypes and
+syntax, allowing the user to extend and 
+
+
+ Guile interpret
+
+.  An
+application the Guile interpreter to allow 
+
+
+, allowing
+applications to incorporate the Scheme interpreter for customization
+
+[[interactive]]
+[[script interpreter]]
+[[embedded]]
+
+[[other languages]]
+The concept of an extension language library does not originate with
+Guile.  However, Guile is the first to offer users a choice of languages
+to program in.  
+
+
+Guile currently supports Scheme and Ctax , and we expect to support Emacs Lisp in the near future.  
+
+
+Scheme is powerful enough that other languages can be
+conveniently translated into it, 
+
+However, unlike other extension packages, Guile gives users a choice of
+languages to program in.  Guile can 
+
+
+In this sense, Guile resembles the Tcl and Python packages, providing
+both an ordinary interpreter and an extension language library.
+However, unlike those packages, Guile supports more than one programming
+language.  
+
+; users can
+write Scheme code to control and customize applications which
+incorporate Guile
+
+, adding their own functions,
+datatypes, and syntax, to allow the user to programm
+
+
+link it into your own programs to make them
+
+
+
+Guile is a library containing an interpreter for Scheme, a complete but
+economical programming language, which the developer can customize to
+suit the application at hand by adding new functions, data types, and
+control structures.  These may be implemented in C, and then
+``exported'' for use by the interpreted code.  Because Guile already
+provides a full-featured interpreter, the developer need not neglect the
+language's design in order to concentrate on code relevant to the task.
+In this way, Guile provides a framework for the construction of
+domain-specific languages.
+
+Guile provides first-class functions, a rich set of data types,
+exception handling, a module system, and a powerful macro facility.
+Guile also supports dynamic linking and direct access to Unix system
+calls.  Releases in the near future will support a source-level
+debugger and bindings for the Tk user interface toolkit.
+
+
+
+Guile is a framework for writing applications controlled by specialized
+languages.  In its simplest form, Guile is an interpreter for Scheme, a
+clean, economical programming language in the Lisp family.  However,
+Guile is packaged as a library, allowing applications to link against it
+and use Scheme as their extension language.  The application can add
+primitive functions to the language, implement new data types, and even
+adjust the language's syntax.
+
+
+
+[the introduction is probably not what Jim has in mind; I just took the
+one I had in earlier, since the file had the same name intro.texi]
+
+Guile is an implementation of the Scheme programming language, but, like
+other modern implementations of Scheme, it adds many features that the
+community of Scheme programmers considers necessary for an ``industrial
+strength'' language.
+
+Examples of extensions to Scheme are the module system
+(@pxref{Modules}), the Unix system programming tools (@pxref{POSIX
+system calls and networking} and @pxref{The Scheme shell (scsh)}), an
+interface to @emph{libtool} to make it easier to add C libraries as
+primitives (@pxref{Linking Guile with your code}), and (FIXME add more).
+
+On top of these extensions, which many other Scheme implementations
+provide, Guile also offers the possibility of writing routines in other
+languages and running them simultaneously with Scheme.  The desire to
+implement other languages (in particular Emacs Lisp) on top of Scheme is
+responsible for Guile's only deviation from the R4RS @footnote{R4RS is
+the Revised^4 Report on the Algorithmic Language Scheme, the closest
+thing to a standard Scheme specification today} Scheme standard
+(@cite{r4rs}): Guile is case sensitive, whereas ``standard'' Scheme is
+not.
+
+But even more fundamentally, Guile is meant to be an @emph{embeddable}
+Scheme interpreter.  This means that a lot of work has gone into
+packaging the interpreter as a C library (@pxref{A Portable C to Scheme Interface} and @pxref{Scheme data representation}).
+
+This reference manual is mainly driven by the need to document all the
+features that go beyond standard Scheme.
+
+@menu
+* Getting started::             
+* Guile feature list::          
+* What you need to use Guile::  
+* Roadmap to the Manual::       
+* Motivation for Guile::        
+* History of Guile::            
+@end menu
+
+@node Getting started
+@section Getting started
+
+We assume that you know how to program in Scheme, although we do not
+assume advanced knowledge.  If you don't know Scheme, there are many
+good books on Scheme at all levels, and the Guile Tutorial might give
+you a good enough feel for the language.  We also assume that you know
+how to program in C, since there will be many examples of how to program
+in C using Guile as a library.
+
+Many diverse topics from the world of Unix hacking will be covered here,
+such as shared libraries, socket programming, garbage collection, and so
+forth.  If at any time you feel you don't have enough background on a
+given topic, just go up a level or two in the manual, and you will find
+that the chapter begins with a few paragraphs that introduce the topic.
+If you are still lost, read through the Guile tutorial and then come
+back to this reference manual.
+
+To run the core Guile interpreter and extension library you need no more
+than a basically configured GNU/Unix system and the Guile sources.  You
+should download and install the Guile sources (@pxref{Obtaining and
+Installing Guile}).
+
+
+@node Guile feature list
+@section Guile feature list
+
+In a reductionist view, Guile could be regarded as:
+@itemize @bullet
+@item
+An R4RS-compliant Scheme interpreter.
+
+@item
+Some Scheme features that go beyond the R4RS standard, notably a module
+system, exception handling primitives and an interface to Aubrey
+Jaffer's SLIB.
+
+@item
+A symbolic debugger for Scheme, and gdb extensions to facilitate
+debugging libguile programs.
+
+@item
+An embeddable version of the same interpreter, called @emph{libguile}.
+
+@item
+A portable high level API on top of libguile (the @code{gh_} interface).
+
+@item
+A collection of bundled C libraries with a Guile API.  As we write, this
+list includes:
+
+@table @strong
+@item Rx
+a regular expression library.
+
+@item Unix
+a low-level interface to the POSIX system calls, socket library
+and other Unix system services.
+
+@item Tk
+an interface to John Ousterhout's Tk toolkit.
+
+@end table
+
+@item
+A set of tools for implementing other languages @emph{on top of Scheme},
+and an example implementation of a language called @emph{Ctax}.
+
+
+@end itemize
+
+
+@node What you need to use Guile
+@section What you need to use Guile
+
+
+@node Roadmap to the Manual
+@section Roadmap to the Manual
+
+@node Motivation for Guile
+@section Motivation for Guile
+
+@node History of Guile
+@section History of Guile
+
+@page
+@node Using Guile
+@chapter Using Guile
+
+[I think that this might go in the appendix in Jim's view of the manual]
+
+@page
+@node Invoking Guile
+@appendix Invoking Guile
+        --- mentions read-eval-print loops
+	--- both the SCSH and GAWK manuals relegate invocation details
+            to an appendix.  We can give examples in the introduction.
+
+@table @samp
+@item -h
+@itemx --help
+Display a helpful message.
+@item -v
+@item --version
+Display the current version.
+@item --emacs
+To be used for emacs editing support.
+@item -s @var{file}
+Process @var{file} as a script then quit.  This is a terminating option:
+any further command line arguments can be accessed by the script using
+the @code{(program-arguments)} procedure.
+
+An executable script can start with the following:
+
+@smallexample
+#!/usr/bin/guile -s
+!#
+@end smallexample
+
+Note the @code{!#} token on the second line.  It is very important
+to include this token when writing Guile scripts.  Guile and SCSH,
+the Scheme shell, share the convention that @code{#!}  and
+@code{!#} may be used to mark block comments (@pxref{Block
+comments and interpreter triggers}).  If the closing @code{!#}
+token is not included, then Guile will consider the block comment
+to be unclosed, and the script will probably not compile
+correctly.
+
+It is also important to include the @samp{-s} option at the
+beginning of the Guile script, so that Guile knows not to behave
+in an interactive fashion.
+
+@end table
+