Manual and release notes for upcoming 10.2.0

[Lutz]

Here is the latest version in OpenOffice ODT format:



http://www.newlisp.org/newlisp_manual-10201.odt">http://www.newlisp.org/newlisp_manual-10201.odt



The PDF and HTML versions have been updated too.



Ps: I would keep different formats in different files.

[cormullion]

Sorry to have missed out on the editing this time round! Thanks to everyone for making theh newLISP manual (even) better!



In some spare moments I've been thinking about ebooks and electronic docs. I've been using the newlisp manual as a real-world example. One thing I tried was this:

Code Select Expand

(set 'f (read-file {/usr/share/doc/newlisp/newlisp_manual.html}))
(xml-type-tags nil nil nil)
(set 'xf (xml-parse f 15))

Yes, it doesn't work. But that's just because the manual is in HTML Transitional.  I ran the HTML source through BBEdit's version of Tidy - converting it to XHTML. It appears to make little difference to the 'user experience' in a  browser - a lot of changes to BR tags and so on, but not much else.



But now that code above works, and produces SXML of the source:

Code Select Expand

(html ((xmlns "http://www.w3.org/1999/xhtml")) (head (meta ((http-equiv "content-type")
     (content "text/html; charset=utf-8")))
   (meta ((name "author") (content "Lutz Mueller")))
   (meta ((name "keywords") (content "newLISP Lisp SCHEME programming language manual reference Artificial Intelligence AI NUEVATEC")))
   (meta ((name "description") (content "newLISP Users Manual and Reference")))
...
(a ((name "shell") (id "shell")))
   (h2 (span ((class "function")) "!"))
   (h4 "syntax: (! " (em "str-shell-command") ")")
   (p "Executes the command in " (em "str-command") " by shelling out to the operating system and executing. This function returns a different value depending on the host operating system.")
   (pre "n(! "vi")  n(! "ls -ltr")n")
...


Yes it looks crazy (but better than HTML), but I can't help thinking that this format might be useful, because you can easily use newLISP on it. For example:

Code Select Expand

(set 'xr (ref-all 'h4 xf))
(dolist (r xr)  (println (rest (xf (chop r)))))


gives a list of all syntax definitions, suitable for producing a quick reference guide...



A few questions arise: what are the problems with distributing the manual in XHTML rather than HTML, such that a trip through Tidy wouldn't be necessary? Also, how could you go about outputting the SXML structure to other formats, such as plain old HTML? It kind of looks to me like it could be executable, somehow, if there were definitions for the major tags... And another possibility - could this format be the basis for some kind of newLISP-oriented text editor?



Just a few thoughts... :)

[tomtoo]

peanut gallery here.  all of that sounds very cool and useful to me. :-)

[Lutz]

This is a great idea. If you can send me an XHTML translation of the current rev-2 manual from:



http://www.newlisp.org/downloads/newlisp_manual.html">http://www.newlisp.org/downloads/newlisp_manual.html



and I can try if it works with my PDF conversion.

[Lutz]

In the end I succeded to do the XHTML conversion myself, and its online now:



http://www.newlisp.org/downloads/newlisp_manual.html">http://www.newlisp.org/downloads/newlisp_manual.html



it can be parsed using:

Code Select Expand

(xml-type-tags nil nil nil nil)
(xml-parse (read-file "newlisp_manual.html") 15)


and you can do this:

Code Select Expand

> (ref-all '(h1 *) (xml-parse (read-file "./newlisp_manual.html") 15) match true)
((h1 "Contents") (h1 "newLISP Users Manual") (h1 "newLISP Function Reference"))
>


The 'true' flag at the end of 'ref/ref-all' was introduced in 10.1.7 to return the content instead of the index-vector.

[cormullion]

Cool - I was going to do it when I got back today but you beat me to it.  I think Tidy is freely available, even though BBEdit costs money...



I can see how you'd scan the SXML for analysis:

Code Select Expand

(define Tags:Tags)

(define (count-tags expr)
 (cond
   ((list? (first expr))
      (count-tags (first expr))
      (dolist (s (rest expr)) (count-tags s)))
   ((symbol? (first expr))
      (dolist (s (rest expr))
            (count-tags s))
      (set 'key (string (first expr)))    
      (if (Tags key)
          (Tags key (inc (Tags key)))
          (Tags key 1))
      )
   )
)

(count-tags xf)

(println (Tags))
  (
    ("a" 2298)
    ("align" 47)
    ("alink" 1)
    ("b" 150)
    ("bgcolor" 1)
    ("blockquote" 21)
    ("body"  1)  
    ("border" 20)  
    ("br" 1079)  
    ("cellpadding" 20)  
    ("center" 42)  
    ("class" 2031)  
    ("color" 29)  
...




But presumably it's possible to actually execute the SXML list directly, provided that there are suitable functions already define for each symbol/tag...? How would I do that?

[cormullion]

I tried to work out how to make such an SXML list can be an expression that can be directly evaluated.  The problem is with the double-parenthesized expressions. For example, this is OK:

Code Select Expand

(p "Built-in and user-defined functions are suitable for " (u "both") " types of arguments, but when passing context names, data will be passed by reference.")
   (p "Quoted symbols can also be used to pass data by reference, but this method has disadvantages:")

because user-defined functions can be defined that output some representation of paragraph and underlined text. But I can't make these work:

Code Select Expand

(a ((href "#load")) "load")

because of the double parentheses?

[Lutz]

You need to add the SXML attribute tag '@' via option 16

Code Select Expand

(xml-type-tags  nil nil nil nil)
(xml-parse "<a href='#thelink'>a Link</a>" 31)

=> ((a (@ (href "#thelink")) "a Link"))


Now the '@' could be defined as processing the s-expressions follwing it. Basically it would work like a 'begin'.

[cormullion]

Yes - that works, thanks! Although now I've got even further into the jungle:



First I had to redefine the built-in symbols that also appear in the SXML, but then:

Code Select Expand

(set-ref-all 'div xf '_div)
(set-ref-all 'name xf '_name)
(set-ref-all '@ xf '_@)

(define (_@) (begin (args)))

(map
    (fn (f)
      (letex
        ((fn-name (sym (string f))))
        (define (fn-name a)
           (string a))))
    (map first (Tags)))

(println (apply eval xf))


it gives a stack overflow error... Nested too much? I didn't think so. I think I'm close to a solution but ...

[kosh]

In newlisp_manual.html, some lines that have a unbalanced double quotes(") are found.



Please see diff file below:

Code Select Expand

--- newlisp_manual-10.2.1-rev2.orig.html Tue Mar 30 02:59:58 2010
+++ newlisp_manual-10.2.1-rev2.html Tue Mar 30 03:12:13 2010
@@ -2099,7 +2099,7 @@
 
 ; strings
 
-(set 's "NewLISP)
+(set 's "NewLISP")
 
 (setf (s 0) "n") <span class='arw'>&rarr;</span> "n"
 
@@ -2590,7 +2590,7 @@
 </pre>
 
 <p>The <a href="#symbols">symbols</a> function is used to show all symbols
-belonging to a context"</p>
+belonging to a "context"</p>
 
 <pre>
 (symbols FOO) <span class='arw'>&rarr;</span> (FOO:func FOO:var FOO:x FOO:y FOO:z)
@@ -2896,7 +2896,7 @@
 ;; Variables used throughout this namespace
 
 (define db:handle)
-(define db:host "http://localhost)
+(define db:host "http://localhost")
 
 ;; Constants


[Lutz]

Thanks to Kosh and Sammo (in a different thread) for the latest manual corrections, online since yesterday:



http://www.newlisp.org/downloads/newlisp_manual.html">http://www.newlisp.org/downloads/newlisp_manual.html

[cormullion]

What could be the cause of this error?

Code Select Expand

ERR: call or result stack overflow : args<3670>
called from user defined function br
called from user defined function h4
called from user defined function body
called from user defined function html

Is it that the list is too deeply nested, or that the list is too long?



sys-info reports this at the beginning:



(78309 268435456 501 8 0 2048 0 56523 10110 131)



and this just before the  overflow:



(86380 268435456 501 8 0 2048 0 56523 10110 131)



but I can't see where a 'call stack' would be exceeded...?



Setting a value with the -s switch doesn't appear to change these figures:

[Lutz]

Currently on a trip with internet on a phone only. Will look into it on Friday.

[Lutz]

I assume you have the body tag defined as a 'begin' operation. The 'begin' function is limited to 4096 expressions, but you could use either 'lambda/fn' or 'dolist' to evaluate longer lists of expressions:

Code Select Expand

(apply (append (fn ()) long-list-of-expressions))

; or

(dolist (ex long-list-of-expressions)
    (eval x))


[cormullion]

Hi Lutz - thanks for the idea. But I think the problem may be elsewhere. Sorry about my code, it's not the best, but I'm just hacking to see if this is a valid path for a project.... Can't see where I've gone wrong. (And sorry about the wrong thread, too...:)



This code expects the manual to be in XHTML format...

Code Select Expand

(set 'f (read-file {/usr/share/doc/newlisp/newlisp_manual.html}))
(xml-type-tags nil nil nil)
(set 'xf (xml-parse f 31))

(set-ref-all 'div xf '_div)
(set-ref-all 'name xf '_name)
(set-ref-all '@ xf '_@)

(define (_@)
    (dolist (ex (args))
        (eval ex)))

(dolist (tag '(html a align alink b bgcolor blockquote
body border br cellpadding center class color
content em font h1 h2 h3 h4 head hr href
http-equiv i id li link media meta ol p
pre size span style summary table td text
th title tr tt type u ul valign vlink
width xmlns _div _name))
    (letex
       ((f-name (sym (string tag))))
       (define (f-name) (string  "{"  (join (args) "n")  "}"))))

(println (eval xf))

ERR: call or result stack overflow : dolist<E5E3>
called from user defined function _@
called from user defined function span
called from user defined function pre
called from user defined function body
called from user defined function html