new-doc: update new-doc

src/doc/new-doc/.gitignore

@@ -0,0 +1 @@
+*.html

src/doc/new-doc/Makefile

@@ -15,6 +15,7 @@ ecldoc.info: $(FILES)
 	makeinfo new-doc.txi
 
 new-doc.html: $(FILES)
+	makeinfo --html --no-split 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/contributing-documentation.txi

@@ -190,3 +190,9 @@ References should be added like as follows:
 @verbatim
 [@ref{Standards}]
 @end verbatim
+
+Links:
+@verbatim
+@uref{http://example.org}
+@uref{http://example.org, Example website}
+@end verbatim

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

@@ -291,7 +291,7 @@ cl_object array2 = string_to_object(string);
 @end deftypefun
 
 @node Integers (dev)
-@subsection Integers (dev)
+@subsection 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
@@ -373,7 +373,7 @@ appropriate size. Signals an error if @var{o} is not of fixnum type.
 @end deftypefun
 
 @node Characters (dev)
-@subsection Characters (dev)
+@subsection Characters
 
 @cfindex --enable-unicode (YES|no|32)
 
@@ -451,7 +451,7 @@ before comparing them.
 @end deftypefun
 
 @node Arrays (dev)
-@subsection Arrays (dev)
+@subsection 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
@@ -595,7 +595,7 @@ cl_print(1, array); /* Outputs #(1 2 3 5) */
 @end deftypefun
 
 @node Strings (dev)
-@subsection Strings (dev)
+@subsection 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
@@ -633,7 +633,7 @@ supported, then @code{ECL_EXTENDED_STRING_P} always returns 0.
 @end deftypefun
 
 @node Bit-vectors (dev)
-@subsection Bit-vectors (dev)
+@subsection Bit-vectors
 
 Bit-vector operations are implemented in file
 @code{src/c/array.d}. Bit-vector shares the structure with a vector,
@@ -641,7 +641,7 @@ therefore, almost everything mentioned in the section of arrays remains
 valid here.
 
 @node Streams (dev)
-@subsection Streams (dev)
+@subsection 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
@@ -713,7 +713,7 @@ object of type @code{m}.
 @end deftypefun
 
 @node Structures (dev)
-@subsection Structures (dev)
+@subsection Structures
 
 Structures and instances share the same datatype @code{t_instance} (
 with a few exceptions. Structure implementation details are the file
@@ -733,7 +733,7 @@ Convenience functions for the structures.
 @end deftypefun
 
 @node Instances (dev)
-@subsection Instances (dev)
+@subsection Instances
 
 @cppindex ECL_CLASS_OF
 @cppindex ECL_SPEC_FLAG
@@ -758,7 +758,7 @@ Convenience functions for the structures.
 @end deftypefun
 
 @node Bytecodes (dev)
-@subsection Bytecodes (dev)
+@subsection 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/introduction/about_man.txi

@@ -0,0 +1,47 @@
+@node About this book
+@section About this book
+
+This manual is part of the ECL software system. It documents deviations
+of ECL from various standards (@bibcite{ANSI}, @bibcite{AMOP},...),
+extensions, daily working process (compiling files, loading sources,
+creating programs, etc) and the internals of this implementation.
+
+It is not intended as a source to learn Common Lisp. There are other
+tutorials and textbooks available in the Net which serve this
+purpose. The homepage of the
+@uref{https://common-lisp.net,Common-Lisp.net} contains a good list of
+links of such teaching and learning material.
+
+This book is structure into four parts:
+
+@subsection User's guide
+We begin with [@ref{User's guide}] which provides introductory material
+showing the user how to build and use ECL and some of its unique
+features. This part assumes some basic Common Lisp knowledge and is
+suggested as an entry point for a new users who want to start using
+@ecl{}.
+
+@subsection Developer's guide
+[@ref{Developer's guide}] documents @ecl{} implementation details. This
+part isn not meant for normal users but rather for the ECL developers
+and other people who want to contribute to @ecl{}. This section is prone
+to change due to the dynamic nature of a software. Covered topics
+include source code structure, contributing guide, internal
+implementation details and many other topics relevant to the development
+process.
+
+@subsection Standards
+[@ref{Standards}] documents all parts of the standard which are left as
+implementation specific or to which ECL doesn't adhere. For instance,
+precision of floating point numbers, available character sets, actual
+input/output protocols, etc.
+
+Section covers also @emph{C Reference} as a description of @ansi{} from
+the C/C++ programmer perspective and @emph{ANSI Dictionary} for @clisp{}
+constructs available from C/C++.
+
+@subsection Extensions
+[@ref{Extensions}] introduces all features which are specific to ECL and
+which lay outside the standard. This includes configuring, building and
+installing ECL multiprocessing capabilities, graphics libraries,
+interfacing with the operating system, etc.

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

@@ -49,7 +49,7 @@ with agreement of Prof. Attardi, took over the original ECL
 implementation and it became what it is nowadays, a community project.
 
 In 2013 once again project got unmaintained. In 2015 Daniel Kochmański
-took position of maintainer with consent of Juanjo García-Ripoll.
+took the position of a maintainer with consent of Juanjo García-Ripoll.
 
 The ECL project owes a lot to different people who have contributed in
 many different aspects, from pointing out bugs and incompatibilities of

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

@@ -2,6 +2,7 @@
 @unnumbered Introduction
 
 @menu
+* About this book::
 * What is ECL::
 * History::
 * Credits::
@@ -9,6 +10,7 @@
 * Sandbox::
 @end menu
 
+@include introduction/about_man.txi
 @include introduction/about_ecl.txi
 @include introduction/history.txi
 @include introduction/credits.txi

src/doc/new-doc/macros.txi

@@ -84,7 +84,7 @@
 @r{ANSI Common-Lisp}
 @end macro
 @macro ecl
-@b{@r{Embeddable Common-Lisp}}
+@b{@r{Embeddable Common Lisp}}
 @end macro
 @macro clisp
 @r{Common-Lisp}

src/doc/new-doc/new-doc.txi

@@ -9,6 +9,7 @@
 @defcodeindex cf
 @defcodeindex ft
 @defindex ex
+@documentencoding UTF-8
 @c %**end of header
 
 @c Entries for @command{install-info} to use

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

@@ -114,8 +114,7 @@ instance, if you compile with a low value of @code{SAFETY}, and invoke
 @end multitable
 @end float
 
-@node C Reference (Evaluation and compilation)
-@subsection C Reference (Evaluation and compilation)
+@subsection C Reference
 
 @cppindex ecl_process_env
 @deftypefn {@cind{}} cl_object cl_env_ptr ()
@@ -126,7 +125,6 @@ variety of tasks, such as defining special variable bindings,
 controlling interrupts, retrieving function output values, etc.
 @end deftypefn
 
-@node ANSI Dictionary (Evaluation and compilation)
 @subsection ANSI Dictionary
 
 @multitable @columnfractions 0.4 0.6

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

@@ -56,7 +56,7 @@ concepts are explained in a different (@ref{Embedding ECL}) part of the
 book.
 
 @node C Reference (Overview)
-@subsection C Reference (Overview)
+@subsection C Reference
 @subsubsection One type for everything: @code{cl_object}
 @cindex One type for everything: @code{cl_object}
 

src/doc/new-doc/user-guide/break-loop.txi

@@ -0,0 +1,2 @@
+@node The break loop
+@section The break loop

src/doc/new-doc/user-guide/building.txi

@@ -1,8 +1,8 @@
 @node Building ECL
 @section Building ECL
 
-Due to it's portable nature ECL works on every (at least) 32-bit
-architecture which provides the proper C99 compliant compiler.
+Due to its portable nature ECL works on every (at least) 32-bit
+architecture which provides a proper C99 compliant compiler.
 
 Operating systems on which ECL is reported to work: Linux, Darwin (Mac
 OS X), Solaris, FreeBSD, NetBSD, OpenBSD, DragonFly BSD, Windows and
@@ -15,14 +15,6 @@ however each release is tested by volunteers with an excellent package
 @uref{https://common-lisp.net/project/cl-test-grid,cl-test-grid} created
 and maintained by Anton Vodonosov.
 
-@menu
-@c * Supported platforms::
-* Autoconf based configuration::
-@c * Cross-compiling ECL::
-* Platform specific instructions::
-@end menu
-
-@node Autoconf based configuration
 @subsection Autoconf based configuration
 
 ECL, like many other FOSS programs, can be built and installed with a
@@ -73,16 +65,7 @@ Top level in: #<process TOP-LEVEL>.
 @end example
 @end enumerate
 
-@node Platform specific instructions
 @subsection Platform specific instructions
-
-@menu
-* MSVC based configuration::
-@c * BSD systems::
-@c * Android::
-@end menu
-
-@node MSVC based configuration
 @subsubsection MSVC based configuration
 
 If you have a commercial version of Microsoft Visual Studio, the steps

src/doc/new-doc/user-guide/index.txi

@@ -8,7 +8,7 @@
 @c * The tracer::
 @c * The stepper::
 @c * Errors::
-@c * The break loop::
+* The break loop::
 @c * Describe and inspect::
 @c * The profiler::
 @c * Online help::
@@ -19,4 +19,5 @@
 
 @include user-guide/building.txi
 @include user-guide/invoking.txi
+@include user-guide/break-loop.txi
 @include user-guide/embedding.txi

src/doc/new-doc/user-guide/invoking.txi

@@ -58,7 +58,7 @@ SI>
 To exit from @ecl{}, call the function @code{quit}.
 
 @example
->(quit)
+> (quit)
 %
 @end example
 
@@ -66,7 +66,8 @@ Alternatively, you may type @myctrl{D} , i.e. press the key @key{D}
 while pressing down the control key (@key{Ctrl}).
 
 @example
->@myctrl{D}
+> @myctrl{D}
+
 %
 @end example
 
@@ -77,23 +78,23 @@ If more than one value is returned by the evaluation of the top-level
 form, the values will be printed successively.  If no value is returned,
 then nothing will be printed.
 @example
->(values 1 2)
+> (values 1 2)
 1
 2
->(values)
+> (values)
 
 >
 @end example
 
 When an error is signalled, control will enter the break loop.
 @example
->(defun foo (x) (bar x))
+> (defun foo (x) (bar x))
 foo
 
->(defun bar (y) (bee y y))
+> (defun bar (y) (bee y y))
 
 bar
->(foo 'lish)
+> (foo 'lish)
 Condition of type: UNDEFINED-FUNCTION
 The function BAR is undefined.
 
@@ -105,8 +106,6 @@ Broken at FOO. In: #<process TOP-LEVEL>.
 >>
 @end example
 
-To pick the first restart user has too type 
-
 @c @vskip 1em
 
 `@code{>>}' in the last line is the prompt of the break loop.  Like in
@@ -126,20 +125,18 @@ If more restarts are present, user may invoke them with by typing
 @code{:rN}, where @key{N} is the restart number. For instance to pick
 the restart number two, type @code{:r2}.
 
-@c @vskip 1em
+See [@ref{The break loop}] for the details of the break loop.
 
-See Section 5.4 for the details of the break loop.
-
-The terminal interrupt (usually caused by typing @myctrl{C}
+The terminal interrupt (usually caused by typing @myctrl{C} 
 (Control-@code{C})) is a kind of error.  It breaks the running program
 and calls the break level loop.
 
 Example:
 @example
->(defun foo () (do () (nil)))
+> (defun foo () (do () (nil)))
 foo
 
->(foo)
+> (foo)
 @myctrl{C}
 
 Condition of type: INTERACTIVE-INTERRUPT