new-doc: iteration

src/doc/new-doc/Makefile

@@ -15,7 +15,7 @@ ecldoc.info: $(FILES)
 	makeinfo new-doc.txi
 
 new-doc.html: $(FILES)
-	makeinfo --html --css-include=ecl.css --no-split new-doc.txi
+	makeinfo --html --css-include=ecl.css --split=chapter new-doc.txi
 
 clean:
 	rm -rf *.{aux,cf,cfs,cp,cpp,cpps,cps,ex,exs,fn,fns,ft,fts,log,lsp,lsps,toc,tp,tps,vr,vrs,pdf,info,html}

src/doc/new-doc/developer-guide/objects.txi

@@ -2,15 +2,8 @@
 @section Manipulating Lisp objects
 
 @menu
-* Integers (dev)::
-* Characters (dev)::
-* Arrays (dev)::
-* Strings (dev)::
-* Bit-vectors (dev)::
-* Streams (dev)::
-* Structures (dev)::
-* Instances (dev)::
-* Bytecodes (dev)::
+* Objects representation::
+* Constructing objects::
 @end menu
 
 If you want to extend, fix or simply customize ECL for your own needs,
@@ -22,6 +15,7 @@ you should understand how the implementation works.
 Union containing all first-class ECL types.
 @end deftp
 
+@node Objects representation
 @subsection Objects representation
 In ECL a lisp object is represented by a type called
 @code{cl_object}. This type is a word which is long enough to host both
@@ -250,7 +244,7 @@ calls to @code{ecl_t_of}.
 Tells whether @var{x} is an immediate datatype.
 @end deftypefun
 
-
+@node Constructing objects
 @subsection Constructing objects
 
 On each of the following sections we will document the standard
@@ -290,8 +284,7 @@ cl_object array2 = string_to_object(string);
 @end example
 @end deftypefun
 
-@node Integers (dev)
-@subsection Integers
+@subheading Integers
 Common-Lisp distinguishes two types of integer types: @code{bignum}s and
 @code{fixnum}s. A fixnum is a small integer, which ideally occupies only
 a word of memory and which is between the values
@@ -372,8 +365,7 @@ appropriate size. Signals an error if @var{o} is not of fixnum type.
 @code{fixnint} additionally ensure that @var{o} is not negative.
 @end deftypefun
 
-@node Characters (dev)
-@subsection Characters
+@subheading Characters
 
 @cfindex --enable-unicode (YES|no|32)
 
@@ -450,8 +442,7 @@ of case and @code{char_compare} converts all characters to uppercase
 before comparing them.
 @end deftypefun
 
-@node Arrays (dev)
-@subsection Arrays
+@subheading Arrays
 
 An array is an aggregate of data of a common type, which can be accessed
 with one or more non-negative indices. ECL stores arrays as a C structure
@@ -594,8 +585,7 @@ cl_print(1, array); /* Outputs #(1 2 3 5) */
 @end example
 @end deftypefun
 
-@node Strings (dev)
-@subsection Strings
+@subheading Strings
 
 A string, both in Common-Lisp and in ECL is nothing but a vector of
 characters. Therefore, almost everything mentioned in the section of
@@ -632,16 +622,14 @@ Verifies if an objects is an extended or base string. If Unicode isn't
 supported, then @code{ECL_EXTENDED_STRING_P} always returns 0.
 @end deftypefun
 
-@node Bit-vectors (dev)
-@subsection Bit-vectors
+@subheading Bit-vectors
 
 Bit-vector operations are implemented in file
 @code{src/c/array.d}. Bit-vector shares the structure with a vector,
 therefore, almost everything mentioned in the section of arrays remains
 valid here.
 
-@node Streams (dev)
-@subsection Streams
+@subheading Streams
 
 Streams implementation is a broad topic. Most of the implementation is
 done in the file @code{src/c/file.d}. Stream handling may have different
@@ -712,8 +700,7 @@ Predicate determining if @code{o} is a first-class stream
 object of type @code{m}.
 @end deftypefun
 
