Commit 158cb847 authored by Marius Gerbershagen's avatar Marius Gerbershagen

doc: fix makeinfo invocation failures

    Some versions of makeinfo are quite strict about input files and
    don't allow whitespace between @macros and braces or nodes which
    are not referenced in some menu.
parent dcfc987d
......@@ -6,7 +6,7 @@ all: pdf info html
pdf: new-doc.pdf
info: ecldoc.info
html: new-doc.html
html: ecldoc
new-doc.pdf: $(FILES)
texi2pdf new-doc.txi
......@@ -14,8 +14,9 @@ new-doc.pdf: $(FILES)
ecldoc.info: $(FILES)
makeinfo new-doc.txi
new-doc.html: $(FILES)
ecldoc: $(FILES)
makeinfo --html --css-include=ecl.css --split=chapter new-doc.txi
cp -r figures ecldoc
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}
......@@ -10,7 +10,7 @@ If you want to extend, fix or simply customize ECL for your own needs,
you should understand how the implementation works.
@cppindex cl_lispunion
@deftp {@cind} cl_lispunion cons big ratio SF DF longfloat complex symbol pack hash array vector base_string string stream random readtable pathname bytecodes bclosure cfun cfunfixed cclosure d instance process queue lock rwlock condition_variable semaphore barrier mailbox cblock foreign frame weak sse
@deftp @cind{} cl_lispunion cons big ratio SF DF longfloat complex symbol pack hash array vector base_string string stream random readtable pathname bytecodes bclosure cfun cfunfixed cclosure d instance process queue lock rwlock condition_variable semaphore barrier mailbox cblock foreign frame weak sse
Union containing all first-class ECL types.
@end deftp
......@@ -93,7 +93,7 @@ comments in the source code):
@end verbatim
@cppindex cl_object
@deftp {@cind} cl_object
@deftp @cind{} cl_object
This is the type of a lisp object. For your C/C++ program, a cl_object
can be either a fixnum, a character, or a pointer to a union of
structures (See @code{cl_lispunion} in the header object.h). The actual
......@@ -127,7 +127,7 @@ You should see the following sections and the header object.h to learn
how to use the different fields of a cl_object pointer.
@end deftp
@deftp {@cind} cl_type
@deftp @cind{} cl_type
Enumeration type which distinguishes the different types of lisp
objects. The most important values are:
......@@ -302,7 +302,7 @@ amount of memory and the GNU Multiprecision Library is required to
create, manipulate and calculate with them.
@cppindex cl_fixnum
@deftp {@cind} cl_fixnum
@deftp @cind{} cl_fixnum
This is a C signed integer type capable of holding a whole @code{fixnum}
without any loss of precision. The opposite is not true, and you may
create a @code{cl_fixnum} which exceeds the limits of a fixnum and
......@@ -310,7 +310,7 @@ should be stored as a @code{bignum}.
@end deftp
@cppindex cl_index
@deftp {@cind} cl_index
@deftp @cind{} cl_index
This is a C unsigned integer type capable of holding a non-negative
@code{fixnum} without loss of precision. Typically, a @code{cl_index} is
used as an index into an array, or into a proper list, etc.
......@@ -375,7 +375,7 @@ other is used when ECL is built with a configure option
@cppindex ecl_character
@cppindex ecl_base_char
@deftp {@cind} ecl_character
@deftp @cind{} ecl_character
Immediate type @code{t_character}. If ECL built with Unicode support,
then may be either base or extended character, which may be
distinguished with the predicate @code{ECL_BASE_CHAR_P}.
......@@ -460,7 +460,7 @@ functions.
@end deftypefun
@cppindex ecl_vector
@deftp {@cind} ecl_vector
@deftp @cind{} ecl_vector
If @code{x} contains a vector, you can access the following fields:
@table @code
......@@ -479,7 +479,7 @@ pointer depending on @var{x->vector.elttype}.
@end deftp
@cppindex ecl_array
@deftp {@cind} ecl_array
@deftp @cind{} ecl_array
If @code{x} contains a multidimensional array, you can access the
following fields:
......@@ -504,7 +504,7 @@ pointer depending on @var{x->array.elttype}.
@end deftp
@cppindex cl_elttype
@deftp {@cind} cl_elttype ecl_aet_object ecl_aet_sf ecl_aet_df ecl_aet_bit ecl_aet_fix ecl_aet_index ecl_aet_b8 ecl_aet_i8 ecl_aet_b16 ecl_aet_i16 ecl_aet_b32 ecl_aet_i32 ecl_aet_b64 ecl_aet_i64 ecl_aet_ch ecl_aet_bc
@deftp @cind{} cl_elttype ecl_aet_object ecl_aet_sf ecl_aet_df ecl_aet_bit ecl_aet_fix ecl_aet_index ecl_aet_b8 ecl_aet_i8 ecl_aet_b16 ecl_aet_i16 ecl_aet_b32 ecl_aet_i32 ecl_aet_b64 ecl_aet_i64 ecl_aet_ch ecl_aet_bc
Each array is of an specialized type which is the type of the elements
of the array. ECL has arrays only a few following specialized types, and
......@@ -599,8 +599,8 @@ base-string self pointer to any C routine.
@cppindex ecl_string
@cppindex ecl_base_string
@deftp {@cind} ecl_string
@deftpx {@cind} ecl_base_string
@deftp @cind{} ecl_string
@deftpx @cind{} ecl_base_string
If @code{x} is a lisp object of type string or a base-string, we can
access the following fields:
@table @code
......@@ -643,11 +643,11 @@ separate package @var{GRAY}. We may redefine functions in the
at run-time.
@cppindex ecl_file_pos
@deftp {@cind} ecl_file_ops write_* read_* unread_* peek_* listen clear_input clear_output finish_output force_output input_p output_p interactive_p element_type length get_position set_position column close
@deftp @cind{} ecl_file_ops write_* read_* unread_* peek_* listen clear_input clear_output finish_output force_output input_p output_p interactive_p element_type length get_position set_position column close
@end deftp
@cppindex ecl_stream
@deftp {@cind} ecl_stream
@deftp @cind{} ecl_stream
@table @code
@item ecl_smmode mode
Stream mode (in example @code{ecl_smm_string_input}).
......
......@@ -40,6 +40,16 @@ Relations among them are depicted below:
@image{figures/file-types}
@end float
@menu
* Portable FASL (fasc)::
* Native FASL::
* Object file::
* Static library::
* Shared library::
* Executable::
* Summary::
@end menu
@node Portable FASL (fasc)
@subsubsection Portable FASL
@cindex Portable FASL
......@@ -303,6 +313,13 @@ pack libraries your project depends on (that is, all dependencies you
put in your @code{.asd} file, and their dependencies - nothing more,
despite the fact that other libraries may be loaded).
@menu
* Example code to build::
* Build it as an single executable::
* Build it as shared library and use in C::
* Build it as static library and use in C::
@end menu
@node Example code to build
@subsubsection Example code to build
......
......@@ -841,7 +841,7 @@ should in general not return @code{cstring}s, but @code{foreign
strings}. (There is no portable way to release such @code{cstring}s from
Lisp.) The following is an example of handling such a function.
@exindex Conversion between @code{foreign string} and @code {cstring}
@exindex Conversion between @code{foreign string} and @code{cstring}
@lisp
(ffi:def-function ("readline" c-readline)
((prompt :cstring))
......@@ -1065,8 +1065,8 @@ does not take any arguments.
A string specifying which module (or library) that the foreign function
resides.
@item call
Function calling convention. May be one of @code{:default}, @code
{:cdecl}, @code{:sysv}, @code{:stdcall}, @code{:win64} and
Function calling convention. May be one of @code{:default}, @code{:cdecl},
@code{:sysv}, @code{:stdcall}, @code{:win64} and
@code{unix64}.
This argument is used only when we're using the dynamic function
......
@node Meta-Object Protocol (MOP)
@section Meta-Object Protocol (MOP)
@menu
* MOP - Introduction::
@end menu
@node MOP - Introduction
@subsection Introduction
The Meta-Object Protocol is an extension to Common Lisp which provides rules, functions and a type structure to handle the object system. It is a reflective system, where classes are also objects and can be created and manipulated using very well defined procedures.
......
......@@ -75,7 +75,7 @@ Kill a task that is doing nothing (See @code{mp:process-kill}).
@defun mp:make-process &key name initial-bindings
Create a new thread. This function creates a separate task with a name
set to @code {name}, set of variable bindings @code{initial-bindings}
set to @code{name}, set of variable bindings @code{initial-bindings}
and no function to run. See also @code{mp:process-run-function}. Returns
newly created process.
......@@ -90,7 +90,7 @@ newly created process.
@defun mp:process-active-p process
Returns @code{t} when @code{process} is active, @code {nil}
Returns @code{t} when @code{process} is active, @code{nil}
otherwise. Signals an error if @code{process} doesn't designate a valid
process.
......
@node Signals and Interrupts
@section Signals and Interrupts
@menu
* Signals and Interrupts - Problems associated to signals::
* Signals and Interrupts - Kinds of signals::
* Signals and Interrupts - Signals and interrupts in ECL::
* Signals and Interrupts - Considerations when embedding ECL::
* Signals and Interrupts - Signals Reference::
@end menu
@node Signals and Interrupts - Problems associated to signals
@subsection Problems associated to signals
POSIX contemplates the notion of "signals", which are events that cause a process or a thread to be interrupted. Windows uses the term "exception", which includes also a more general kind of errors.
......@@ -14,6 +22,11 @@ Understanding this, POSIX restricts severely what functions can be called from a
@node Signals and Interrupts - Kinds of signals
@subsection Kinds of signals
@menu
* Signals and Interrupts - Synchronous signals::
* Signals and Interrupts - Asynchronous signals::
@end menu
@node Signals and Interrupts - Synchronous signals
@subsubsection Synchronous signals
The name derives from POSIX and it denotes interrupts that occur due to the code that a particular thread executes. They are largely equivalent to C++ and Java exceptions, and in Windows they are called "unchecked exceptions."
......@@ -52,6 +65,11 @@ The signal handling facilities in ECL are constrained by two needs. First of all
The way in which this is solved is based on the existence of both synchronous and asynchronous signal handling code, as explained in the following two sections.
@menu
* Signals and Interrupts - Handling of asynchronous signals::
* Signals and Interrupts - Handling of synchronous signals::
@end menu
@node Signals and Interrupts - Handling of asynchronous signals
@subsubsection Handling of asynchronous signals
In systems in which this is possible, ECL creates a signal handling thread to detect and process asynchronous signals (@xref{Signals and Interrupts - Asynchronous signals}). This thread is a trivial one and does not process the signals itself: it communicates with, or launches new signal handling threads to act accordingly to the denoted events.
......
......@@ -2,6 +2,12 @@
@section Arrays
@cindex Arrays
@menu
* Arrays - Array limits::
* Arrays - Specializations::
* Arrays - C Reference::
@end menu
@node Arrays - Array limits
@subsection Array limits
ECL arrays can have up to 64 dimensions. Common-Lisp constants related to arrays have the following values in ECL.
......
......@@ -3,6 +3,12 @@
ECL is fully ANSI Common-Lisp compliant in all aspects of the character data type, with the following peculiarities.
@menu
* Characters - Unicode vs. POSIX locale::
* Characters - Newline characters::
* Characters - C Reference::
@end menu
@node Characters - Unicode vs. POSIX locale
@subsection Unicode vs. POSIX locale
There are two ways of building ECL: with C or with Unicode character codes. These build modes are accessed using the @code{--disable-unicode} and @code{--enable-unicode} configuration options, the last one being the default.
......
@node Conditions
@section Conditions
@menu
* Conditions - C Reference::
@end menu
@node Conditions - C Reference
@subsection C Reference
@cppindex ECL_HANDLER_CASE
......
@node Conses
@section Conses
@menu
* Conses - C Reference::
@end menu
@node Conses - C Reference
@subsection C Reference
......
@node Data and control flow
@section Data and control flow
@menu
* Shadowed bindings::
* Minimal compilation::
* Function types::
* C Calling conventions::
* C Reference::
@end menu
@node Shadowed bindings
@cindex Shadowed bindings in LET, FLET, LABELS and lambda-list
@subsection Shadowed bindings
@cindex Shadowed bindings in LET, FLET, LABELS and lambda-list
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
......@@ -21,9 +29,9 @@ the @code{LET} operator were using first binding. Both @code{FLET} and
the last binding as a visible one when the byte compiler was used.
@node Minimal compilation
@subsection 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
......@@ -181,7 +189,7 @@ printf("\n1 + 1 + 1 is %d\n", ecl_fixnum(three));
Another restriction of C and C++ is that functions can only take a limited number of arguments. In order to cope with this problem, ECL uses an internal stack to pass any argument above a hardcoded limit, @code{ECL_C_CALL_ARGUMENTS_LIMIT}, which is as of this writing 63. The use of this stack is transparently handled by the Common Lisp functions, such as apply, funcall and their C equivalents, and also by a set of macros, @code{cl_va_arg}, which can be used for coding functions that take an arbitrary name of arguments.
@node C Reference
@subsection C Reference
@cppindex ecl_bds_bind
@cppindex ecl_bds_push
......
@node Environment
@section Environment
@menu
* Environment - Dictionary::
* Environment - C Reference::
@end menu
@node Environment - Dictionary
@subsection Dictionary
@lspindex disassemble
......
@node Filenames
@section Filenames
@menu
* Filenames - Syntax::
* Filenames - Wild pathnames and matching::
* Filenames - C Reference::
@end menu
@node Filenames - Syntax
@subsection Syntax
A pathname in the file system of Common-Lisp consists of six elements: host, device, directory, name, type and version. Pathnames are read and printed using the @code{#P} reader macro followed by the namestring. A namestring is a string which represents a pathname. The syntax of namestrings for logical pathnames is well explained in the ANSI @bibcite{ANSI} and it can be roughly summarized as follows:
......
@node Files
@section Files
@menu
* Files - Dictionary::
* Files - C Reference::
@end menu
@node Files - Dictionary
@subsection Dictionary
@subsubsection @code{DIRECTORY}
......
@node Hash tables
@section Hash tables
@menu
* Hash tables - C Reference::
@end menu
@subheading Weakness in hash tables
@cindex Weak hash tables
@ftindex ECL-WEAK-HASH
......
@node Numbers
@section Numbers
@menu
* Numbers - Numeric types::
* Numbers - Random-States::
* Numbers - C Reference::
@end menu
@node Numbers - Numeric types
@subsection Numeric types
ECL supports all of the Common Lisp numeric tower, which is shown in @ref{tab:num-types}. The details, however, depend both on the platform on which ECL runs and on the configuration which was chosen when building ECL.
......@@ -33,6 +39,15 @@ The @code{#$} macro can be used to initialize the generator with a random seed (
@node Numbers - C Reference
@subsection C Reference
@menu
* Numbers - Number C types::
* Numbers - Number constructors::
* Numbers - Number accessors::
* Numbers - Number coercion::
* Numbers - Numbers C dictionary::
@end menu
@node Numbers - Number C types
@subsubsection Number C types
Numeric C types understood by ECL
......
@node Objects
@section Objects
@menu
* Objects - C Reference::
@end menu
@node Objects - C Reference
@subsection C Reference
......
@node Sequences
@section Sequences
@menu
* Sequences - C Reference::
@end menu
@node Sequences - C Reference
@subsection C Reference
@subsubsection Sequences C dictionary
......
@node Streams
@section Streams
@menu
* Streams - ANSI Streams::
* Streams - C Reference::
@end menu
@node Streams - ANSI Streams
@subsection ANSI Streams
@menu
* Streams - Supported types::
* Streams - Element types::
* Streams - External formats::
@end menu
@node Streams - Supported types
@subsubsection Supported types
ECL implements all stream types described in ANSI @bibcite{ANSI}. Additionally, when configured with option @code{--enable-clos-streams}, ECL includes a version of Gray streams where any object that implements the appropiate methods (@code{stream-input-p}, @code{stream-read-char}, etc) is a valid argument for the functions that expect streams, such as @code{read}, @code{print}, etc.
......@@ -36,8 +47,8 @@ external-format-designator :=
and the table of known symbols is shown below. Note how some symbols (@code{:cr}, @code{:little-endian}, etc.) just modify other external formats.
@c@float Table, tab:stream-ext-formats
@c@caption{Stream external formats}
@c @float Table, tab:stream-ext-formats
@c @caption{Stream external formats}
@multitable @columnfractions .4 .4 .2
@headitem Symbols @tab Codepage or encoding @tab Unicode required
@item @code{:cr} @tab @code{#\Newline} is @code{Carriage Return} @tab No
......
@node Strings
@section Strings
@menu
* Strings - String types & Unicode::
* Strings - C reference::
@end menu
@node Strings - String types & Unicode
@subsection String types & Unicode
The ECL implementation of strings is ANSI Common-Lisp compliant. There are basically four string types as shown in @ref{tab:cl-str-types}. As explained in @ref{Characters}, when Unicode support is disabled, @code{character} and @code{base-character} are the same type and the last two string types are equivalent to the first two.
......
@node Structures
@section Structures
@menu
* Structures - C Reference::
@end menu
@node Structures - C Reference
@subsection C Reference
......
@node Embedding ECL
@section Embedding ECL
@menu
* Embedding ECL - Embedding Reference::
@end menu
@c @node Embedding ECL - Introduction
@c @subsection Introduction
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment