newLISP built-in documentation ?

[anta40]

Does newLISP has a built-in documentation ?



I mean, a documentation built within the interpreter.

So when you are running newLISP, you can do something like this :

Code Select Expand


> help reverse
"In the first form, reverse reverses and returns the list. Note that reverse is destructive and changes the original list."

> help unique
"Returns a unique version of list with all duplicates removed."


Yes I know, there's a good documentation http://www.newlisp.org/downloads/manual_frame.html">there, but it's pretty convenient not to open too much window :)

[HPW]

No.



But one of the major benefits of newLISP is the small footprint and fast loading.

So why bloat the executable with the doc.

As you noticed the external doc is very good and much better than a small one line help.

Also some editors allow to select a keyword and jump directly into the help page. (newLISP-TK, Ultraedit etc.)

The help doc does provide jump targets for it.

[newdep]

Hi anta40,



No its not default, but very easy to build in..



Here is a nice example on how to embed it in newlisp.

http://newlisp-on-noodles.org/wiki/index.php/NewLISP_Ideas">//http://newlisp-on-noodles.org/wiki/index.php/NewLISP_Ideas



seek for the Par. [Included Help]



Enjoy ;-)



Norman.

[Jeff]

If you document your functions with built in doc strings:

Code Select Expand

(define (say-hello x)
  "says hello to x"
  (println "hello, " x))

...you can access the doc string with (nth say-hello 1).

[lithper]

Yes, there are 2 ways to use help from inside the interpreter that I use.



[1] One is offered by Lutz M., the creator of the language, in his default init.lsp file:

Code Select Expand

(define-macro (help func)
   (if (primitive? (eval func))
       (let (func-name (name func))
            (if (ends-with func-name "?") (replace "?" func-name "p"))
       (!  (format "w3m file:/usr/share/newlisp/doc/newlisp_manual.html#%s" func-name)))
        ;(format "%s is not a built-in function" (name func))
        (!  "w3m file:/usr/share/newlisp/doc/newlisp_manual.html#functions"))
   )

(I edited the macro to use "w3m", the best command-line www browser, but you may also put there any other like "links", "lynx" etc.



This help simply reads the manual file and shows it at the requested function.



[2] There is also a file with short, skeleton help lines in the form of

("slice" "syntax: (slice str int-index [int-length])")

written by one of the more popular forum participants - I picked it up from his web site with newlisp scripts and add-ons. Will try to find out which site it was and add the URL here

In a similar way, this quick short help must be loaded, possibly from "init.lsp" (and its name may be changed to something like "hh" not to conflict with the full detailed help based on the manual)



[3] Generally speaking, computer documentation is very irritating. It's written, as a rule with surprisingly few exceptions, by abominably stupid people.

The main problem is that documentation demands that you always did internat translations into and from a new, intermediary language, before you can understand and use the info.



This is the same problem that humanity has with old-fashioned dictionaries in the tradition of 19th century:

BREAK

1 a: to separate into parts with suddenness or violence b: fracture break an arm  

(this will be the only example in the subentry)

When computers became available for linguistic research in the 1980s, Collins publishers and Birmingham University made a pioneering study and published a first dictionary in which entries used a radically different principle in explanations:

BREAK

1. When an object breaks or when you break it, it suddenly separates into 2 or more pieces......(etc.)

He fell through the window breaking the glass...the plate broke...(etc)

The definition EMBEDS PATTERNS OF USAGE (not speaking of the examples which in this COUBILD project all come from the real usage as collected and revealed by their computers)



The "traditional" (i.e. stupid) formal way of description presupposes someone who ALREADY KNOWS how to use the word, and needs only a small passive reminder. The second, intelligent explanation, provides immediate info, disposes of the need to restore or reformulate or regroup the information in your head - or, even worse, a need to go and look sth else somewhere else - before you can actually use it.

insane ways of documenting language functions



[1] /some PHP doc/

object imap_bodystruct(int stream_id, int msg_no [,  int options]);



[2] /GNU Prolog/

open/4, open/3

Templates:

    open(+source_sink, +io_mode, -stream, +stream_option_list)

    open(+source_sink, +io_mode, -stream)

Description

open(SourceSink, Mode, Stream, Options) opens the source/sink SourceSink for input or output as indicated by Mode and the list of stream-options

Options and unifies Stream with the stream-term which is associated with this stream. See absolute_file_name/2 for information about the syntax of

SourceSink (section 7.26.1).



..and not a single example in sight! - one has to grep for the function among the testsuite files or in the examples directory, if it exists

This insanity murders first-class ideas and languages, such as Common Lisp, as one example, or Prolog.

Instead of:

("write-buffer" "syntax: (write-buffer str-device str-buffer [int-size])")



...Problems on the first reading are: am I writing a given buffer or into a buffer? What is the meaning of the operator? So str-buffer is my output, or do I get the stuff from it? I can figure out that str-device may be sth like stdin - or is it stdout, the output device??

In other words, before using such help one needs either to go and read in full the detailed explanation in the manual, or to KNOW all this stuff already!! ..and then it still requires reformulation of the stuff internally before one can use it.



Because NATURALLY in my head I keep a different formula - computer operators are naturally remembered AS VERBS OF A HUMAN LANGUAGE:

..write this

 ("write-buffer" "syntax: (write-buffer into_which_str_or_device which_str_or_buffer [int-size])")



Internally I always think of it as "write-buffer into.. from.."

The definition MUST be like a sentence in a human language. This is the way our brains work, so use it instead of fighting it

I re-wrote half of the short definitions in my copy of the short help file to insert meaningful usage patterns, so that no reformulation or need to check another doc would ever happen, even if you do not know the operator or have not used it before.



Fake formality in definitions was invented by idiots, and unfortunately, in spite of the newer ways, popularized by the Internet wave and open programming (all those cookbooks, great snippets in each case etc.), the same old fake formality still rules making even great languages and ideas fail or require inordiate amounts of time before a newcomer is actually able to begin to use them

[cormullion]

If you document your functions with built in doc strings:

Code Select Expand

(define (say-hello x)
  "says hello to x"
  (println "hello, " x))

...you can access the doc string with (nth say-hello 1).

- I wondered why you did comments like that, instead of semicolons. Now I know.

[Jeff]

That is the standard way of doing documentation in lisp.

[Tim Johnson]

Does newLISP has a built-in documentation ?



I mean, a documentation built within the interpreter.

So when you are running newLISP, you can do something like this :

Code Select Expand


> help reverse
"In the first form, reverse reverses and returns the list. Note that reverse is destructive and changes the original list."

> help unique
"Returns a unique version of list with all duplicates removed."


Yes I know, there's a good documentation http://www.newlisp.org/downloads/manual_frame.html">there, but it's pretty convenient not to open too much window :)

