Changeset 4561 for trunk/manuals

Timestamp:

11/02/08 09:20:29 (2 months ago)

Author:

pmoura

Message:

Minor documentation improvements.

Location:

trunk/manuals/userman

Files:

• documenting.html (modified) (1 diff)
• features.html (modified) (4 diffs)
• index.html (modified) (10 diffs)
• installing.html (modified) (2 diffs)
• messages.html (modified) (2 diffs)
• objects.html (modified) (1 diff)
• programming.html (modified) (4 diffs)
• protocols.html (modified) (1 diff)
• running.html (deleted)
• userman.sh (modified) (2 diffs)

trunk/manuals/userman/documenting.html

@@ -140 +140 @@
 </p>
 <p>
-There is a set of compilers options, used with the Logtalk <a title="Consult reference manual" href="../refman/builtins/logtalk_load2.html"><code>logtalk_load/2</code></a> or the <a title="Consult reference manual" href="../refman/builtins/logtalk_compile2.html"><code>logtalk_compile/2</code></a> built-in predicates, that can be used to control the generation of the XML documentation files. Please see the <a href="running.html#options">Running Logtalk</a> section of this manual for details.
+There is a set of compilers options, used with the Logtalk <a title="Consult reference manual" href="../refman/builtins/logtalk_load2.html"><code>logtalk_load/2</code></a> or the <a title="Consult reference manual" href="../refman/builtins/logtalk_compile2.html"><code>logtalk_compile/2</code></a> built-in predicates, that can be used to control the generation of the XML documentation files. Please see the <a href="programming.html#options">Running Logtalk</a> section of this manual for details.
 </p>
 

trunk/manuals/userman/features.html

@@ -44 +44 @@
 <blockquote>
 <p>
-Event-driven programming enables the building of reactive systems, where computing which takes place at each moment is a result of the observation of occurring events. This integration complements object-oriented programming, in which each computing is initiated by the explicit sending of a message to an object. The user dynamically defines what events are to be observed and establishes monitors for these events. This is specially useful when representing relationships between objects that imply constraints in the state of participating objects <a href="../bibliography.html#Rumbaugh87">[Rumbaugh 87</a>, <a href="../bibliography.html#Rumbaugh88">Rumbaugh 88</a>, <a href="../bibliography.html#Fornarino89">Fornarino 89</a>, <a href="../bibliography.html#Razek92">Razek 92]</a>. Other common uses are reflective applications like code debugging or profiling <a href="../bibliography.html#Maes87">[Maes 87]</a>.
+Event-driven programming enables the building of reactive systems, where computing which takes place at each moment is a result of the observation of occurring events. This integration complements object-oriented programming, in which each computing is initiated by the explicit sending of a message to an object. The user dynamically defines what events are to be observed and establishes monitors for these events. This is specially useful when representing relationships between objects that imply constraints in the state of participating objects <a href="../bibliography.html#Rumbaugh87">[Rumbaugh 87</a>, <a href="../bibliography.html#Rumbaugh88">Rumbaugh 88</a>, <a href="../bibliography.html#Fornarino89">Fornarino 89</a>, <a href="../bibliography.html#Razek92">Razek 92]</a>. Other common uses are reflective applications like code debugging or profiling <a href="../bibliography.html#Maes87">[Maes 87]</a>. Predicates can be implicitly called when a spied event occurs, allowing programming solutions which minimize object coupling. In addition, events provide support for behavioral reflection and can be used to implement the concepts of <em>pointcut</em> and <em>advice</em> found on Aspect-Oriented Programming.</dd>
 </p>
 </blockquote>
@@ -52 +52 @@
 <blockquote>
 <p>
-Predicates can be encapsulated inside <em>categories</em> which can be imported by any object. A category is a first-class encapsulation entity, at the same level as objects and protocols, which can be used as a component when building new objects. Categories allows for code reuse between non-related objects, independent of hierarchy relations, in the same vein as protocols allow for interface reuse.
+Predicates can be encapsulated inside <em>categories</em> which can be imported by any object, without any code duplication and irrespective of object hierarchies. A category is a first-class encapsulation entity, at the same level as objects and protocols, which can be used as a component when building new objects. Thus, objects may be defined through composition of categories, which act as fine-grained units of code reuse. Categories may also extend existing objects. Categories can be used to implement <em>mixins</em> and <em>aspects</em>. Categories allows for code reuse between non-related objects, independent of hierarchy relations, in the same vein as protocols allow for interface reuse.
 </p>
 </blockquote>
@@ -100 +100 @@
 <blockquote>
 <p>