-@node Structures (dev)
-@subsection Structures
+@subheading Structures
 
 Structures and instances share the same datatype @code{t_instance} (
 with a few exceptions. Structure implementation details are the file
@@ -732,8 +719,7 @@ with a few exceptions. Structure implementation details are the file
 Convenience functions for the structures.
 @end deftypefun
 
-@node Instances (dev)
-@subsection Instances
+@subheading Instances
 
 @cppindex ECL_CLASS_OF
 @cppindex ECL_SPEC_FLAG
@@ -757,8 +743,7 @@ Convenience functions for the structures.
 Convenience functions for the structures.
 @end deftypefun
 
-@node Bytecodes (dev)
-@subsection Bytecodes
+@subheading Bytecodes
 
 A bytecodes object is a lisp object with a piece of code that can be
 interpreted. The objects of type t_bytecode are implicitly constructed

src/doc/new-doc/developer-guide/removed.txi

@@ -11,7 +11,7 @@
 @c @end menu
 
 @c @node In-house DFFI
-@subsection In-house DFFI
+@subheading In-house DFFI
 
 Commit @code{10bd3b613fd389da7640902c2b88a6e36088c920}. Native DFFI was
 replaced by a @code{libffi} long time ago, but we have maintained the
@@ -19,7 +19,7 @@ code as a fallback. Due to small number of supported platforms and no
 real use it has been removed in 2016.
 
 @c @node In-house GC
-@subsection In-house GC
+@subheading In-house GC
 Commit @code{61500316b7ea17d0e42f5ca127f2f9fa3e6596a8}.  Broken GC is
 replaced by BoehmGC library. This may be added back as a fallback in
 the near future.
@@ -28,30 +28,30 @@ the near future.
 (apparently gbc.d wasn't bdwgc glue).
 
 @c @node Green threads
-@subsection Green threads
+@subheading Green threads
 Commit @code{41923d5927f31f4dd702f546b9caee74e98a2080}. Green threads
 (aka light weight processes) has been replaced with native threads
 implementation. There is an ongoing effort to bring them back as an
 alternative interface.
 
 @c @node Compiler newcmp
-@subsection Compiler newcmp
+@subheading Compiler newcmp
 Commit @code{9b8258388487df8243e2ced9c784e569c0b34c4f} This was
 abandoned effort of changing the compiler architecture. Some clever
 ideas and a compiler package hierarchy. Some of these things should be
 incorporated during the evolution of the primary compiler.
 
-@subsection Old MIT loop
+@subheading Old MIT loop
 Commit @code{5042589043a7be853b7f85fd7a996747412de6b4}. This old loop
 implementation has got superseeded by the one incorporated from
 Symbolics LOOP in 2001.
 
-@subsection Support for bignum arithmetic (earith.d)
+@subheading Support for bignum arithmetic (earith.d)
 Commit @code{edfc2ba785d6a64667e89c869ef0a872d7b9704b}. Removes
 pre-gmp bignum code. Name comes probably from ``extended arithmetic'',
 contains multiplication and division routines (assembler and a
 portable implementation).
 
-@subsection Unification module
+@subheading Unification module
 Commit @code{6ff5d20417a21a76846c4b28e532aac097f03109}. Old unifiction
 module (logic programming) from EcoLisp times.

src/doc/new-doc/extensions/ffi.txi

@@ -195,7 +195,7 @@ UFFI and the CFFI library.
 @c XXX: we should describe here, how to use SFFI for interactive C/C++ development
 @c @node Lower level interfaces
 
-@subsubsection UFFI example
+@subsubheading UFFI example
 @exindex UFFI usage
 
 The example below shows how to use UFFI in an application. There are several important
@@ -235,7 +235,7 @@ Build and load this module with (compile-file "uffi.lsp" :load t)
 	(sin 1.0d0) (c-sin 1.0d0) (- (sin 1.0d0) (c-sin 1.0d0)))
 @end lisp
 
-@subsubsection CFFI example
+@subsubheading CFFI example
 @exindex CFFI usage
 
 The CFFI library is an independent project and it is not shipped with
@@ -275,7 +275,7 @@ Build and load this module with (compile-file "cffi.lsp" :load t)
 	(cos 1.0d0) c-cos (- (cos 1.0d0) c-cos)))
 @end lisp
 
-@subsubsection SFFI example (low level inlining)
+@subsubheading SFFI example (low level inlining)
 @exindex SFFI usage
 
 To compare with the previous pieces of code, we show how the previous programs would be

src/doc/new-doc/introduction/index.txi

@@ -2,12 +2,11 @@
 @unnumbered Introduction
 
 @menu