This sounds like rebol. (I'm a rebol and python programmer) Although I make extensive use of rebol and python docstrings, I like the flexibility

offered by newlisp via the examples here.

Tim

[lithper]

Get the short in-line help.lsp from here:



http://www.newlisp-on-noodles.org/wiki/index.php/NewLISP_Ideas#Included_Help">http://www.newlisp-on-noodles.org/wiki/ ... luded_Help">http://www.newlisp-on-noodles.org/wiki/index.php/NewLISP_Ideas#Included_Help



I (as I explained earlier)

(1) re-wrote some, not yet all, of the brief definitions to BE LIKE VERB PHRASES of a HUMAN LANGUAGE, and



(2) added help on the categories



So now the provided function looks like this:

Code Select Expand


(define (hh (target 'help) , command_lst syntax)

(set 'command_lst '(
  ("help" "syntax: (hh command) or (hh top)")
  ("zero?" "syntax: (zero? expr) -- check if expr evaluates to 0")
  ("xml-type-tags" "syntax: (xml-type-tags [expr-text-tag expr-cdata-tag expr-comment-tag expr-element-tags]) --> suppress or replace tags in output o
f following xml-parse")
  ("xml-parse" "syntax: (xml-parse which_string-xml [int-options into_target_sym-ontext [with_func-callback]]) --> ret. parsed Ss-expr list")
  ("xml-error" "syntax: (xml-error) --> list of err from last xml-parse")

..............
..............
..............

  ("lists" "syntax: (+, -, *, /,%, <, >, =, <=, >=, !=, :, and, append, apply, args, assoc, assoc-set, begin, bind, case, catch, chop, clean, cond, co
ns, constant, count, curry, define, define-macro, def-new, difference, doargs, dolist, dostring, dotimes, dotree, do-until, do-while, dup, ends-with,
exists, eval, expand, first, filter, find, find-all, flat, fn, for, for-all, if, index, intersect, lambda, lambda-macro, last, length, let, letex, let
n, list, local, lookup, map, match, member, not, nth, nth-set, or, pop, pop-assoc, push, quote, ref, ref-all, ref-set, rest, replace, replace-assoc, r
everse, rotate, select, set, setq, set-assoc, set-nth, set-ref, set-ref-all, silent, slice, sort, starts-with, swap, unify, unique, unless, until, whe
n, while)" )
  ("strings" "syntax: (.. address, append, char, chop, dup, ends-with, encrypt, eval-string, explode, find, first, float, format, get-char, get-float,
 get-int, get-long, get-string, int, join, last, lower-case, member, name, nth, nth-set, pack, parse, pop, push, regex, replace, rest, reverse, rotate
, select, set-nth, slice, source, starts-with, string, sym, title-case, trim, unicode, unpack, upper-case, utf8, utf8len..)")
  ("math" "syntax: (.. abs, acos, acosh, add, asin, asinh, atan, atanh, atan2, beta, betai, binomial, ceil, cos, cosh, crc32, crit-chi2, crit-z, dec,
div, erf, exp, factor, fft, floor, flt, gammai, atan, gcd, ifft, inc, log, min, max, mod, mul, pow, round, sequence, series, sgn, sin, sinh, sqrt, sub
, tan, tanh..)")
  ("matrix" "syntax: (.. det, invert, mat, multiply, transpose..)")
  ("array" "syntax: (.. append, array, array-list, array?, det, first, invert, last, mat, multiply, nth, nth-set, rest, set-nth, transpose..)")
  ("bit" "syntax: (.. <<, >>, &, |, ^, ~..)")
  ("predicates" "syntax: (.. array?, atom?, context?, directory?, empty?, file?, float?, global?, integer?, lambda?, legal?, list?, macro?, NaN?, nil?
, null?, number?, primitive?, protected?, quote?, string?, symbol?, true?, zero?..)")
  ("time-date" "syntax: (.. date, date-value, parse-date, now, time, time-of-day..)")
  ("stats" "syntax: (.. amb, bayes-query, bayes-train, normal, prob-chi2, prob-z, rand, random, randomize, seed..)")
  ("patterns" "syntax: (.. ends-with, find, find-all, match, parse, regex, replace, search, starts-with, unify..)")
  ("financial" "syntax: (.. fv, irr, nper, npv, pv, pmt..)")
  ("io" "syntax: (.. append-file, close, command-line, copy-file, device, exec, load, open, peek, print, println, read-buffer, read-char, read-file, r
ead-key, read-line, save, search, seek, write-buffer, write-char, write-file, write-line..)")
  ("unix" "syntax: (.. !, destroy, exec, fork, pipe, process, semaphore, share, wait-pid..)")
  ("file" "syntax: (.. change-dir, copy-file, delete-file, directory, file-info, make-dir, real-path, remove-dir, rename-file..)")
  ("http" "syntax: (.. base64-enc, base64-dec, delete-url, get-url, put-url, post-url, xml-error, xml-parse, xml-type-tags..)")
  ("sockets" "syntax: (.. net-accept, net-close, net-connect, net-error, net-eval, net-listen, net-local, net-lookup, net-peer, net-peek, net-ping, ne
t-receive, net-receive-from, net-receive-udp, net-select, net-send, net-send-to, net-send-udp, net-service, net-sessions..)")
  ("lisp-system" "syntax: (.. $, callback, catch, context, debug, default, delete, env, error-event, error-number, exit, global, import, main-args, ne
w, ostype, pretty-print, reset, set-locale, signal, sleep, sym, symbols, sys-error, sys-info, timer, throw, throw-error, trace, trace-highlight..)")
  ("libraries" "syntax: (.. address, flt, float, get-char, get-float, get-int, get-long, get-string, import, int, pack, unpack..)")
  ("lisp-internals" "syntax: (.. cpymem, dump..)")
  ("top" "syntax: (lists strings math matrix array bit predicates time-date stats patterns financial io unix file http sockets lisp-system libraries l
isp-internals)")



(set 'syntax (map last (filter (fn (z) (= (z 0) (string target))) command_lst)))
(if syntax
  (println (join syntax "n"))
  (println "No help for that command")
)
(string target)
)


/ignore the line breaks done by the phpbb forum software/



After the file is loaded the usage is:

Code Select Expand


:- (hh)
syntax: (hh command) or (hh top)
"help"

:-  (hh "top")
syntax: (lists strings math matrix array bit predicates time-date stats patterns financial io unix file http sockets lisp-system libraries lisp-internals)
"top"

:- (hh "bit")
syntax: (.. <<, >>, &, |, ^, ~..)
"bit"

[i]..and so on. For each particular function help looks like this:[/i]

:-  (hh "trim")
syntax: (trim which_str [ str-left-onechar_to_trim] [ str-right-onechar_to_trim ]) --> ret. string_trimmed
syntax: (trim which_str [ str-onechar_to_trim ]) --> ret. string_trimmed
"trim"
:-


It does not wrap in the normal xterm window, of course, and so looks neat and readable, too

[hsmyers]

lithper: I await the revisions!! Having said that I wonder about parsing the manual for the existing syntax line? Perhaps not 'BE LIKE VERB...' but timely and only needing update with new manual? Come to think of it, the same function that would parse the manual could also combine your improved text and offer up both. Might only have to worry about definition drift over time...



--hsm

[pjot]

There is also an online help in my VIM resourcefile, just checked it and surprisingly, it still seems to work (Unix only, I made it some years ago). I have stolen the idea from Cormullion: parse the newLisp documentation HTML file which is locally on your PC, and show the correct section.



http://www.turtle.dds.nl/newlisp/vimrc.txt">http://www.turtle.dds.nl/newlisp/vimrc.txt



You can use the help in the newLisp menu which is graphical, or enter ':Help <command>' (mind the capital H here).



It is easy to rewrite the VIM macro to open the HTML help in a WIn32 environment I'ld say, but unfortunately, I do not have have access to Win32 anymore.



Peter