-Object names can be compound terms (instead of atoms), providing a way to parameterize object predicates. Parametric objects are implemented in a similar way to <code>L&amp;O</code> <a href="../bibliography.html#McCabe92">[McCabe 92]</a>, <code>OL(P)</code> <a href="../bibliography.html#Fromherz93">[Fromherz 93]</a> or <code>SICStus Objects</code> <a href="../bibliography.html#SICStus95">[SICStus 95]</a>. However, access to parameter values is done via a built-in method instead of making the parameters scope global over the whole object.
+Object names can be compound terms (instead of atoms), providing a way to parameterize object predicates. Parametric objects are implemented in a similar way to <code>L&amp;O</code> <a href="../bibliography.html#McCabe92">[McCabe 92]</a>, <code>OL(P)</code> <a href="../bibliography.html#Fromherz93">[Fromherz 93]</a> or <code>SICStus Objects</code> <a href="../bibliography.html#SICStus95">[SICStus 95]</a> (however, access to parameter values is done via a built-in method instead of making the parameters scope global over the whole object). Parametric objects allows us to treat any predicate clause as defining an <em>instantiation</em> of a parametric object. Thus, a parametric object allows us to  encapsulate and associate any number of predicates with a compound term.</dd>
 </p>
 </blockquote>
@@ -142 +142 @@
 </blockquote>
 
+<h2 id="features_scope">Logtalk scope</h2>
+
+<p>
+Logtalk, being a superset of Prolog, shares with it the same preferred areas of application but also extends them with those areas where object-oriented features provide an advantage compared to plain Prolog. Among these areas we have:
+</p>
+<dl>
+    <dt><strong>Logic and object-oriented programming teaching and researching</strong></dt>
+        <dd>Logtalk smooth learning curve, combined with support for both prototype and class-based programming, protocols, components or aspects via category-based composition, and other advanced object-oriented features allow a smooth introduction to object-oriented programming to people with a background in Prolog programming. The distribution of Logtalk source code using an open-source license provides a framework for people to learn and then modify to try out new ideas on object-oriented programming research. In addition, the Logtalk distribution includes plenty of programming examples that can be used in the classroom for teaching logic and object-oriented programming concepts.</dd>
+</dl>
+<dl>
+    <dt><strong>Structured knowledge representations and knowledge-based systems</strong></dt>
+        <dd>Logtalk objects, coupled with event-driven programming features, enable easy implementation of frame-like systems and similar structured knowledge representations.</dd>
+</dl>
+<dl>
+    <dt><strong>Blackboard systems, agent-based systems and systems with complex object relationships</strong></dt>
+        <dd>Logtalk support for event-driven programming can provide a basis for the dynamic and reactive nature of blackboard type applications.</dd>
+</dl>
+<dl>
+    <dt><strong>Highly portable applications</strong></dt>
+        <dd>Logtalk is compatible with almost any modern Prolog compiler. Used as a way to provide Prolog with namespaces, it avoids the porting problems of most Prolog module systems. Platform, operating system, or compiler specific code can be isolated from the rest of the code by encapsulating it in objects with well defined interfaces.</dd>
+</dl>
+<dl>
+    <dt><strong>Alternative to a Prolog module system</strong></dt>
+        <dd>Logtalk can be used as an alternative to a Prolog compiler module system. Any Prolog application that use modules can be converted to a Logtalk application, improving portability across Prolog compilers and taking advantage of the stronger encapsulation and reuse framework provided by Logtalk object-oriented features.</dd>
+</dl>
+<dl>
+    <dt><strong>Integration with other programming languages</strong></dt>
+        <dd>Logtalk support for most key object-oriented features helps users integrating Prolog with object-oriented languages like C++, Java, or Smalltalk by providing an high-level mapping between the two languages.</dd>
+</dl>
+
 <div class="footer">
     <div class="copyright">
         <span>Copyright &copy; <a href="mailto:pmoura@logtalk.org">Paulo Moura</a> &mdash; <a href="http://logtalk.org">Logtalk.org</a></span><br/> 
-        <span>Last updated on: June 8, 2007</span>
+        <span>Last updated on: October 31, 2008</span>
     </div>
     <div class="navbottom">

trunk/manuals/userman/index.html

@@ -23 +23 @@
 
 <dl class="toc-entries">
-    <dt><a href="#features">Logtalk features</a><span class="leader"></span><span class="page-ref"><span class="features_features"></span></span></dt>
-    <dt><a href="#nomenclature">Logtalk nomenclature</a><span class="leader"></span><span class="page-ref"><span class="nomenclature_nomenclature"></span></span></dt>
-</dl>
-<dl class="toc-entries">
-    <dt><a href="#messages">Message sending</a><span class="leader"></span><span class="page-ref"><span class="messages_messages"></span></span></dt>
+    <dt><a href="#features">Logtalk Features</a><span class="leader"></span><span class="page-ref"><span class="features_features"></span></span></dt>
+    <dt><a href="#nomenclature">Logtalk Nomenclature</a><span class="leader"></span><span class="page-ref"><span class="nomenclature_nomenclature"></span></span></dt>
+</dl>
+<dl class="toc-entries">
+    <dt><a href="#messages">Message Sending</a><span class="leader"></span><span class="page-ref"><span class="messages_messages"></span></span></dt>
     <dt><a href="#objects">Objects</a><span class="leader"></span><span class="page-ref"><span class="objects_objects"></span></span></dt>
     <dt><a href="#protocols">Protocols</a><span class="leader"></span><span class="page-ref"><span class="protocols_protocols"></span></span></dt>