-* About this book::
-* What is ECL::
-* History::
-* Credits::
-* Copyrights::
-* Sandbox::
+* About this book:: Information about the manual
+* What is ECL:: Information about the implementation
+* History:: ECL from the history perspective
+* Credits:: Non-exhaustive list of contributors
+* Copyrights:: Copyright of the manual and implementation
 @end menu
 
 @include introduction/about_man.txi
@@ -15,16 +14,3 @@
 @include introduction/history.txi
 @include introduction/credits.txi
 @include introduction/copyrights.txi
-
-@node Sandbox
-@section Sandbox
-
-@defun funkcja arg1 arg2 arg3
-This is my defun
-@end defun
-
-@lspindex *ignore-eof-on-terminal-io*
-@defvr {System} {*ignore-eof-on-terminal-io*}
-This variable controls whether an end of file character (normally
-@myctrl{D}) should terminate the session. The default value is @nil{}.
-@end defvr

src/doc/new-doc/standards/data_and_control_flow.txi

@@ -0,0 +1,137 @@
+@node Data and control flow
+@section Data and control flow
+
+@node Shadowed bindings
+@cindex Shadowed bindings in LET, FLET, LABELS and lambda-list
+@subsection Shadowed bindings
+ANSI doesn't specify what should happen if any of the @code{LET},
+@code{FLET} and @code{LABELS} special operators contain many bindings
+sharing the same name. Because the behavior varies between the
+implementations and the programmer can't rely on the spec ECL signals an
+error if such situation occur.
+
+Moreover, while ANSI defines lambda list parameters in the terms of
+@code{LET*}, when used in function context programmer can't provide an
+initialization forms for required parameters. If required parameters
+share the same name the error is signalled.
+
+Described behavior is present in ECL since version 16.0.0. Previously
+the @code{LET} operator were using first binding. Both @code{FLET} and
+@code{LABELS} were signalling an error if C compiler was used and used
+the last binding as a visible one when the byte compiler was used.
+
+@node Minimal compilation
+@cindex Bytecodes eager compilation
+@lspindex si::make-lambda
+@subsection Minimal compilation
+Former versions of ECL, as well as many other lisps, used linked lists
+to represent code. Executing code thus meant traversing these lists and
+performing code transformations, such as macro expansion, every time
+that a statement was to be executed. The result was a slow and memory
+hungry interpreter.
+
+Beginning with version 0.3, ECL was shipped with a bytecodes compiler
+and interpreter which circumvent the limitations of linked lists. When
+you enter code at the lisp prompt, or when you load a source file, ECL
+begins a process known as minimal compilation. Barely this process
+consists on parsing each form, macroexpanding it and translating it into
+an intermediate language made of bytecodes.
+
+The bytecodes compiler is implemented in src/c/compiler.d. The main
+entry point is the lisp function si::make-lambda, which takes a name for
+the function and the body of the lambda lists, and produces a lisp
+object that can be invoked. For instance,
+
+@exindex @code{si::make-lambda} usage (bytecodes compilation)
+@lisp
+> (defvar fun (si::make-lambda 'f '((x) (1+ x))))
+*FUN*
+> (funcall fun 2)
+3
+@end lisp
+
+ECL can only execute bytecodes. When a list is passed to EVAL it must be
+first compiled to bytecodes and, if the process succeeds, the resulting
+bytecodes are passed to the interpreter. Similarly, every time a
+function object is created, such as in DEFUN or DEFMACRO, the compiler
+processes the lambda form to produce a suitable bytecodes object.
+
+@cindex Eager compilation implications
+
+The fact that ECL performs this eager compilation means that changes on
+a macro are not immediately seen in code which was already
+compiled. This has subtle implications. Take the following code:
+
+@exindex Eager compilation impact on macros
+@lisp
+> (defmacro f (a b) `(+ ,a ,b))
+F
+> (defun g (x y) (f x y))
+G
+> (g 1 2)
+3
+> (defmacro f (a b) `(- ,a ,b))
+F
+> (g 1 2)
+3
+@end lisp
+
+The last statement always outputs 3 while in former implementations
+based on simple list traversal it would produce -1.
+
+@node Function types
+@subsection Function types
+
+Functions in ECL can be of two types: they are either compiled to
+bytecodes or they have been compiled to machine code using a lisp to C
+translator and a C compiler. To the first category belong function
+loaded from lisp source files or entered at the toplevel. To the second
+category belong all functions in the ECL core environment and functions
+in files processed by compile or compile-file.
+
+The output of (symbol-function fun) is one of the following:
+@itemize
+@item a function object denoting the definition of the function fun,
+@item a list of the form (macro . function-object) when fun denotes a macro,
+@item or simply 'special, when fun denotes a special form, such as block, if, etc.
+@end itemize
+
+@cindex @code{disassemble} and @code{compile} on defined functions
+@exindex Keeping lambda definitions with @code{si:*keep-definitions}
+
+ECL usually drops the source code of a function unless the global
+variable si:*keep-definitions* was true when the function was translated
+into bytecodes. Therefore, if you wish to use compile and disassemble on
+defined functions, you should issue @code{(setq si:*keep-definitions*
+t)} at the beginning of your session.
+
+@lspindex si:*keep-definitions*
+@defvr {SI} {*keep-definitions*}
+If set to @code{T} ECL will preserve the compiled function source code
+for disassembly and recompilation.
+@end defvr
+
+@cindex Common Lisp functions limits
+@lspindex call-arguments-limit
+@lspindex lambda-parameters-limit
+@lspindex multiple-values-limit
+@lspindex lambda-list-keywords
+
+In @ref{tab:fun-const} we list all Common Lisp values related to the limits of functions.
+@float Table,tab:fun-const
+@caption{Function related constants}
+@multitable @columnfractions 0.3 0.7
+@item call-arguments-limit
+@tab 65536
+
+@item lambda-parameters-limit
+@tab @code{call-arguments-limit}
+
+@item multiple-values-limit
+@tab 64
+
+@item lambda-list-keywords
+@tab @code{(&optional &rest &key &allow-other-keys &aux &whole &environment &body)}
+@end multitable
+@end float
+

