Revision 1 of the newLISP Manual and Reference

[Lutz]

Revision 1 of the newLISP Manual and Reference is available for download here: http://newlisp.org/index.cgi?Documentation">http://newlisp.org/index.cgi?Documentation in HTML and PDF.



Thanks to Michael for a complete edit of the reference section in such a short time.



Lutz

[newdep]

the ⇒ bugger is still there in rev 1.0 for Firefox and Netscape.



Btw...Opera 9.0 does it oke under linux! (a better browser anyway)





Norman.

[Lutz]

On what version of Firefox do you see the arrow problem? It is fine on Firefox 1.06 on my WinXP machine and Firefox 1.504 and Safari 2.03 on Mac OS X.



I only saw the problem On version 6.x IE Explorer on WinXP, and hope that it is fixed in the upcoming IE 7.0. I am glad it works on Opera.



Who else cannot see the => in the program examples? They have been replaced by a graphics character HTML ⇒ ?



Lutz

[newdep]

I see the problem only under linux ! not under winXP.



here my browser info from linux ->



Opera 9.0 - works oke

Firefox 1.5.04 - works not oke

Mozilla 1.7.11 - works not oke



If you change &rArr to &rarr it works fine in firefox and mozilla.

Its a Case issue ;-)



Norman.

[cormullion]

great job guys!

[Lutz]

Making all those spelling and English mistakes was easy ;), the hard part was fixing them, and that is 100% Michael's and your work. This is the first time I feel good about the manual.



Now, who can convince O'Reilly Books to print it? Getting this done in a print shop is always a hassle and not cheap, between $25 to $80 depending on paper quality and if color or not. Color is much, much nicer.



About the arrow phenomenon: ⇒ produces => and the lowercase → produces the -> symbol.



I liked => better but at least → which is nice too, seems to display on all browsers. See the change here: http://newlisp.org/downloads/newlisp_manual.html#eval_rules">http://newlisp.org/downloads/newlisp_ma ... eval_rules">http://newlisp.org/downloads/newlisp_manual.html#eval_rules not too bad really, depending how big you see the pre -formatted font.



Lutz

[newdep]

I like the idea of having a BOOK in my hands when reading...

If you realy are thinking about this we might setup a sort of

forum/webinterface for creating a book on newlisp, taking the

manual as the base with for every function some more examples

and some background on Lisp and on the history of newLisp.

Some tips&tricks section , external library's and not to forget the

picture of the guru at the back of the cover ;-)



Norman.

[noah]

Hello, everyone.



How about developing source documentation using docbook? Docbook is designed for documenting a full book on a software program. It's commonly used as part of the Linux Documentation Project.

See http://www.tldp.org">www.tldp.org.

Also see http://www.tldp.org/LDP/LDP-Author-Guide/html/tools-writing.html">http://www.tldp.org/LDP/LDP-Author-Guid ... iting.html">http://www.tldp.org/LDP/LDP-Author-Guide/html/tools-writing.html



Lutz, would you consider adding your documentation to the tldp.org project?



Lutz, if you release docbook source for the existing manual, then the community can build a single set of documentation on top of it. Also, anyone can then print their own book, or set of books, from the source, or just download your pdf/html/postscript content.



See http://www.docbook.org">www.docbook.org for more on docbook.



-Noah

[Lutz]

Docbook is good for very technical documentation, like references. But the newLISP Users Manual and Reference is basically done and users always submit bugs and it gets edited and improved. The docbook phase for a newLISP reference basically has passed.



For all other stuff I like introductions, cookbooks or special topics, I think it is better when written by one person or a very small group of people, who know each other and work well together, each one in a well defined area.



This guarantees that the the document has a personality, which is very important for this kind of book because it makes it a pleasure reading. When a persoanl style of formatting and presentation is added, it gets even better.



Cormullion's Introduction to newLISP is a good example for both aspects, the language and the visual presentation. It would be impossible to create something like this collaborative in an anonymous group.



Currently Michael and his wife are going through the Users Manual and Reference correcting English, improving style and visual appearance (as much as a multi purpose HTML document allows it). Because this is done by one small group, the result will breathe character and personality and will make the whole thing more attractive to read and use.



What newLISP needs is some kind of Cookbook or several of them in different areas like: systems administration, networking, distributed computing, natural language processing, mathematics and statistics, GUI apps etc. and many more in many areas.



Lots of possibilities here to contribute ;), many of these specialized cookbooks don't need to be very big, but these things are laborous, bigger code examples have to be developed and tested.



Lutz

[cormullion]

I have mixed feelings about DocBook. I have tried to research it, and although working on the source looks quite easy, relative to HTML/LATEX etc, the formatting (XSL-FO) is a nightmare for anyone not really into all that Makefile/config/xml hassle (and I'm a Mac person so I'm even worse in this respect!).



(I understand that all Apple's tech documentation is now created in some form of XML - all I can say is that they probably have loads of Unix guys on call to set it all up and probably paid RenderX loads of money for the rendering software.)



DocBook was the dream that - for me - turned into a nightmare. But of course I realise that I'm at one end of the spectrum.



Lutz raises the possibility of loads of different newLISP documents written by a variety of authors, using different presentation styles. Some would regard this inconsistency as A Bad Thing, a la Emerson's Hobgoblin. It could also be refreshing to avoid the monolithic approach. That's another interesting debate!

[newdep]

Perhpas you could just email Oreilly about it? perhpas they will?, afterall

the Referance manual is finished indeed ;-)

[noah]

Hello.



Thank you, Lutz, for your thoughtful reply.



Another documentation option is to add embedded documentation built-ins to newLisp.



For example:

Code Select Expand


(doc:section
  (head "Hello World Program")
  (para "This program prints out (i "Hello, World"))
)
(print "Hello, World")


newLisp could work like Perl does with POD. POD contains mark-up (that looks like =begin and =end) for headings, paragraphs, and lists, and additional inline markup for filenames, indexes, italics, literal code, cross-references, et cetera. Perl ignores every line that starts with =. Scripts can extract and preprocess the documentation for latex and troff, or transform the documentation directly into html.



The POD systems lets authors who publish their code to CPAN rely on one documentation mark-up language to document their modules. What if newLisp starts a CNAN (Comprehensive newLisp Archive Network)?



You can publish embedded documentation specifications for newlisp modules. The specifications will allow programmers to author modules that contain newlisp documentation that fits a standard format that newLisp ignores.



Maybe newLisp could ignore documentation code unless prompted to process it using a command-line switch. doc: would be a possible namespace prefix (unless/until you make a switch to using namespace uri associations to distinguish namespaces).  Then newlisp could output either formatted content with a particular target, or just the documentation code.



For example:

Code Select Expand


$newlisp --doc hello_world.lsp

(doc:section
  (head "Hello World Program")
  (para "This program prints out (i "Hello, World"))
)

$newlisp --doc="nldoc2html.lsp" hello_world.lsp

<html>
<head>
<title>Hello World Program</title>
</head>
<body>
<h1>Hello World Program</h1>
<p>This program prints out <i>Hello, world</i></p>
</body>
</html>



Embedded documentation would help a standard set of documentation grow quickly, and allow you to build a public module distribution and documentation system efficiently. You intend newLisp users to rely on your system, so you keep the mark-up language as minimal as POD.



Perl provides http://www.cpan.org/modules/04pause.html#conventions">information about how to manage submission of perl modules. They make a special request that authors check existing namespaces before submitting additional code.



This points out a possible advantage of separating namespaces from namespace prefixes. It's easier to create a unique namespace uri than it is to create a unique object prefix, particularly a short one that makes some sense.



I certainly understand your feelings about documentation needing to have character and be published by individuals. That's what books published by companies like O'Reilly have, and that's a good thing. Cormullion's tutorial is analogous to a Learning newLisp book, while Mr. Small's book could be expanded into a newLisp Pocket Reference (because it's so terse), with addition of appropriate reference information.



I'm just hoping that through standardization, a system of documentation will develop in which the community of users can provide basic information without worrying about whether their writing has any character or personality. Something like the Perl POD system.



-Noah

[m i c h a e l]

Hi newLISPers!



Based on what Norman says here:

afterall the Referance manual is finished indeed

there may be some confusion as to how much of the manual I have completed so far. I (with Melissa's expert help) have only edited the first 72 pages, leaving 206 pages to go. We are not even a third of the way there yet! And the more technical nature of the last part may end up taking a little longer to edit. It could well be revision 20 before this thing is finished!



So, everything up to (but not including) "Functions in alphabetical order" has been edited (the parts where cormullion pointed out changes have been edited, as well).



Happy newLISPing,



m i c h a e l

[Lutz]

I also like the Javadoc way of documenting code. See an overview here: http://en.wikipedia.org/wiki/Javadoc">http://en.wikipedia.org/wiki/Javadoc . It does not nead any change to the language itself, because it works of the comment part of the function and does special formatting of the tags it ecnounters.

Code Select Expand


;; This function performs ......
;;
;; @author  John Doe
;;
;; @params str  the text string
;; @params pattern  the pattern to search
;;
;; @return  returns the result of ...
;; @see    foo, bar
;;
(define (foo str pattern)
...
)


newlispdoc then would parse out the general description and do special formatting for a HTML help page with the @ tags found. We could use the same tags from Javadoc or invent some of our own for newLISP's special needs. For example we could jave a @module tag, then newlispdoc when running over the whole newlisp-x.x.x/modules directory would produce a framed HTML document where yoy can pick the module, i.e. MySQL in the left index frame, and then see all the function descriptions for it.



Lutz

[noah]

Hi, Lutz.





I'll be reading http://java.sun.com/j2se/javadoc/writingdoccomments/index.html">How to Write Doc Comments For the Javadoc Tool.



newlispdoc looks good, too.Ship it with newlisp, and programmers will use it.



What's most exciting about this is how it will bring newlisp modules into the spotlight. Adding on a unified documentation system for them that's  relatively easy to use (and functional), will encourage newlisp programmers to write more modules!



newlisp cookbooks will grow out of that trend.



-Noah