@@ -33 +33 @@
     <dt><a href="#predicates">Predicates</a><span class="leader"></span><span class="page-ref"><span class="predicates_predicates"></span></span></dt>
     <dt><a href="#inheritance">Inheritance</a><span class="leader"></span><span class="page-ref"><span class="inheritance_inheritance"></span></span></dt>
-    <dt><a href="#events">Event-driven programming</a><span class="leader"></span><span class="page-ref"><span class="events_events"></span></span></dt>
-    <dt><a href="#threads">Multi-threading programming</a><span class="leader"></span><span class="page-ref"><span class="threads_threads"></span></span></dt>
-    <dt><a href="#errors">Error handling</a><span class="leader"></span><span class="page-ref"><span class="errors_errors"></span></span></dt>
-</dl>
-<dl class="toc-entries">
-    <dt><a href="#documenting">Documenting Logtalk programs</a><span class="leader"></span><span class="page-ref"><span class="documenting_documenting"></span></span></dt>
+    <dt><a href="#events">Event-driven Programming</a><span class="leader"></span><span class="page-ref"><span class="events_events"></span></span></dt>
+    <dt><a href="#threads">Multi-threading Programming</a><span class="leader"></span><span class="page-ref"><span class="threads_threads"></span></span></dt>
+    <dt><a href="#errors">Error Handling</a><span class="leader"></span><span class="page-ref"><span class="errors_errors"></span></span></dt>
+</dl>
+<dl class="toc-entries">
+    <dt><a href="#documenting">Documenting Logtalk Programs</a><span class="leader"></span><span class="page-ref"><span class="documenting_documenting"></span></span></dt>
 </dl>
 <dl class="toc-entries">
     <dt><a href="#installing">Installing Logtalk</a><span class="leader"></span><span class="page-ref"><span class="installing_installing"></span></span></dt>
-    <dt><a href="#running">Running and debugging Logtalk programs</a><span class="leader"></span><span class="page-ref"><span class="running_running"></span></span></dt>
-    <dt><a href="#programming">Programming in Logtalk</a><span class="leader"></span><span class="page-ref"><span class="programming_programming"></span></span></dt>
-</dl>
-
-<h2><a id="features" href="features.html">Logtalk features</a></h2>
+    <dt><a href="#programming">Writing, Running, and Debugging Logtalk Programs</a><span class="leader"></span><span class="page-ref"><span class="programming_programming"></span></span></dt>
+</dl>
+
+<h2><a id="features" href="features.html">Logtalk Features</a></h2>
 
 <dl class="toc-entries">
@@ -62 +61 @@
     <dt><a href="features.html#features_compatibility">Compatibility with most Prologs and the ISO standard</a><span class="leader"></span><span class="page-ref"><span class="features_compatibility"></span></span></dt>
     <dt><a href="features.html#features_performance">Performance</a><span class="leader"></span><span class="page-ref"><span class="features_performance"></span></span></dt>
-</dl>
-
-<h2><a id="nomenclature" href="nomenclature.html">Logtalk nomenclature</a></h2>
+    <dt><a href="features.html#features_scope">Logtalk scope</a><span class="leader"></span><span class="page-ref"><span class="features_scope"></span></span></dt>
+</dl>
+
+<h2><a id="nomenclature" href="nomenclature.html">Logtalk Nomenclature</a></h2>
 
 <dl class="toc-entries">
@@ -71 +71 @@
 </dl>
 
-<h2><a id="messages" href="messages.html">Message sending</a></h2>
+<h2><a id="messages" href="messages.html">Message Sending</a></h2>
 
 <dl class="toc-entries">
@@ -192 +192 @@
 </dl>
 
-<h2><a id="events" href="events.html">Event-driven programming</a></h2>
+<h2><a id="events" href="events.html">Event-driven Programming</a></h2>
 
 <dl class="toc-entries">
@@ -210 +210 @@
 </dl>
 
-<h2><a id="threads" href="threads.html">Multi-threading programming</a></h2>
+<h2><a id="threads" href="threads.html">Multi-threading Programming</a></h2>
 
 <dl class="toc-entries">
@@ -224 +224 @@
 </dl>
 
-<h2><a id="errors" href="errors.html">Error handling</a></h2>
+<h2><a id="errors" href="errors.html">Error Handling</a></h2>
 
 <dl class="toc-entries">
@@ -242 +242 @@
 </dl>
 
-<h2><a id="documenting" href="documenting.html">Documenting Logtalk programs</a></h2>
+<h2><a id="documenting" href="documenting.html">Documenting Logtalk Programs</a></h2>
 
 <dl class="toc-entries">
@@ -268 +268 @@
 </dl>
 
