RFC open on newLISP documentation

[Lutz]

Thanks, I will add this



Lutz

[nigelbrown]

I think some more documentation is needed on the requirement for updating init.lsp to catch the changed behaviour of (load between stable 8.6 and stable 8.7 - but I'm not sure of the best way to deliver it.



1)One option is for the the win32 installer package to include the  CHANGES file and init.lsp in a version named subdirectory (so it is available as an example but won't clobber a user's init.lsp). Currently I believe this files are only part of the source download but I think they're important enough docs to be in the installer package.



2)Alternatively, a note regarding the change and example of the required change to init.lsp could go in the user manual at (load.



3)Another option would be to have an 'Upgrading from previous version" section in the manual or readme that would address any such issues explicitly.



Possibly a combination of 1) and 3)?





How this topic came about -

I installed stable 8.7.1 on win32 over my previous stable 8.6.0 and newlisp refused to start while complaining that .init.lsp could not be found. It took me a bit of digging and downloading the source to have my attention drawn to the need for adjusting init.lsp for the new behaviour.

CHANGES does say:

8.6.5-7

   'ramdomize' looped on listlen 1



   'load' now throws an eror when the file cannot be found or returns

   the value of the last expression in the file evaluated. Before 'load'

   returned 'nil' when file was not found and else 'true'. Note that this

   required a change in init.lsp to catch error when trying to load

   $HOME/.init.lsp

...



and tne new init.lsp does have