src/doc/new-doc/standards/index.txi

@@ -38,9 +38,8 @@
 
 @include standards/evaluation.txi
 @include standards/types_and_classes.txi
+@include standards/data_and_control_flow.txi
 
-@node Data and control flow
-@section Data and control flow
 @node Iteration
 @section Iteration
 @node Objects

src/doc/new-doc/standards/types_and_classes.txi

@@ -3,11 +3,42 @@
 
 ECL defines the following additional built-in classes in the @code{CL} package:
 
-@code{single-float}, @code{double-float}
+@itemize
+@item @code{single-float}
+@item @code{double-float}
+@end itemize
 
-@c @code{ext:ansi-stream}, @code{ext:sequence-stream},
-@c @code{si::code-block}, @code{si::foreign-data}, @code{si::frame},
-@c @code{si::weak-pointer}, @code{mp::process}, @code{mp::lock},
-@c @code{mp::rwlock}, @code{mp::condition-variable},
-@c @code{mp::semaphore}, @code{mp::barrier}, @code{mp::mailbox},
-@c @code{ext::sse-pack}.
+@subsection C Reference
+
+@subsection ANSI Dictionary
+@multitable @columnfractions 0.3 0.7
+@headitem Lisp symbol
+@tab C/C++ function
+
+@lspindex coerce
+@cppindex cl_coerce
+@ansidict{@clhs{f_coerce.htm,coerce},
+@code{cl_object cl_coerce (cl_object object, cl_object result-type)}}
+
+@lspindex subtypep
+@cppindex cl_subtypep
+@ansidict{@clhs{f_subtpp.htm,subtypep},
+@code{cl_object cl_subtypep (cl_narg narg, cl_object type1, cl_object type2, ...)}}
+
+@lspindex type-of
+@cppindex cl_type-of
+@ansidict{@clhs{f_tp_of.htm,type-of},
+@code{cl_object cl_type-of (cl_object object)}}
+
+@lspindex typep
+@cppindex cl_typep
+@ansidict{@clhs{f_typep.htm,typep},
+@code{cl_object cl_typep (cl_narg narg, cl_object object, cl_object type_specifier, ...)}}
+
+@lspindex type-error-datum
+@ansidict{@clhs{f_tp_err.htm,type-error-datum}, @ocl{}}
+
+@lspindex type-error-expected-type
+@ansidict{@clhs{f_tp_err.htm,type-error-expected-type}, @ocl{}}
+
+@end multitable