-<h2><a id="running" href="running.html">Running and debugging Logtalk programs</a></h2>
-
-<dl class="toc-entries">
-    <dt><a href="running.html#running_session">Running a Logtalk session</a><span class="leader"></span><span class="page-ref"><span class="running_session"></span></span></dt>
-        <dd><a href="running.html#running_starting">Starting Logtalk</a><span class="leader"></span><span class="page-ref"><span class="running_starting"></span></span></dd>
-        <dd><a href="running.html#running_compiling">Compiling and loading your programs</a><span class="leader"></span><span class="page-ref"><span class="running_compiling"></span></span></dd>
-        <dd><a href="running.html#running_flags">Compiler flags</a><span class="leader"></span><span class="page-ref"><span class="running_flags"></span></span></dd>
-        <dd><a href="running.html#running_smart">Realoding and smart compilation of source files</a><span class="leader"></span><span class="page-ref"><span class="running_smart"></span></span></dd>
-    <dt><a href="running.html#running_batch">Using Logtalk for batch processing</a><span class="leader"></span><span class="page-ref"><span class="running_batch"></span></span></dt>
-    <dt><a href="running.html#running_debugging">Debugging Logtalk programs</a><span class="leader"></span><span class="page-ref"><span class="running_debugging"></span></span></dt>
-        <dd><a href="running.html#running_debugmode">Compiling objects in debug mode</a><span class="leader"></span><span class="page-ref"><span class="running_debugmode"></span></span></dd>
-        <dd><a href="running.html#running_boxmodel">Logtalk Procedure Box model</a><span class="leader"></span><span class="page-ref"><span class="running_boxmodel"></span></span></dd>
-        <dd><a href="running.html#running_spypoints">Defining spy points</a><span class="leader"></span><span class="page-ref"><span class="running_spypoints"></span></span></dd>
-        <dd><a href="running.html#running_trace">Tracing program execution</a><span class="leader"></span><span class="page-ref"><span class="running_trace"></span></span></dd>
-        <dd><a href="running.html#running_debug">Debugging using spy points</a><span class="leader"></span><span class="page-ref"><span class="running_debug"></span></span></dd>
-        <dd><a href="running.html#running_commands">Debugging commands</a><span class="leader"></span><span class="page-ref"><span class="running_commands"></span></span></dd>
-        <dd><a href="running.html#running_context">Context-switching calls</a><span class="leader"></span><span class="page-ref"><span class="running_context"></span></span></dd>
-        <dd><a href="running.html#running_hooks">Using compilation hooks and term expansion for debugging</a><span class="leader"></span><span class="page-ref"><span class="running_hooks"></span></span></dd>
-</dl>
-
-<h2><a id="programming" href="programming.html">Programming in Logtalk</a></h2>
+<h2><a id="programming" href="programming.html">Writing, Running, and Debugging Logtalk programs</a></h2>
 
 <dl class="toc-entries">
@@ -298 +278 @@
         <dd><a href="programming.html#programming_errors">Avoiding common errors</a><span class="leader"></span><span class="page-ref"><span class="programming_errors"></span></span></dd>
         <dd><a href="programming.html#programming_style">Coding style guidlines</a><span class="leader"></span><span class="page-ref"><span class="programming_style"></span></span></dd>
-    <dt><a href="programming.html#programming_scope">Logtalk scope</a><span class="leader"></span><span class="page-ref"><span class="programming_scope"></span></span></dt>
+    <dt><a href="programming.html#programming_session">Running a Logtalk session</a><span class="leader"></span><span class="page-ref"><span class="programming_session"></span></span></dt>
+        <dd><a href="programming.html#programming_starting">Starting Logtalk</a><span class="leader"></span><span class="page-ref"><span class="programming_starting"></span></span></dd>
+        <dd><a href="programming.html#programming_compiling">Compiling and loading your programs</a><span class="leader"></span><span class="page-ref"><span class="programming_compiling"></span></span></dd>
+        <dd><a href="programming.html#programming_flags">Compiler flags</a><span class="leader"></span><span class="page-ref"><span class="programming_flags"></span></span></dd>
+        <dd><a href="programming.html#programming_smart">Realoding and smart compilation of source files</a><span class="leader"></span><span class="page-ref"><span class="programming_smart"></span></span></dd>
+        <dd><a href="programming.html#programming_batch">Using Logtalk for batch processing</a><span class="leader"></span><span class="page-ref"><span class="programming_batch"></span></span></dd>
+    <dt><a href="programming.html#programming_debugging">Debugging Logtalk programs</a><span class="leader"></span><span class="page-ref"><span class="programming_debugging"></span></span></dt>
+        <dd><a href="programming.html#programming_debugmode">Compiling objects in debug mode</a><span class="leader"></span><span class="page-ref"><span class="programming_debugmode"></span></span></dd>
+        <dd><a href="programming.html#programming_boxmodel">Logtalk Procedure Box model</a><span class="leader"></span><span class="page-ref"><span class="programming_boxmodel"></span></span></dd>
+        <dd><a href="programming.html#programming_spypoints">Defining spy points</a><span class="leader"></span><span class="page-ref"><span class="programming_spypoints"></span></span></dd>
+        <dd><a href="programming.html#programming_trace">Tracing program execution</a><span class="leader"></span><span class="page-ref"><span class="programming_trace"></span></span></dd>
+        <dd><a href="programming.html#programming_debug">Debugging using spy points</a><span class="leader"></span><span class="page-ref"><span class="programming_debug"></span></span></dd>
+        <dd><a href="programming.html#programming_commands">Debugging commands</a><span class="leader"></span><span class="page-ref"><span class="programming_commands"></span></span></dd>
+        <dd><a href="programming.html#programming_context">Context-switching calls</a><span class="leader"></span><span class="page-ref"><span class="programming_context"></span></span></dd>
+        <dd><a href="programming.html#programming_hooks">Using compilation hooks and term expansion for debugging</a><span class="leader"></span><span class="page-ref"><span class="programming_hooks"></span></span></dd>
 </dl>
 

