commit 9f8f150e3667b9673924e74c06f74cbefdcf35a1
parent 99233ce522a02d1d8eeb4d7e4bf91ab01ce4c811
Author: Alexander Burger <abu@software-lab.de>
Date: Sun, 11 Nov 2012 15:47:42 +0100
Document "debug mode only" functions
Diffstat:
14 files changed, 106 insertions(+), 99 deletions(-)
diff --git a/doc/refB.html b/doc/refB.html
@@ -147,8 +147,9 @@ href="refC.html#char">char</a></code>.
</code></pre>
<dt><a name="bench"><code>(bench . prg) -> any</code></a>
-<dd>Benchmarks <code>prg</code>, by printing the time it took to execute, and
-returns the result. See also <code><a href="refU.html#usec">usec</a></code>.
+<dd>(Debug mode only) Benchmarks <code>prg</code>, by printing the time it took
+to execute, and returns the result. See also <code><a
+href="refU.html#usec">usec</a></code>.
<pre><code>
: (bench (wait 2000))
diff --git a/doc/refC.html b/doc/refC.html
@@ -98,9 +98,9 @@ term can be proven.
</code></pre>
<dt><a name="can"><code>(can 'msg) -> lst</code></a>
-<dd>Returns a list of all classes that accept the message <code>msg</code>. See
-also <code><a href="ref.html#oop">OO Concepts</a></code>, <code><a
-href="refC.html#class">class</a></code>, <code><a
+<dd>(Debug mode only) Returns a list of all classes that accept the message
+<code>msg</code>. See also <code><a href="ref.html#oop">OO Concepts</a></code>,
+<code><a href="refC.html#class">class</a></code>, <code><a
href="refD.html#dep">dep</a></code>, <code><a
href="refW.html#what">what</a></code> and <code><a
href="refW.html#who">who</a></code>.
diff --git a/doc/refD.html b/doc/refD.html
@@ -106,10 +106,11 @@ or this position is deleted from the order:
</code></pre>
<dt><a name="d"><code>(d) -> T</code></a>
-<dd>Inserts <code><a href="ref_.html#!">!</a></code> breakpoints into all
-subexpressions of the current breakpoint. Typically used when single-stepping a
-function or method with <code><a href="refD.html#debug">debug</a></code>. See
-also <code><a href="refU.html#u">u</a></code> and <code><a
+<dd>(Debug mode only) Inserts <code><a href="ref_.html#!">!</a></code>
+breakpoints into all subexpressions of the current breakpoint. Typically used
+when single-stepping a function or method with <code><a
+href="refD.html#debug">debug</a></code>. See also <code><a
+href="refU.html#u">u</a></code> and <code><a
href="refU.html#unbug">unbug</a></code>.
<pre><code>
@@ -442,13 +443,13 @@ href="refU.html#undef">undef</a></code>.
<dt><a name="debug"><code>(debug 'sym) -> T</code></a>
<dt><code>(debug 'sym 'cls) -> T</code>
<dt><code>(debug '(sym . cls)) -> T</code>
-<dd>Inserts a <code><a href="ref_.html#!">!</a></code> breakpoint function call
-at the beginning and all top-level expressions of the function or method body of
-<code>sym</code>, to allow a stepwise execution. Typing <code>(<a
-href="refD.html#d">d</a>)</code> at a breakpoint will also debug the current
-subexpression, and <code>(<a href="refE.html#e">e</a>)</code> will evaluate the
-current subexpression. The current subexpression is stored in the global
-variable <code><a href="ref_.html#^">^</a></code>. See also <code><a
+<dd>(Debug mode only) Inserts a <code><a href="ref_.html#!">!</a></code>
+breakpoint function call at the beginning and all top-level expressions of the
+function or method body of <code>sym</code>, to allow a stepwise execution.
+Typing <code>(<a href="refD.html#d">d</a>)</code> at a breakpoint will also
+debug the current subexpression, and <code>(<a href="refE.html#e">e</a>)</code>
+will evaluate the current subexpression. The current subexpression is stored in
+the global variable <code><a href="ref_.html#^">^</a></code>. See also <code><a
href="refU.html#unbug">unbug</a></code>, <code><a
href="refD.html#*Dbg">*Dbg</a></code>, <code><a
href="refT.html#trace">trace</a></code> and <code><a
@@ -606,8 +607,8 @@ href="refM.html#mmeq">mmeq</a></code> and <a href="ref.html#cmp">Comparing</a>.
</code></pre>
<dt><a name="dep"><code>(dep 'cls) -> cls</code></a>
-<dd>Displays the "dependencies" of <code>cls</code>, i.e. the tree of
-superclasses and the tree of subclasses. See also <code><a
+<dd>(Debug mode only) Displays the "dependencies" of <code>cls</code>, i.e. the
+tree of superclasses and the tree of subclasses. See also <code><a
href="ref.html#oop">OO Concepts</a></code>, <code><a
href="refC.html#class">class</a></code> and <code><a
href="refC.html#can">can</a></code>.
@@ -731,13 +732,13 @@ OK done -> done
</code></pre>
<dt><a name="doc"><code>(doc ['sym1] ['sym2])</code></a>
-<dd>Opens a browser, and tries to display the reference documentation for
-<code>sym1</code>. <code>sym2</code> may be the name of a browser. If not given,
-the value of the environment variable <code>BROWSER</code>, or the
-<code>w3m</code> browser is tried. If <code>sym1</code> is <code>NIL</code>, the
-<a href="ref.html">PicoLisp Reference</a> manual is opened. See also <a
-href="ref.html#fun">Function Reference</a> and <code><a
-href="refV.html#vi">vi</a></code>.
+<dd>(Debug mode only) Opens a browser, and tries to display the reference
+documentation for <code>sym1</code>. <code>sym2</code> may be the name of a
+browser. If not given, the value of the environment variable
+<code>BROWSER</code>, or the <code>w3m</code> browser is tried. If
+<code>sym1</code> is <code>NIL</code>, the <a href="ref.html">PicoLisp
+Reference</a> manual is opened. See also <a href="ref.html#fun">Function
+Reference</a> and <code><a href="refV.html#vi">vi</a></code>.
<pre><code>
: (doc '+) # Function reference
diff --git a/doc/refE.html b/doc/refE.html
@@ -142,15 +142,15 @@ successfully completed. See also <code><a href="refF.html#from">from</a></code>.
</code></pre>
<dt><a name="edit"><code>(edit 'sym ..) -> NIL</code></a>
-<dd>Edits the value and property list of the argument symbol(s) by calling the
-<code>vim</code> editor on a temporary file with these data. When closing the
-editor, the modified data are read and stored into the symbol(s). During the
-edit session, individual symbols are separated by the pattern
-<code>(********)</code>. These separators should not be modified. When moving
-the cursor to the beginning of a symbol (no matter if internal, transient or
-external), and hitting '<code>K</code>', that symbol is added to the currently
-edited symbols. Hitting '<code>Q</code>' will go back one step and return to the
-previously edited list of symbols.
+<dd>(Debug mode only) Edits the value and property list of the argument
+symbol(s) by calling the <code>vim</code> editor on a temporary file with these
+data. When closing the editor, the modified data are read and stored into the
+symbol(s). During the edit session, individual symbols are separated by the
+pattern <code>(********)</code>. These separators should not be modified. When
+moving the cursor to the beginning of a symbol (no matter if internal, transient
+or external), and hitting '<code>K</code>', that symbol is added to the
+currently edited symbols. Hitting '<code>Q</code>' will go back one step and
+return to the previously edited list of symbols.
<p><code>edit</code> is especially useful for browsing through the database
(with '<code>K</code>' and '<code>Q</code>'), inspecting external symbols, but
diff --git a/doc/refH.html b/doc/refH.html
@@ -76,8 +76,8 @@ href="refO.html#oct">oct</a></code>.
</code></pre>
<dt><a name="hd"><code>(hd 'sym ['cnt]) -> NIL</code></a>
-<dd>Displays a hexadecimal dump of the file given by <code>sym</code>, limited
-to <code>cnt</code> lines. See also <code><a
+<dd>(Debug mode only) Displays a hexadecimal dump of the file given by
+<code>sym</code>, limited to <code>cnt</code> lines. See also <code><a
href="refP.html#proc">proc</a></code>.
<pre><code>
diff --git a/doc/refL.html b/doc/refL.html
@@ -12,9 +12,9 @@
<dl>
<dt><a name="*Led"><code>*Led</code></a>
-<dd>A global variable holding a (possibly empty) <code>prg</code> body that
-implements a "Line editor". When non-<code>NIL</code>, it should return a single
-symbol (string) upon execution.
+<dd>(Debug mode only) A global variable holding a (possibly empty)
+<code>prg</code> body that implements a "Line editor". When
+non-<code>NIL</code>, it should return a single symbol (string) upon execution.
<pre><code>
: (de *Led "(bye)")
@@ -70,8 +70,8 @@ href="refP.html#pipe">pipe</a></code>'ed child process. The return value of
</code></pre>
<dt><a name="ld"><code>(ld) -> any</code></a>
-<dd><code><a href="refL.html#load">load</a></code>s the last file edited with
-<code><a href="refV.html#vi">vi</a></code>.
+<dd>(Debug mode only) <code><a href="refL.html#load">load</a></code>s the last
+file edited with <code><a href="refV.html#vi">vi</a></code>.
<pre><code>
: (vi 'main)
@@ -258,12 +258,13 @@ href="refM.html#made">made</a></code>.
<dt><a name="lint"><code>(lint 'sym) -> lst</code></a>
<dt><code>(lint 'sym 'cls) -> lst</code>
<dt><code>(lint '(sym . cls)) -> lst</code>
-<dd>Checks the function definition or file contents (in the first form), or the
-method body of sym (second and third form), for possible pitfalls. Returns an
-association list of diagnoses, where <code>var</code> indicates improper
-variables, <code>dup</code> duplicate parameters, <code>def</code> an undefined
-function, <code>bnd</code> an unbound variable, and <code>use</code> unused
-variables. See also <code><a href="refN.html#noLint">noLint</a></code>, <code><a
+<dd>(Debug mode only) Checks the function definition or file contents (in the
+first form), or the method body of sym (second and third form), for possible
+pitfalls. Returns an association list of diagnoses, where <code>var</code>
+indicates improper variables, <code>dup</code> duplicate parameters,
+<code>def</code> an undefined function, <code>bnd</code> an unbound variable,
+and <code>use</code> unused variables. See also <code><a
+href="refN.html#noLint">noLint</a></code>, <code><a
href="refL.html#lintAll">lintAll</a></code>, <code><a
href="refD.html#debug">debug</a></code>, <code><a
href="refT.html#trace">trace</a></code> and <code><a
@@ -279,10 +280,10 @@ href="refD.html#*Dbg">*Dbg</a></code>.
</code></pre>
<dt><a name="lintAll"><code>(lintAll ['sym ..]) -> lst</code></a>
-<dd>Applies <code><a href="refL.html#lint">lint</a></code> to <code><a
-href="refA.html#all">all</a></code> internal symbols - and optionally to all
-files <code>sym</code> - and returns a list of diagnoses. See also <code><a
-href="refN.html#noLint">noLint</a></code>.
+<dd>(Debug mode only) Applies <code><a href="refL.html#lint">lint</a></code> to
+<code><a href="refA.html#all">all</a></code> internal symbols - and optionally
+to all files <code>sym</code> - and returns a list of diagnoses. See also
+<code><a href="refN.html#noLint">noLint</a></code>.
<pre><code>
: (more (lintAll "file1.l" "file2.l"))
diff --git a/doc/refM.html b/doc/refM.html
@@ -556,13 +556,13 @@ href="refF.html#format">format</a></code>.
<dt><a name="more"><code>(more 'lst ['fun]) -> flg</code></a>
<dt><code>(more 'cls) -> any</code>
-<dd>Displays the elements of <code>lst</code> (first form), or the type and
-methods of <code>cls</code> (second form). <code>fun</code> defaults to <code><a
-href="refP.html#print">print</a></code>. In the second form, the method
-definitions of <code>cls</code> are pretty-printed with <code><a
-href="refP.html#pp">pp</a></code>. After each step, <code>more</code> waits for
-console input, and terminates when a non-empty line is entered. In that case,
-<code>T</code> is returned, otherwise (when end of data is reached)
+<dd>(Debug mode only) Displays the elements of <code>lst</code> (first form), or
+the type and methods of <code>cls</code> (second form). <code>fun</code>
+defaults to <code><a href="refP.html#print">print</a></code>. In the second
+form, the method definitions of <code>cls</code> are pretty-printed with
+<code><a href="refP.html#pp">pp</a></code>. After each step, <code>more</code>
+waits for console input, and terminates when a non-empty line is entered. In
+that case, <code>T</code> is returned, otherwise (when end of data is reached)
<code>NIL</code>. See also <code><a href="refQ.html#query">query</a></code> and
<code><a href="refS.html#show">show</a></code>.
diff --git a/doc/refN.html b/doc/refN.html
@@ -349,11 +349,12 @@ href="refN.html#not/1">not/1</a></code>.
<dt><a name="noLint"><code>(noLint 'sym)</code></a>
<dt><code>(noLint 'sym|(sym . cls) 'sym2)</code>
-<dd>Excludes the check for a function definition of <code>sym</code> (in the
-first form), or for variable binding and usage of <code>sym2</code> in the
-function definition, file contents or method body of <code>sym</code> (second
-form), during calls to <code><a href="refL.html#lint">lint</a></code>. See also
-<code><a href="refL.html#lintAll">lintAll</a></code>.
+<dd>(Debug mode only) Excludes the check for a function definition of
+<code>sym</code> (in the first form), or for variable binding and usage of
+<code>sym2</code> in the function definition, file contents or method body of
+<code>sym</code> (second form), during calls to <code><a
+href="refL.html#lint">lint</a></code>. See also <code><a
+href="refL.html#lintAll">lintAll</a></code>.
<pre><code>
: (de foo ()
diff --git a/doc/refP.html b/doc/refP.html
@@ -637,9 +637,9 @@ href="refM.html#memq">memq</a></code>.
</code></pre>
<dt><a name="proc"><code>(proc 'sym ..) -> T</code></a>
-<dd>Shows a list of processes with command names given by the <code>sym</code>
-arguments, using the system <code>ps</code> utility. See also <code><a
-href="refH.html#hd">hd</a></code>.
+<dd>(Debug mode only) Shows a list of processes with command names given by the
+<code>sym</code> arguments, using the system <code>ps</code> utility. See also
+<code><a href="refH.html#hd">hd</a></code>.
<pre><code>
: (proc 'pil)
diff --git a/doc/refS.html b/doc/refS.html
@@ -252,8 +252,8 @@ href="refP.html#pick">pick</a></code>.
</code></pre>
<dt><a name="select"><code>(select [var ..] cls [hook|T] [var val ..]) -> obj | NIL</code></a>
-<dd>Interactive database function, loosely modelled after the SQL
-'<code>SELECT</code>' command. A (limited) front-end to the Pilog <code><a
+<dd>(Debug mode only) Interactive database function, loosely modelled after the
+SQL '<code>SELECT</code>' command. A (limited) front-end to the Pilog <code><a
href="refS.html#select/3">select/3</a></code> predicate. When called with only a
<code>cls</code> argument, <code>select</code> steps through all objects of that
class, and <code><a href="refS.html#show">show</a></code>s their complete
diff --git a/doc/refT.html b/doc/refT.html
@@ -452,12 +452,12 @@ modified.
<dt><a name="trace"><code>(trace 'sym) -> sym</code></a>
<dt><code>(trace 'sym 'cls) -> sym</code>
<dt><code>(trace '(sym . cls)) -> sym</code>
-<dd>Inserts a <code><a href="ref_.html#$">$</a></code> trace function call at
-the beginning of the function or method body of <code>sym</code>, so that trace
-information will be printed before and after execution. Built-in functions
-(C-function pointer) are automatically converted to Lisp expressions (see
-<code><a href="refE.html#expr">expr</a></code>). See also <code><a
-href="refD.html#*Dbg">*Dbg</a></code>, <code><a
+<dd>(Debug mode only) Inserts a <code><a href="ref_.html#$">$</a></code> trace
+function call at the beginning of the function or method body of
+<code>sym</code>, so that trace information will be printed before and after
+execution. Built-in functions (C-function pointer) are automatically converted
+to Lisp expressions (see <code><a href="refE.html#expr">expr</a></code>). See
+also <code><a href="refD.html#*Dbg">*Dbg</a></code>, <code><a
href="refT.html#traceAll">traceAll</a></code> and <code><a
href="refU.html#untrace">untrace</a></code>, <code><a
href="refD.html#debug">debug</a></code> and <code><a
@@ -473,7 +473,7 @@ href="refL.html#lint">lint</a></code>.
</code></pre>
<dt><a name="traceAll"><code>(traceAll ['lst]) -> sym</code></a>
-<dd>Traces all Lisp level functions by inserting a <code><a
+<dd>(Debug mode only) Traces all Lisp level functions by inserting a <code><a
href="ref_.html#$">$</a></code> function call at the beginning. <code>lst</code>
may contain symbols which are to be excluded from that process. In addition, all
symbols in the global variable <code>*NoTrace</code> are excluded. See also
diff --git a/doc/refU.html b/doc/refU.html
@@ -82,10 +82,11 @@ access to multidimensional data. Only numeric keys are supported. See also
</code></pre>
<dt><a name="u"><code>(u) -> T</code></a>
-<dd>Removes <code><a href="ref_.html#!">!</a></code> all breakpoints in all
-subexpressions of the current breakpoint. Typically used when single-stepping a
-function or method with <code><a href="refD.html#debug">debug</a></code>. See
-also <code><a href="refD.html#d">d</a></code> and <code><a
+<dd>(Debug mode only) Removes <code><a href="ref_.html#!">!</a></code> all
+breakpoints in all subexpressions of the current breakpoint. Typically used when
+single-stepping a function or method with <code><a
+href="refD.html#debug">debug</a></code>. See also <code><a
+href="refD.html#d">d</a></code> and <code><a
href="refU.html#unbug">unbug</a></code>.
<pre><code>
@@ -139,8 +140,8 @@ href="refW.html#week">week</a></code>.
<dt><a name="unbug"><code>(unbug 'sym) -> T</code></a>
<dt><code>(unbug 'sym 'cls) -> T</code>
<dt><code>(unbug '(sym . cls)) -> T</code>
-<dd>Removes all <code><a href="ref_.html#!">!</a></code> breakpoints in the
-function or method body of sym, as inserted with <code><a
+<dd>(Debug mode only) Removes all <code><a href="ref_.html#!">!</a></code>
+breakpoints in the function or method body of sym, as inserted with <code><a
href="refD.html#debug">debug</a></code> or <code><a
href="refD.html#d">d</a></code>, or directly with <code><a
href="refE.html#edit">edit</a></code>. See also <code><a
@@ -253,11 +254,12 @@ T
<dt><a name="untrace"><code>(untrace 'sym) -> sym</code></a>
<dt><code>(untrace 'sym 'cls) -> sym</code>
<dt><code>(untrace '(sym . cls)) -> sym</code>
-<dd>Removes the <code><a href="ref_.html#$">$</a></code> trace function call at
-the beginning of the function or method body of <code>sym</code>, so that no
-more trace information will be printed before and after execution. Built-in
-functions (C-function pointer) are automatically converted to their original
-form (see <code><a href="refS.html#subr">subr</a></code>). See also <code><a
+<dd>(Debug mode only) Removes the <code><a href="ref_.html#$">$</a></code> trace
+function call at the beginning of the function or method body of
+<code>sym</code>, so that no more trace information will be printed before and
+after execution. Built-in functions (C-function pointer) are automatically
+converted to their original form (see <code><a
+href="refS.html#subr">subr</a></code>). See also <code><a
href="refT.html#trace">trace</a></code> and <code><a
href="refT.html#traceAll">traceAll</a></code>.
@@ -300,12 +302,12 @@ during database <code><a href="ref.html#trans">transactions</a></code>.
</code></pre>
<dt><a name="update"><code>(update 'obj ['var]) -> obj</code></a>
-<dd>Interactive database function for modifying external symbols. When called
-only with an <code>obj</code> argument, <code>update</code> steps through the
-value and all properties of that object (and recursively also through
-substructures) and allows to edit them with the console line editor. When the
-<code>var</code> argument is given, only that single property is handed to the
-editor. To delete a propery, <code>NIL</code> must be explicitly entered.
+<dd>(Debug mode only) Interactive database function for modifying external
+symbols. When called only with an <code>obj</code> argument, <code>update</code>
+steps through the value and all properties of that object (and recursively also
+through substructures) and allows to edit them with the console line editor.
+When the <code>var</code> argument is given, only that single property is handed
+to the editor. To delete a propery, <code>NIL</code> must be explicitly entered.
<code>update</code> will correctly handle all <a
href="ref.html#er">entity/relation</a> mechanisms. See also <code><a
href="refS.html#select">select</a></code>, <code><a
diff --git a/doc/refV.html b/doc/refV.html
@@ -105,8 +105,8 @@ $ pil -version
<dt><code>(vi 'sym 'cls) -> sym</code>
<dt><code>(vi '(sym . cls)) -> sym</code>
<dt><code>(vi) -> NIL</code>
-<dd>Opens the "vi" editor on the function or method definition of
-<code>sym</code>. A call to <code><a href="refL.html#ld">ld</a></code>
+<dd>(Debug mode only) Opens the "vi" editor on the function or method definition
+of <code>sym</code>. A call to <code><a href="refL.html#ld">ld</a></code>
thereafter will <code><a href="refL.html#load">load</a></code> the modified
file. See also <code><a href="refD.html#doc">doc</a></code>, <code><a
href="refE.html#edit">edit</a></code>, <code><a
diff --git a/doc/refW.html b/doc/refW.html
@@ -87,9 +87,10 @@ NIL
</code></pre>
<dt><a name="what"><code>(what 'sym) -> lst</code></a>
-<dd>Returns a list of all internal symbols that match the pattern string
-<code>sym</code>. See also <code><a href="refM.html#match">match</a></code>,
-<code><a href="refW.html#who">who</a></code> and <code><a
+<dd>(Debug mode only) Returns a list of all internal symbols that match the
+pattern string <code>sym</code>. See also <code><a
+href="refM.html#match">match</a></code>, <code><a
+href="refW.html#who">who</a></code> and <code><a
href="refC.html#can">can</a></code>.
<pre><code>
@@ -98,8 +99,8 @@ href="refC.html#can">can</a></code>.
</code></pre>
<dt><a name="who"><code>(who 'any) -> lst</code></a>
-<dd>Returns a list of all functions or method definitions that contain the atom
-or pattern <code>any</code>. See also <code><a
+<dd>(Debug mode only) Returns a list of all functions or method definitions that
+contain the atom or pattern <code>any</code>. See also <code><a
href="refM.html#match">match</a></code>, <code><a
href="refW.html#what">what</a></code> and <code><a
href="refC.html#can">can</a></code>.
