lspdoc v1.40 Create automaticly a documentation of all lisp files in Ascii or winhelp format as LSPDOC.HLP usage: lspdoc [options] [sourcefile(s)...] sourcefile(s): Default *.lsp options: --help displays this help page (also -h) --rtf create a rtf only --hlp create a rtf and a winhelp file automatically [Default if <=25 files] --html create a html (experimental) --doc create a ASCII doc --hdr includes the fileheader (general description) too --name="name" basename of outputfile, Default: LSPDOC --title="Title string", Default: "Lisp Function Library" -v verbose processing -d debug --nostats no statistics --hlp only: --hc3 for the old help compiler hc v3.x, default: hcrtf v4.x hc4 is better, but hc3 takes bigger files and the old hc4 has bugs. hcp.exe or hcrtf.exe must be in the PATH. --nohpj don't create new lspdoc.hpj, take old if existing --noexec don't execute the help compiler --nohelp don't display created winhelp --ansi use ansi character set instead of DOS/OEM (CP 850) --cp="" use codepage --nc no winhelp compression (faster) --table creates tables for the contents and index page, if you've got a lot of files and funcs (like me) --bighlp = --hlp --table [Default Option if >25 files] --brackets for winhelp keyword indices --editor="filename" editor for winhelp Parses globals and functions with its parameters along with the description, if the description appears immediately before with ; comments. (a blank line may be before the definition) Example: ;;; TEST-FUNC ;;; ;;; Description as following, ... (defun test-func (a b / x1 x2) ------------------------------------------------------------------ Shareware Restriction: You may use the Shareware version for 30 days. Then you have to delete it or pay for it. It now has a limitation of max. 15 edit buttons and 100 links. The full version is unrestricted, comes with perl source code and is usable as perl library to create arbitrary formatted winhelp files from text sources. Please look at the sample LSPDOC.HLP which ran through some lisp files from the internet. Maybe there are some goodies for you. Note that none of these files were documented very well. How to describe the functions to be displayed correctly? ------------------------------------------------------------------ Globals are symbols, defined with 1) (setq at the first column or 2) (std-defconstant ' or 3) (defconstant The value is parsed only until the next ) or ; on the same line. If the value continues on the next lines, it is not shown in the help file. Values are seperated from the symbol and the description by = Example: ;;; if load messages should be printed (setq *LOAD-VERBOSE* T) -> *LOAD-VERBOSE* - T - if load messages should be printed ;;; dependant on *BREAK* too (setq *DEBUG* (or *BREAK* *DEBUG*)) -> *DEBUG* (or - dependant on *BREAK* too Functions are defined with (defun at the first column or some spaces before. The parameters are parsed only from the same line. If they continue on the next lines, it is not shown in the help file. Example: ;;; load a file (defun LOAD (f / x) -> (LOAD f) - load a file Descriptions are gathered from all the commented lines before the definition. There may occur blank lines immediatly before the definition. Valid descriptions: ;;; some desc ;;; (defun some () is valid: some desc ; some desc (defun some () is valid: some desc ;;; some desc (defun some () is valid: some desc Invalid descriptions: ;;; line 1 ;;; (defun some () description is empty (defun some () description is empty How to get rid of unwanted comments? You see a function description that is the outcommented function from above? Just insert a blank line and a line with ; before the definition. Example: Wrong: ;;; ) ;unused code ;;; ) ;or some comment not ;;;) ;belonging to the below function, (defun func () Corrected: ;;; ) ;;; ) ;;;) ; (defun func () Note that (defun) may be indented by whitespace (Sources by Tony Tanzillo are often indented) but globals with (setq) must appear at the first column! Globals that are not defined outside the functions body are not detected, but may be defined in the special function: (special '(list-of-globals ...)) which is needed for acomp, the AutoLISP compiler. The edit button starts the program associated with the file on the current page, usually with the extension .LSP So set up the extension .LSP with your favourite editor. With -hc3 this does not work, so you have to define it manually if you want an better editor than notepad. I use it with VitalLISP 2.0 stand-alone. What else could be done? C/C++/Java or Pascal language support would be no problem too, but should those depricated languages be supported? Better you learn a real language. Maybe perl too, but I dont have that much perl code, that's not already documented in the perl help. And there's pod2rtf.pl ------------------------------------------------------------------ Legal and money stuff: lspdoc is (c) 1996,97,98 by Reini Urban A single license sells for US $20 excluding shipping and taxes. Ordering and payment is best done with sending me a check payable to me by mail. Preferred is shipping by electronic e-mail or by ftp. It should run on almost every operating system, only the winhelp compiler is restricted onto the DOS/Win3.1/Win95/WinNT/OS2 platforms. The package comes with perl.exe and lspdoc.pl. The Microsoft Windows Helpcompiler (either HC.EXE, HCP.EXE or better HCRFT.EXE must be provided by yourself. It is shipped with almost every windows programming toolkit) HTML output is experimental. Please contact the author at the above mail address or at Reini Urban X-RAY Nibelungengasse 3 A-8010 Graz, Austria ------------------------------------------------------------------ # Revisions: # 1.39 03:24 06.07.98 # added doc for defconstant # changed - to = for globals # 1.38 30.06.98 16:43 # support for (std-defconstant) # 1.37 29.06.98 18:39 # removed \par in do_jump: \uldb # Shareware limitations: 15 files for edit and 100 links # honor -nohpj switch # 1.36: 30.04.98 15:25 # works as main or as library: # require "lspdoc.pl"; # &lspdoc'keyword(); # 1.35: 03.02.98 17:17 # fixed -name, # -brackets => (func params) brackets in the searchable index confuse winhelp # 1.34: 14.11.97 15:00 # expands command line wildcards # 1.33: 04.08.97 11:53 # gets *.lsp and *.mnl per default if no files are specified on the # command line # 1.32: 27.06.97 10:56 # getopt fixup, ignore lspdoc.ignore if file is specified on commandline # -hdr works okay, -hc4 default even with more files (>25) # created a stand-alone exe and a shareware version. # 1.31: 21:19 03.05.97 # >25 -table # 1.3: 01.03.97 10:26 # extended Posix GetOpts::Long module (--long or -l or --nolong) # fixed -hdr # 1.21: 05.02.97 10:03 # added option -noexec, # removed starting paren "(" from K help keyword with -hc3, # it confused the search engine # changed hc3 executable to hc.exe (hcp caused errors on my # virtual nt machine) # -hdr for file headers (reimplemented) # 1.2: 19.01.97 14:20 # $title bugfix (Edit button does not work), # Edit button works now with absolute filepaths, # -bighlp Default option (-table only if > 25 files) # hc4 error only with >2 files (very strange, did MS hire some adesk programmers?) # 1.11: 15.12.96 # -bighlp, -name # 1.1: 11.12.96 17:49 # ignore all files in lspdoc.ignore (on line per file), # edit button # 1.0: 10.12.96 05:59 # create hpj file and call help compiler, # added howto pages to lspdoc.hlp, # new options -ansi, -nc, -nohpj # corrected OEM chars in hc3 and hc4, # fixed desc paragraph indentation, # fixed globals parsing # 0.97: 09.12.96 16:51 # -table: for index and contents tables # 0.96: 08.12.96 # alphabetic index # 0.95: 07.12.96 20:51 # handles empty lines before func def # 0.9: 20.11.96 # creates rtf fileindex # with no arguments processes *.lsp --- Reini Urban, lspdoc v1.40, 25.07.98 16:59 e-mail: web: http://xarch.tu-graz.ac.at/autocad/lsp_tools/#lspdoc