trunk/manuals/userman/installing.html

@@ -168 +168 @@
 </p>
 <p>
-The configuration files specifies default values for all the Logtalk compiler flags. Most of these compiler flags are described in the <a href="running.html#options">next</a> section. A few of these flags have read-only values which cannot be changed at runtime. These are:
+The configuration files specifies default values for all the Logtalk compiler flags. Most of these compiler flags are described in the <a href="programming.html#options">next</a> section. A few of these flags have read-only values which cannot be changed at runtime. These are:
 </p>
 <dl>
@@ -229 +229 @@
     </div>
     <div class="navbottom">
-        <span><a href="documenting.html">previous</a> | <a href="../glossary.html">glossary</a> | <a href="running.html">next</a></span><br/>
+        <span><a href="documenting.html">previous</a> | <a href="../glossary.html">glossary</a> | <a href="programming.html">next</a></span><br/>
         <span><a href="http://validator.w3.org/check/referer">XHTML</a> + <a href="http://jigsaw.w3.org/css-validator/check/referer">CSS</a></span>
     </div>

trunk/manuals/userman/messages.html

@@ -150 +150 @@
     ... .</pre>
 <p>
-When events are not used, is possible to turn off event generation on a per object basis by using the <a title="Consult user manual" href="running.html#running_flags"><code>events/1</code></a> compiler option. See the session on <a href="events.html">event-driven programming</a> for more details.
+When events are not used, is possible to turn off event generation on a per object basis by using the <a title="Consult user manual" href="programming.html#programming_flags"><code>events/1</code></a> compiler option. See the session on <a href="events.html">event-driven programming</a> for more details.
 </p>
 
@@ -183 +183 @@
 </dl>
 <p>
-Given that events can be dynamically defined at runtime, there is no room for reducing the number of predicate calls without turning off support for event-driven programming. When events are defined, the number of predicate calls grows proportional to the number of events and event handlers (monitors). Event-driven programming support can be switched off for specific object using the compiler flag <a title="Consult compiler flag details" href="running.html#running_flags"><code>events/1</code></a>. Doing so, reduces the number of predicate calls from six to just two.
+Given that events can be dynamically defined at runtime, there is no room for reducing the number of predicate calls without turning off support for event-driven programming. When events are defined, the number of predicate calls grows proportional to the number of events and event handlers (monitors). Event-driven programming support can be switched off for specific object using the compiler flag <a title="Consult compiler flag details" href="programming.html#programming_flags"><code>events/1</code></a>. Doing so, reduces the number of predicate calls from six to just two.
 </p>
 <p>

trunk/manuals/userman/objects.html

@@ -431 +431 @@
 
 <p>
-Logtalk defines a built-in object named <code>debugger</code> which implements the Logtalk built-in debugger (see the section on <a href="running.html#debugging">debugging Logtalk programs</a> for details). This object is virtually compiled as a prototype. Programmers may define new prototypes extending <code>debugger</code> in order to implement custom debuggers.
+Logtalk defines a built-in object named <code>debugger</code> which implements the Logtalk built-in debugger (see the section on <a href="programming.html#programming_debugging">debugging Logtalk programs</a> for details). This object is virtually compiled as a prototype. Programmers may define new prototypes extending <code>debugger</code> in order to implement custom debuggers.
 </p>
 

trunk/manuals/userman/programming.html

@@ -7 +7 @@
 <head>
     <meta http-equiv="content-type" content="application/xml+xhtml; charset=utf-8" />
-    <title>Logtalk user manual: programming</title>
+    <title>Logtalk user manual: writing, running, and debugging programs</title>
     <link rel="stylesheet" href="../screen.css" type="text/css" media="screen"/>
     <link rel="stylesheet" href="../print.css" type="text/css" media="print"/>
@@ -15 +15 @@
 
 <div class="top-left">Logtalk user manual</div> 
-<div class="top-right">Programming in Logtalk</div>
+<div class="top-right">Writing, running, and debugging programs</div>
 <div class="bottom-left"><span class="page"/></div> 
 <div class="bottom-right"><span class="page"/></div>
 <div class="navtop"><a href="../index.html">contents</a> &gt; <a href="index.html">user manual</a></div>
 
-<h1 id="programming_programming">Programming in Logtalk</h1>
+<h1 id="programming_running">Writing, running, and debugging programs</h1>
+
 
 <h2 id="programming_writing">Writing programs</h2>
@@ -41 +42 @@
 <p>
 The text encoding used in a source file may be declared using the <a title="Consult reference manual" href="../refman/directives/encoding1.html"><code>encoding/1</code></a> directive when running Logtalk with some back-end Prolog compilers that support multiple encodings (check the <code>encoding_directive</code> flag in the configuration file of your Prolog compiler). The encoding used (and, in the case of a Unicode encoding, any BOM present) in a source file will be used for the generated Prolog and XML files. Logtalk uses the encoding names specified by <a title="" href="http://www.iana.org/assignments/character-sets">IANA</a> (in those cases where a preferred MIME name alias is specified, the alias is used instead).