(constant (global '$HOME) (or (env "HOME") (env "USERPROFILE") (env "DOCUMENT_ROOT")))

(if $HOME (catch (load (append $HOME "/.init.lsp")) 'error)



instead of

(constant (global '$HOME) (or (env "HOME") (env "USERPROFILE") (env "DOCUMENT_ROOT")))

(if $HOME (load (append $HOME "/.init.lsp")))



but this information is only in the source tree. The installer does, of course, have the manual which describes the (load behaviour in 8.7 but doesn't draw attention to the implications for init.lsp. By the time you're reading the 8.7 manual the 8.6 manual is overwritten so what has changed between versions is not clear.



Nigel

[Lutz]

Next time I will put a link to the http://newlisp.org/downloads/newLISP_87_Release_Notes.html">http://newlisp.org/downloads/newLISP_87 ... Notes.html">http://newlisp.org/downloads/newLISP_87_Release_Notes.html on the http://newlisp.org/index.cgi?page=Downloads">http://newlisp.org/index.cgi?page=Downloads page instead of having it only on the http://newlisp.org/index.cgi?Documentation">http://newlisp.org/index.cgi?Documentation page.



And perhaps inside that release note a more prominent 'upgrade' section at the beginning, where these kind of dangerous situations are documented more explicetly.



Lutz



ps: sorry for the hassles ;)



ps2: added a remark/link on the download page

[nigelbrown]

Hi Lutz,

No hassles really - just had to use my brain.



Perhaps the release notes could be an appendix at the end of the newlisp manual? I'd like them in some form in the installed directory for reference.



Having a current example init.lsp (maybe called init.lsp.example to stop it clobering a user's init.lsp) in the install package should be considered.



Nigel

[alex]

Function chop absent in "List processing, flow control and integer arithmetic"

in file newlisp_index.html.

[nigelbrown]

Hi Lutz,

In looking at a html2latex.lsp converter I've run newlisp_manual.html through tidy ( http://tidy.sourceforge.net/">http://tidy.sourceforge.net/ ) which can convert to xml (xhtml) which I'm planning to analyse with newlisp xml functions.



Tidy reports this apparent mark up error



line 11958 column 21 - Error: <t> is not recognized!

line 11958 column 21 - Warning: discarding unexpected <t>

line 11958 column 34 - Warning: discarding unexpected </str>



which relates to html:

<p>As an additional <t>str-option</str> <tt>"non-block"</tt> or <tt>"n"</tt> can be specified



I guess it should be "str-option" ?



Nigel

[nigelbrown]

A warning from tidy (that occurs a few times):



line 63 column 1 - Warning: missing <li>



relates to starting an unordered list within and ordered (to get the bullets under a heading) but not making the unordered list an item.

You have:

<h3>Users Manual</h3>

<ol>

<li><a href="#introduction">Introduction</a></li>

<li><a href="#deprecated">Deprecated functions and future changes</a></li>

<li><a href="#options">Command line options, startup and directories</a></li>

<ul>

<li><a href="#stack_size">Stack size</a></li>

<li><a href="#max_mem">Maximum memory usage</a></li>

<li><a href="#prompt">Suppressing the prompt</a></li>

<li><a href="#tcpip_server">newLISP as a TCP/IP server</a></li>

<li><a href="#demon">TCP/IP demon mode</a></li>

<li><a href="#demon_handler">Demon mode with handler function</a></li>

<li><a href="#direct_exec">Direct execution mode</a></li>

<li><a href="#logging">Logging I/O</a></li>

<li><a href="#cmd_help">Command line help summary</a></li>

<li><a href="#initialization">The initialization file <tt>init.lsp</tt></a></li>

<li><a href="#directories_unix">Directories on Linux, BSD, OSX</a></li>

<li><a href="#directories_win32">Directories on Win32i/newLISP-tk</a></li>

</ul>

<li><a href="#shared-lib">Shared library module for Linux/BSD</a></li>

etc.



The idea would be to move the </li> from

<li><a href="#options">Command line options, startup and directories</a></li>

to the end of the <ul></ul> block.

as suggested in

http://www.htmldog.com/guides/htmlbeginner/lists/">http://www.htmldog.com/guides/htmlbeginner/lists/



Nigel



PS rather than post 'tidy' warnings and their 'fixes' in bits I'll make my next post a summary and a diff. The html with 'fixes' should display the same (browsers can usually guess what was meant and display that) but will be easier to analyse and translate.

[Lutz]

Thanks Nigel, for the HTML corrections, fixed all the list-in-list ocurrences in the index section.



Lutz

[nigelbrown]

Hi Lutz,

Here is a diff, corrected version first (quite are few are replacing <p>...<p> with <p>...</p>, closing '<a' with a '>', adding a missed = after href - it includes the </li> stuff you've already addressed:

*** newlisp_manual.html   Fri Jan 27 13:50:17 2006

--- c:Program Filesnewlispnewlisp_manual.html   Mon Nov 07 23:52:14 2005

***************

*** 36 ****

!    <h2>Users Manual and Reference v.8.7.1</h2></center>

--- 36 ----

!    <h2>Users Manual and Reference v.8.7.1 <font size="-2"> </font></h2></center>

***************

*** 62 ****

! <li><a href="#options">Command line options, startup and directories</a>

--- 62 ----

! <li><a href="#options">Command line options, startup and directories</a></li>

***************

*** 76 ****

! </ul></li>

--- 76 ----

! </ul>

***************

*** 79 ****

! <li><a href="#expressions">Evaluating newLISP expressions</a>

--- 79 ----

! <li><a href="#expressions">Evaluating newLISP expressions</a></li>

***************

*** 83 ****

! </ul></li>

--- 83 ----

! </ul>

***************

*** 88 ****

! <li><a href="#indexing">Indexing elements of strings, lists and arrays</a>

--- 88 ----

! <li><a href="#indexing">Indexing elements of strings, lists and arrays</a></li>

***************

*** 93 ****

! </ul></li>

--- 93 ----

! </ul>

***************

*** 96 ****

! <li><a href="#return">Early return from functions, loops, blocks</a>

--- 96 ----

! <li><a href="#return">Early return from functions, loops, blocks</a></li>

***************

*** 99,100 ****

! <li><a href="#flow_and_or">Using <tt>and</tt> or <tt>or</tt></a>

! </ul></li>

--- 99,100 ----

! <li><a href="#flow_and_or">Using <tt>and</tt> or <tt>or</tt></a></li>

! </ul>

***************

*** 109,110 ****

! </ul></li>

! <li><a href="#context_objects">Programming with context objects</a>

--- 109,110 ----

! </ul>

! <li><a href="#context_objects">Programming with context objects</a></li>

***************

*** 118 ****

! </ul></li>

--- 118 ----

! </ul>

***************

*** 125 ****

! </ul></li>

--- 125 ----

! </ul>

***************

*** 135 ****

! <li><a href="#functions">Functions in groups</a>

--- 135 ----

! <li><a href="#functions">Functions in groups</a></li>

***************

*** 154 ****

! </ul></li>

--- 154 ----

! </ul>

***************

*** 436 ****

! At first newLISP is started as a server:</p>

--- 436 ----

! At first newLISP is started as a server:<p>

***************

*** 497 ****

! systems newLISP may not be able to reconnect at all times.</p>

--- 497 ----

! systems newLISP may not be able to reconnect at all times.<p>

***************

*** 595 ****

! <tr><td><tt>newlisp -l -p 4711
newlisp -l -d 4711</tt></td>

--- 595 ----

! <tr><td><tt>newlisp -l -p 4711
newlisp -l -d 4711</td>

***************

*** 597 ****

! <tr><td><tt>newlisp -L -p 4711
newlisp -L -d 4711</tt></td>

--- 597 ----

! <tr><td><tt>newlisp -L -p 4711
newlisp -L -d 4711</td>

***************

*** 681 ****

! can be converted using <a href="#get-string">get-string</a>.</p>

--- 681 ----

! can be converted using <a href="#get-string">get-string</a>.<p>

***************

*** 683 ****

! <p>The first example shows how <tt>newlisp.so</tt> is imported from newLISP itself.</p>

--- 683 ----

! <p>The first example shows how <tt>newlisp.so</tt> is imported from newLISP itself.<p>

***************

*** 898 ****

! Floating-point numbers are IEEE 754 64-bit double floats.</p>

--- 898 ----

! Floating-point numbers are IEEE 754 64-bit double floats.<p>

***************

*** 1083 ****

! lambda expressions in newLISP evaluate to themselves.</p>

--- 1083 ----

! lambda expressions in newLISP evaluate to themselves.<p>

***************

*** 1118 ****

! to parameters to work as user-defined, anonymous functions:</p>

--- 1118 ----

! to parameters to work as user-defined, anonymous functions:<p>

***************

*** 1233 ****

! see <a href="#purelisp">purelisp.lsp, the consistency of newLISP</a></p>

--- 1233 ----

! see <a href="#purelisp">purelisp.lsp, the consistency of newLISP</p>

***************

*** 1278 ****

! in turn is an array.</p>

--- 1278 ----

! in turn is an array.<p>

***************

*** 1511 ****

! version of newLISP.</p>

--- 1511 ----

! version of newLISP.</a>

***************

*** 1785 ****

! <a NAME="flow_catch_throw"></a>

--- 1785 ----

! <a NAME="flow_catch_throw"><a>

***************

*** 2090 ****

! symbols in MAIN visible to other contexts use the function <a href="#global">global</a>:</p>

--- 2090 ----

! symbols in MAIN visible to other contexts use the function <a href="#global">global</a>:<p>

***************

*** 2139 ****

! context by explicitly prefixing them with the context symbol:</p>

--- 2139 ----

! context by explicitly prefixing them with the context symbol:<p>

***************

*** 2151 ****

! <p>In this example the built-in function <a href="#new">new</a> is overwritten

--- 2151 ----

! In this example the built-in function <a href="#new">new</a> is overwritten

***************

*** 2258 ****

! <a name="context_rules"></a>

--- 2258 ----

! <a name="context_rules"</a>

***************

*** 2266 ****

! translation symbols are created.</p></li>

--- 2266 ----

! translation symbols are created.</p>

***************

*** 2275 ****

! for forever.</p></li>

--- 2275 ----

! for forever.</p>

***************

*** 2281 ****

! context.</p></li>

--- 2281 ----

! context.</p>

***************

*** 2382 ****

! using the function <a href="#new">new</a>. Note that OO programming purists would

--- 2382 ----

! using the function <a href"#new">new</a>. Note that OO programming purists would

***************

*** 2778 ****

! <tr><td><tt>system.listMethods</tt></td><td>Returns a list of all method names</td></tr>

--- 2778 ----

! <tr><td><tt>system.listMethods<tt></td><td>Returns a list of all method names</td></tr>

***************

*** 2978 ****

! a shape similar to a Latin small <tt>w</tt>.</p>

--- 2978 ----

! a shape similar to a Latin small <tt>w</tt>.<p>

***************

*** 3891 ****

! <a href="#find">find</a> and <a href="#regex">regex</a></td>

--- 3891 ----

! <a href="#find">find</a> and <a href"#regex">regex</a></td>

***************

*** 4847 ****

! <td><a href="#semaphore">semaphore</a></td>

--- 4847 ----

! <td><a href="#semaphore">semaphore<a></td>

***************

*** 6030 ****

! <P>Arrays are modified and accessed using the usual functions for lists:</p>

--- 6030 ----

! <P>Arrays are modified and accessed using the usual functions for lists:<p>

***************

*** 6394 ****

! from each other:</p>

--- 6394 ----

! from each other:<p>

***************

*** 6764 ****

! symbols, which have been protected in their home context.</p>

--- 6764 ----

! symbols, which have been protected in their home context.<p>

***************

*** 7173 ****

! <center><table>

--- 7173 ----

! <center>

***************

*** 7818 ****

! <p>While <tt>do-until</tt> goes through the loop at least once, <a href="#until">until</a>

--- 7818 ----

! <p>While <tt>do-until</tt> goes through the loop at least once, <a href"#until">until</a>

***************

*** 7850 ****

! <p>While <tt>do-until</tt> goes through the loop at least once, <a href="#until">until</a>

--- 7850 ----

! <p>While <tt>do-until</tt> goes through the loop at least once, <a href"#until">until</a>

***************

*** 8943 ****

!

<font size=+2>"%w.pf"</font>

--- 8943 ----

! <font size=+2>

"%w.pf"

</font>

***************

*** 8950 ****

!

<font size=+2>w</font>

--- 8950 ----

! <font size=+2>

w

</font>

***************

*** 8958 ****

!

<font size=+2>p</font>

--- 8958 ----

! <font size=+2>

p

</font>

***************

*** 8968 ****

!

<font size=+2>f</font>

--- 8968 ----

! <font size=+2>

f

</font>

***************

*** 9910 ****

! <p>See also <a HREF="#first">first</a>, <a HREF="#rest">rest</a> and <a href="#nth">nth</a>.</p>

--- 9910 ----

! <p>See also <a HREF="#first">first</a>, <a HREF="#rest">rest</a> and <a href"#nth">nth</a>.</p>

***************

*** 9948 ****

! an array or the number of characters in a string.</p>

--- 9948 ----

! an array or the number of characters in a string.<p>

***************

*** 10338 ****

! in newLISP evaluate to themselves.</p>

--- 10338 ----

! in newLISP evaluate to themselves.<p>

***************

*** 10994 ****

! fashion. To send data back to the address and port received with <a href="#net-receive-from">

--- 10994 ----

! fashion. To send data back to the address and port received with <a href-"#net-receive-from">

***************

*** 11032 ****

! and receive.</p>

--- 11032 ----

! and receive.<p>

***************

*** 11476 ****

! <p>For blocking short UDP transactions see <a href="#net-send-udp">net-send-udp</a>

--- 11476 ----

! <p>For blocking short UDP transactions see <a href="#net-send-udp>net-send-udp"</a>

***************

*** 11958 ****

! <p>As an additional str-option <tt>"non-block"</tt> or <tt>"n"</tt> can be specified

--- 11958 ----

! <p>As an additional <t>str-option</str> <tt>"non-block"</tt> or <tt>"n"</tt> can be specified

***************

*** 12086 ****

! <tt>ld</tt> the same way internally.</p>

--- 12086 ----

! <tt>ld</tt> the same way internally.<p>

***************

*** 12755 ****

! where directory access rights are configured.</p>

--- 12755 ----

! where directory access rights are configured.<p>

***************

*** 13128 ****

! and is swallowed if it is last character in the stream.</p>

--- 13128 ----

! and is swallowed if it is last character in the stream.<p>

***************

*** 13133 ****

! specified in int-file obtained from a previous <a HREF="#open">open</a> statement.</p>

--- 13133 ----

! specified in int-file obtained from a previous <a HREF="#open">open</a> statement.<p>

***************

*** 13256 ****

! not to be doubled in a regular expression pattern which itself is delimited by quotes.</p>

--- 13256 ----

! not to be doubled in a regular expression pattern which itself is delimited by quotes.<p>

***************

*** 13670 ****

! with the normal syntax rules for symbols, are serialized using a <a href="#symbol">sym</a>

--- 13670 ----

! with the normal syntax rules for symbols, are serialized using a <a href"#symbol">sym</a>

***************

*** 13692 ****

! stored in the system variables <tt>$0</tt> to <tt>$15</tt>.</p>

--- 13692 ----

! stored in the system variables <tt>$0</tt> to <tt>$15</tt>.</tt></p>

***************

*** 14099 ****

! See the file LOCALIZATION in the newLISP source distribution for details.</p>

--- 14099 ----

! See the file LOCALIZATION in the newLISP source distribution for details.<p>

***************

*** 14235 ****

!

--- 14235 ----

!

***************

*** 14281 ****

! The memory address or handle can be assigned to a variable for later reference.</p>

--- 14281 ----

! The memory address or handle can be assigned to a variable for later reference.<p>

***************

*** 15195 ****

! <a NAME="time-of-day"></a>

--- 15195 ----

! <a NAME="time-of-day"</a>

***************

*** 16311 ****

! <a NAME=tcpip_error_codes></a>

--- 16311 ----

! <a NAME=tcpip_error_codes</a>

***************

*** 17585 ****

!

--- 17585 ----

! <p></p>

***************

*** 17821 ****

! <center><p>PREAMBLE</p></center>

--- 17821 ----

! <p><center>PREAMBLE</center></p>

***************

*** 18058 ****

! of promoting the sharing and reuse of software generally.</p>

--- 18058 ----

! of promoting the sharing and reuse of software generally.

***************

*** 18065 ****

!    <p>NO WARRANTY</p></center>

--- 18065 ----

! <p>NO WARRANTY</center></p>





I'll put the updated file on my site tonight and post the link.



There are still some issues - mainly that a name= shouldn't have a '?' in it

see http://www.w3.org/TR/html401/types.html#type-name">http://www.w3.org/TR/html401/types.html#type-name

 but the targets 'array?' etc do (maybe change the name= to arrayp etc.



The remaining warnings from 'tidy' are:



line 25 column 1 - Warning: <body> proprietary attribute "leftmargin"

line 329 column 1 - Warning: <table> lacks "summary" attribute

line 592 column 1 - Warning: <table> lacks "summary" attribute

line 933 column 1 - Warning: <table> lacks "summary" attribute

line 1250 column 1 - Warning: <table> lacks "summary" attribute

line 1591 column 1 - Warning: <table> lacks "summary" attribute

line 2777 column 1 - Warning: <table> lacks "summary" attribute

line 2989 column 1 - Warning: <table> lacks "summary" attribute

line 3530 column 1 - Warning: <table> lacks "summary" attribute

line 3661 column 1 - Warning: <table> lacks "summary" attribute

line 4042 column 1 - Warning: <table> lacks "summary" attribute

line 4075 column 1 - Warning: <table> lacks "summary" attribute

line 4300 column 1 - Warning: <table> lacks "summary" attribute

line 4323 column 1 - Warning: <table> lacks "summary" attribute

line 4325 column 1 - Warning: <td> proprietary attribute "witdh"

line 4356 column 1 - Warning: <table> lacks "summary" attribute

line 4394 column 1 - Warning: <table> lacks "summary" attribute

line 4433 column 1 - Warning: <table> lacks "summary" attribute

line 4467 column 1 - Warning: <table> lacks "summary" attribute

line 4697 column 1 - Warning: <table> lacks "summary" attribute

line 4820 column 1 - Warning: <table> lacks "summary" attribute

line 4868 column 1 - Warning: <table> lacks "summary" attribute

line 4916 column 1 - Warning: <table> lacks "summary" attribute

line 5160 column 1 - Warning: <table> lacks "summary" attribute

line 5208 column 1 - Warning: <table> lacks "summary" attribute

line 5310 column 1 - Warning: <table> lacks "summary" attribute

line 5374 column 1 - Warning: <table> lacks "summary" attribute

line 6141 column 1 - Warning: <a> attribute "name" has invalid value "array?"

line 6238 column 1 - Warning: <a> attribute "name" has invalid value "atom?"

line 6912 column 1 - Warning: <a> attribute "name" has invalid value "context?"

line 7173 column 9 - Warning: <table> lacks "summary" attribute

line 7666 column 1 - Warning: <a> attribute "name" has invalid value "directory?"

line 7923 column 1 - Warning: <a> attribute "name" has invalid value "empty?"

line 8493 column 1 - Warning: <a> attribute "name" has invalid value "file?"

line 8737 column 1 - Warning: <a> attribute "name" has invalid value "float?"

line 9703 column 1 - Warning: <a> attribute "name" has invalid value "integer?"

line 9865 column 1 - Warning: <a> attribute "name" has invalid value "lambda?"

line 9914 column 1 - Warning: <a> attribute "name" has invalid value "legal?"

line 10087 column 1 - Warning: <a> attribute "name" has invalid value "list?"

line 10207 column 1 - Warning: <a> attribute "name" has invalid value "macro?"

line 10569 column 1 - Warning: <a> attribute "name" has invalid value "NaN?"

line 11626 column 1 - Warning: <a> attribute "name" has invalid value "nil?"

line 12020 column 1 - Warning: <table> lacks "summary" attribute

line 12463 column 1 - Warning: <a> attribute "name" has invalid value "primitive?"

line 12493 column 1 - Warning: <table> lacks "summary" attribute

line 12885 column 1 - Warning: <a> attribute "name" has invalid value "quote?"

line 14801 column 1 - Warning: <a> attribute "name" has invalid value "string?"

line 14957 column 1 - Warning: <a> attribute "name" has invalid value "symbol?"

line 15460 column 1 - Warning: <a> attribute "name" has invalid value "true?"

line 15564 column 1 - Warning: <table> lacks "summary" attribute

line 16054 column 1 - Warning: <table> lacks "summary" attribute

line 17389 column 1 - Warning: <table> lacks "summary" attribute

line 17804 column 1 - Warning: <table> lacks "summary" attribute

Info: Doctype given is "-//W3C//DTD HTML 4.0 Transitional//EN"

Info: Document content looks like HTML Proprietary

53 warnings, 0 errors were found!



The table summary attribute should be used to describe

the table structure. It is very helpful for people using

non-visual browsers. The scope and headers attributes for

table cells are useful for specifying which headers apply

to each table cell, enabling non-visual browsers to provide

a meaningful context for each cell.



For further advice on how to make your pages accessible

see http://www.w3.org/WAI/GL">http://www.w3.org/WAI/GL. You may also want to try

"http://www.cast.org/bobby/">http://www.cast.org/bobby/" which is a free Web-based

service for checking URLs for accessibility.



You are recommended to use CSS to specify the font and

properties such as its size and color. This will reduce

the size of HTML files and make them easier to maintain

compared with using <FONT> elements.



To learn more about HTML Tidy see http://tidy.sourceforge.net">http://tidy.sourceforge.net

Please send bug reports to html-tidy@w3.org

HTML and CSS specifications are available from http://www.w3.org/">http://www.w3.org/

Lobby your company to join W3C, see http://www.w3.org/Consortium">http://www.w3.org/Consortium



Nigel

>

[nigelbrown]

Posted

Manual with edits as per diff above:

http://users.cyberone.com.au/nbrown/newlisp/corrected/newlisp_manual.html">http://users.cyberone.com.au/nbrown/new ... anual.html">http://users.cyberone.com.au/nbrown/newlisp/corrected/newlisp_manual.html

xml (xhtml) version created by 'tidy -n -ascii -asxhtml':

http://users.cyberone.com.au/nbrown/newlisp/corrected/newlisp_manual.xml">http://users.cyberone.com.au/nbrown/new ... manual.xml">http://users.cyberone.com.au/nbrown/newlisp/corrected/newlisp_manual.xml

The diff as in prev post:

http://users.cyberone.com.au/nbrown/newlisp/corrected/diff.txt">http://users.cyberone.com.au/nbrown/new ... d/diff.txt">http://users.cyberone.com.au/nbrown/newlisp/corrected/diff.txt

tidy errors as in prev post:

http://users.cyberone.com.au/nbrown/newlisp/corrected/xmlerrors.txt">http://users.cyberone.com.au/nbrown/new ... errors.txt">http://users.cyberone.com.au/nbrown/newlisp/corrected/xmlerrors.txt



Nigel

[Lutz]

Thanks Nigel, I will do the HTML corrections and post a v.8.7.10 with the corrected newlisp_manual.html over the weekend.



The only issue is the predicates ending with a question mark. Help functions rely on things like http://newlisp_manual.html#list? , i.e. the text is highlighted with the mouse, than right-mous-button/menu/help etc..



Perhaps you can just run a script over this before doing the Tex conversion?



Lutz

[Lutz]

Here is the 8.7.10 manual incorporating all your corrections except predicate question marks:



http://newlisp.org/downloads/development/Nigel/newlisp_manual.html">http://newlisp.org/downloads/developmen ... anual.html">http://newlisp.org/downloads/development/Nigel/newlisp_manual.html



Lutz

[nigelbrown]

Thanks Lutz for the edited version.



Regarding list? etc the '?' will keep the manual nonstandard html/xml accepted only by the grace/whim of the browsing application. While it could be massaged on the way to latex I feel finding a correct representation in the html is a solution for the longer term usefulness of the manual.



Perhaps when calling the manual the calling program should perhaps convert any unacceptable characters by substitution according to a translation table eg

? -> _questionmark_   (underscores are valid)

so reference would be  name=#list_questionmark_



Nigel

[nigelbrown]

Hi Lutz,

I'm looking into the help linking and noted:



1. doc location setting

Using newlisp 8.7.9 compiled on Suse 10 86_64 I tried the "text is highlighted with the mouse, than right-mous-button/menu/help" and found the context-sensitive help tried to link to /usr/share/newlisp/newlisp_manual.html while the manual is at /usr/share/newlisp/doc/newlisp_manual.html.



Looking at the newlisp-tk.tcl code the default location settings are:

set Ide(HelpFile)           "/usr/share/newlisp/newlisp_manual.html"

set Ide(HelpTopic)          "/usr/share/newlisp/doc/manual_frame.html"

set Ide(HelpTopic-tk)       "/usr/share/newlisp/doc/newlisp-tk.html"



looks like HelpFile location needs the /doc/ added



2. This looks like code for context-sens help in newlisp-tk.tcl:



proc CommandHelp { widget } {



   global selectionBuff Ide



   catch [set selectionBuff [selection get -displayof $widget ]]

   exec $Ide(HelpProgram) $Ide(HelpFile)#$selectionBuff

        }



to implement replacing ? with _questionmark_ I used :



proc CommandHelp { widget } {



        global selectionBuff Ide



        catch [set selectionBuff [selection get -displayof $widget ]]

        regsub -all {?} $selectionBuff {_questionmark_} safeselectionBuff



        exec $Ide(HelpProgram) "file://$ide(helpfile)#$safeselectionBuff" &

        }



Notes:

1. I added & to exec line to make it non-blocking

2. Added file:// as without the file:// mozilla (1.7.11) couldn't find the link

3. changed href within newlisp_manual.html to, for example,:

<a NAME="array_questionmark_"></a>

4. changed manual location:

set Ide(HelpFile)           "/usr/share/newlisp/doc/newlisp_manual.html"



So all hrefs could be made to meet the standard.

It works!



Nigel

[Lutz]

Thanks for fixing the Tcl file Nigel,



I suggest 'p' instead of '_questionmark_'. This is shorter to type for people, who do "newlisp_manual.html#list?" in a brower manually, now they do "newlisp_manual.html#listp".



The 'p' stands for predicate and is a suffix used instead of '?' in some other LISPs. In fact  older newLISP HTML manuals used the p.



I will post an updated version of newlisp_manual.html 8.7.10 later.



Lutz