+</p>
+
+<h3 id="programming_portability">Portable programs</h3>
+
+<p>
+Logtalk is compatible with almost all modern Prolog compilers. However, this does not necessarily imply that your Logtalk programs will have the same level of portability. If possible, you should only use in your programs Logtalk built-in predicates and ISO Prolog specified built-in predicates and arithmetic functions. If you need to use built-in predicates (or built-in arithmetic functions) that may not be available in other Prolog compilers, you should try to encapsulate the non-portable code in a small number of objects and provide a portable <strong>interface</strong> for that code through the use of Logtalk protocols. An example will be code that access operating-system specific features. The Logtalk compiler can warn you of the use of non-ISO specified built-in predicates and arithmetic functions by using the <code>portability/1</code> compiler flag.
+</p>
+
+<h3 id="programming_errors">Avoiding common errors</h3>
+
+<p>
+Try to write objects and protocol documentation <strong>before</strong> writing any other code; if you are having trouble documenting a predicate perhaps we need to go back to the design stage.
+</p>
+<p>
+Try to avoid lengthy hierarchies. Besides performance penalties, composition is often a better choice over inheritance for defining new objects (Logtalk supports component-based programming through the use of categories). In addition, prototype-based hierarchies are conceptually simpler and more efficient than class-based hierarchies.
+</p>
+<p>
+Dynamic predicates or dynamic entities are sometimes needed, but we should always try to minimize the use of non-logical features like destructive assignment (asserts and retracts).
+</p>
+<p>
+Since each Logtalk entity is independently compiled, if an object inherits a dynamic or a meta-predicate predicate, then we must repeat the respective directives in order to ensure a correct compilation. 
+</p>
+<p>
+In general, Logtalk does not verify if a user predicate call/return arguments comply with the declared modes. On the other hand, Logtalk built-in predicates, built-in methods, and message sending control structures are carefully checked for calling mode errors.
+</p>
+<p>
+Logtalk error handling strongly depends on the ISO compliance of the chosen Prolog compiler. For instance, the error terms that are generated by some Logtalk built-in predicates assume that the Prolog built-in predicates behave as defined in the ISO standard regarding error conditions. In particular, if your Prolog compiler does not support a <code>read_term/3</code> built-in predicate compliant with the ISO Prolog Standard definition, then the current version of the Logtalk compiler may not be able to detect misspell variables in your source code.
+</p>
+
+<h3 id="programming_style">Coding style guidelines</h3>
+
+<p>
+It is suggested that all code between an entity opening and closing directives be indented by one tab stop. When defining entity code, both directives and predicates, Prolog coding style guidelines may be applied. All Logtalk source files, examples, and standard library entities use four-space tabs for laying out code. Closed related entities should be defined in the same source file. Entities that might be useful in different contexts (such as library entities) are best defined in their own source files.
+</p>
+
+
+<h2 id="programming_session">Running a Logtalk session</h2>
+
+<p>
+We run Logtalk inside a normal Prolog session, after loading the necessary files. Logtalk extends but does not modify your Prolog compiler. We can freely mix Prolog queries with the sending of messages and our programs can be made of both normal Prolog clauses and object definitions.
+</p>
+
+<h3 id="programming_starting">Starting Logtalk</h3>
+
+<p>
+Depending on your Logtalk installation, you may use a script or a shortcut to start Logtalk with your chosen Prolog compiler. On POSIX operating systems, the scripts should be available from the command-line; scripts are named upon the used Prolog compilers. On Windows, the shortcuts should be available from the Start Menu. If no scripts or shortcuts are available for your installation, operating-system, or Prolog compiler, you can always start a Logtalk session by performing the following steps:
+</p>
+<ol>
+    <li>Start your Prolog compiler.</li>
+    <li>Load the appropriate configuration file for your compiler. Configuration files for most common Prolog compilers can be found in the <code>configs</code> subdirectory.</li>
+    <li>Load the Logtalk compiler/runtime files contained in the <code>compiler</code> subdirectory.</li>
+    <li>Load the library paths configuration file corresponding to your Logtalk installation contained in the <code>libpaths</code> subdirectory.</li>
+</ol>
+<p>
+Note that the configuration files, compiler/runtime files, and library paths file are Prolog source files. The predicate called to load (and compile) them depends on your Prolog compiler. In case of doubt, consult your Prolog compiler reference manual or take a look at the definition of the predicate <code>'$lgt_load_prolog_code'/3</code> in the corresponding configuration file.
+</p>
+<p>
+Most Prolog compilers support automatic loading of an initialization file, which can include the necessary directives to load both the Prolog configuration file and the Logtalk compiler. This feature, when available, allows automatic loading of Logtalk when you start your Prolog compiler.
+</p>
+
+<h3 id="programming_compiling">Compiling and loading your programs</h3>
+
+<p>
+Your programs will be made of source files containing your objects, protocols, and categories. After changing the Prolog working directory to the one containing your files, you can compile them to disk by calling the Logtalk built-in predicate  
+<a title="Consult reference manual" href="../refman/builtins/logtalk_compile1.html"><code>logtalk_compile/1</code></a>:
+</p>
+<pre>| ?- logtalk_compile([source_file1, source_file2, ...]).</pre>
+<p>
+This predicate runs the compiler on each argument file and, if no fatal errors are found, outputs Prolog source files that can then be consulted or compiled in the usual way by your Prolog compiler.
+</p>
+<p>
+To compile to disk and also load into memory the source files we can use the Logtalk built-in predicate <a title="Consult reference manual" href="../refman/builtins/logtalk_load1.html"><code>logtalk_load/1</code></a>:
+</p>
+<pre>| ?- logtalk_load([source_file1, source_file2, ...]).</pre>
+<p>
+This predicate works in the same way of the predicate <code>logtalk_compile/1</code> but also loads the compiled files to memory. 
+</p>
+<p>
+Both predicates expect a source name name or a list of source name names as an argument. The Logtalk source file name extension, as defined in the configuration file, must be omitted.
+</p>
+<p>
+If you have more than a few source files then you may want to use a loader helper file containing the calls to the <code>logtalk_load/1-2</code> predicates. Consulting or compiling the loader file will then compile and load all your Logtalk entities into memory (see below for details).
+</p>
+<p>
+With most Prolog back-end compilers, you can use the shorthand <code>{File}</code> for <code>logtalk_load(File)</code>. The use this shorthand should be restricted to the Logtak/Prolog top-level; do not use it from within source files.
 </p>
 
@@ -96 +182 @@
 </p>
 
-<h3 id="programming_portability">Portable programs</h3>
-
-<p>
-Logtalk is compatible with almost all modern Prolog compilers. However, this does not necessarily imply that your Logtalk programs will have the same level of portability. If possible, you should only use in your programs Logtalk built-in predicates and ISO Prolog specified built-in predicates and arithmetic functions. If you need to use built-in predicates (or built-in arithmetic functions) that may not be available in other Prolog compilers, you should try to encapsulate the non-portable code in a small number of objects and provide a portable <strong>interface</strong> for that code through the use of Logtalk protocols. An example will be code that access operating-system specific features. The Logtalk compiler can warn you of the use of non-ISO specified built-in predicates and arithmetic functions by using the <code>portability/1</code> compiler flag.
-</p>
-
-<h3 id="programming_errors">Avoiding common errors</h3>
-
-<p>
-Try to write objects and protocol documentation <strong>before</strong> writing any other code; if you are having trouble documenting a predicate perhaps we need to go back to the design stage.
-</p>
-<p>
-Try to avoid lengthy hierarchies. Besides performance penalties, composition is often a better choice over inheritance for defining new objects (Logtalk supports component-based programming through the use of categories). In addition, prototype-based hierarchies are conceptually simpler and more efficient than class-based hierarchies.
-</p>
-<p>
-Dynamic predicates or dynamic entities are sometimes needed, but we should always try to minimize the use of non-logical features like destructive assignment (asserts and retracts).
-</p>
-<p>
-Since each Logtalk entity is independently compiled, if an object inherits a dynamic or a meta-predicate predicate, then we must repeat the respective directives in order to ensure a correct compilation. 
-</p>
-<p>
-In general, Logtalk does not verify if a user predicate call/return arguments comply with the declared modes. On the other hand, Logtalk built-in predicates, built-in methods, and message sending control structures are carefully checked for calling mode errors.
-</p>
-<p>
-Logtalk error handling strongly depends on the ISO compliance of the chosen Prolog compiler. For instance, the error terms that are generated by some Logtalk built-in predicates assume that the Prolog built-in predicates behave as defined in the ISO standard regarding error conditions. In particular, if your Prolog compiler does not support a <code>read_term/3</code> built-in predicate compliant with the ISO Prolog Standard definition, then the current version of the Logtalk compiler may not be able to detect misspell variables in your source code.
-</p>
-
-<h3 id="programming_style">Coding style guidelines</h3>
-
-<p>
-It is suggested that all code between an entity opening and closing directives be indented by one tab stop. When defining entity code, both directives and predicates, Prolog coding style guidelines may be applied. All Logtalk source files, examples, and standard library entities use four-space tabs for laying out code. Closed related entities should be defined in the same source file. Entities that might be useful in different contexts (such as library entities) are best defined in their own source files.
-</p>
-
-
-<h2 id="programming_scope">Logtalk scope</h2>
-
-<p>
-Logtalk, being a superset of Prolog, shares with it the same preferred areas of application but also extends them with those areas where object-oriented features provide an advantage compared to plain Prolog. Among these areas we have:
+<h3 id="programming_flags">Compiler flags</h3>
+
+<p>
+The <a title="Consult reference manual" href="../refman/builtins/logtalk_load1.html"><code>logtalk_load/1</code></a> and <a title="Consult reference manual" href="../refman/builtins/logtalk_compile1.html"><code>logtalk_compile/1</code></a> always use the current set of default compiler flags as specified in the Logtalk configuration files or changed for the current session using the built-in predicate <a title="Consult reference manual" href="../refman/builtins/set_logtalk_flag2.html"><code>set_logtalk_flag/2</code></a>. Although the default flag values cover the usual cases, you may want to use a different set of flag values while compiling or loading some of your Logtalk source files. This can be accomplished by using the <a title="Consult reference manual" href="../refman/builtins/logtalk_load2.html"><code>logtalk_load/2</code></a> or the <a title="Consult reference manual" href="../refman/builtins/logtalk_compile2.html"><code>logtalk_compile/2</code></a> built-in predicates. These two predicates accept a list of flag values affecting how a Logtalk source file is compiled and loaded:
+</p>
+<pre>| ?- logtalk_compile(Files, Flags).</pre>
+<p>
+or:
+</p>
+<pre>| ?- logtalk_load(Files, Flags).</pre>
+<p>
+In fact, the <code>logtalk_load/1</code> and <code>logtalk_compile/1</code> predicates are just shortcuts to the extended versions called with the default compiler flag values.
+</p>
+<p>
+We may also change the default flag values from the ones loaded from the config file by using the <a title="Consult reference manual" href="../refman/builtins/set_logtalk_flag2.html"><code>set_logtalk_flag/2</code></a> built-in predicate. For example:
+</p>
+<pre>| ?- set_logtalk_flag(xmldocs, off).</pre>
+<p>
+The current default flags values can be enumerated using the <a title="Consult reference manual" href="../refman/builtins/current_logtalk_flag2.html"><code>current_logtalk_flag/2</code></a> built-in predicate:
+</p>
+<pre>| ?- current_logtalk_flag(xmldocs, Value).
+
+Value = off
+yes</pre>
+<p>
+Logtalk also implements a <a title="Consult reference manual" href="../refman/directives/set_logtalk_flag2.html"><code>set_logtalk_flag/2</code></a> directive, which can be used to set flags within a source file. For example, assuming a source file defining several entities, you may want to use different settings for compiling each entity. This can be easily accomplished by preceding each entity with the necessary <code>set_logtalk_flag/2</code> directives. Note that the scope of this directive is local to the source file containing it.
+<p>
+
+<h4>Lint flags</h4>
+
+    <dl>
+        <dt><code>unknown(Option)</code></dt>
+            <dd>Controls the unknown entity warnings, resulting from loading an entity that references some other entity that is not currently loaded. Possible option values are <code>warning</code> (the usual default) and <code>silent</code>. Note that these warnings are not always avoidable, specially when using reflective designs of class-based hierarchies.</dd>
+    </dl>
+    <dl>
+        <dt><code>misspelt(Option)</code></dt>
+            <dd>Controls the misspelt predicate call warnings. A misspelt call is a call to a predicate which is not defined in the object or category containing the call, is not declared as dynamic, and is not a Logtalk/Prolog built-in predicate. Possible option values are <code>error</code>, <code>warning</code> (the usual default), and <code>silent</code> (not recommended).</dd>
+    </dl>
+    <dl>
+        <dt><code>lgtredef(Option)</code></dt>
+            <dd>Controls the Logtalk built-in predicate redefinition warnings. Possible option values are <code>warning</code> (the usual default) and <code>silent</code>. These warnings are almost always programming errors.</dd>
+    </dl>
+    <dl>
+        <dt><code>plredef(Option)</code></dt>
+            <dd>Controls the Prolog built-in predicate redefinition warnings. Possible option values are <code>warning</code> (can be very verbose if your code redefines a lot of Prolog built-in predicates) and <code>silent</code> (the usual default). When running a Logtalk application on several Prolog compilers, is possible to get different sets of warnings due to different sets of built-in predicates implemented by each Prolog compiler.</dd>
+    </dl>
+    <dl>
+        <dt><code>portability(Option)</code></dt>
+            <dd>Controls the non-ISO specified built-in predicate and non-ISO specified built-in arithmetic function calls warnings. Possible option values are <code>warning</code> and <code>silent</code> (the usual default).</dd>
+    </dl>
+    <dl>
+        <dt><code>singletons(Option)</code></dt>
+            <dd>Controls the singleton variable warnings. Possible option values are <code>warning</code> (the usual default) and <code>silent</code> (not recommended).</dd>
+    </dl>
+    <dl>
+        <dt><code>underscore_variables(Option)</code></dt>
+            <dd>Controls the interpretation of variables that start with an underscore (excluding the anonymous variable) that occur once in a term as either don't care variables or singleton variables. Possible option values are <code>dont_care</code> and <code>singletons</code> (the usual default). Note that, depending on your Prolog compiler, the <code>read_term/3</code> built-in predicate may report variables that start with an underscore as singleton variables. There is no standard behavior, hence this option.</dd>
+    </dl>
+
+
+<h4>Documenting flags</h4>
+
+    <dl>
+        <dt><code>xmldocs(Option)</code></dt>
+            <dd>Controls the automatic generation of documenting files in XML format. Possible option values are <code>on</code> (the usual default) and <code>off</code>.</dd>
+    </dl>
+    <dl>