<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>newLISPdoc</title>
<style type="text/css" media="screen">
<!--
span.arw {
color:#666666;
font-size: 100%;
}
body, h4, p {
font-family: Lucida Sans, Helvetica, sans-serif;
line-height: 120%;
max-width: 900px;
}
h1, h2, h3 {
margin-top: 3%;
font-family: Lucida Sans, Helvetica, sans-serif;
line-height: 120%;
color: #404040;
}
pre {
font-family: Andale Mono, "Bitstream Vera Sans Mono", Monaco, "Courier New";
font-size: 100%;
}
tt {
font-family: Andale Mono, "Bitstream Vera Sans Mono", Monaco, "C5urier New";
font-size: 100%;
}
-->
</style>
</head>
<body style="margin: 20px;" text="#222222" bgcolor="#FFFFFF"
link="#376592" vlink="#551A8B" alink="#ffAA28">
<center>
<h1>newLISPdoc - the newLISP documentation program</h1>
<font size="-1">last edited 2015-04-16</font>
</center>
<p>Comments in newLISP source files can be converted
to HTML documentation using only a few tags in comments. The newLISPdoc system
is designed to use a minimum of tags and leave the tagged comments still readable.</p>
<p>newLISPdoc also generates an index page for all newLISP source files
generated.</p>
<p>See here for the <a href="http://newlisp.org/syntax.cgi?code/newlispdoc.txt">source of newLISPdoc</a> .
The program and this documentation are also part of the
source distribution of newLISP since version 9.0. Since newLISP version 9.1 syntax
highlighting is built into <tt>newlispdoc</tt> which is installed
in the same directory as the main newLISP executable program. The script
<tt>syntax.cgi</tt> is still available for web site installations, but is not
required anymore for <tt>newlispdoc</tt>.</p>
<h3>Usage</h3>
<p>From within the directory where the modules are, execute with all module filenames
to process on the commandline. For example to process the files <tt>mysql.lsp</tt>,
<tt>odbc.lsp</tt> and <tt>sqlite3.lsp</tt> do:</p>
<blockquote><pre>
newlispdoc mysql.lsp odbc.lsp sqlite.lsp
</pre></blockquote>
<p>Or on Windows:</p>
<blockquote><pre>
newlisp newlispdoc mysql.lsp odbc.lsp sqlite.lsp
</pre></blockquote>
<p>This will generate <tt>index.html</tt>, <tt>mysql.lsp.html</tt>, <tt>odbc.lsp.html</tt>
and <tt>sqlite.lsp.html</tt> all in the same directory, where the command was executed.
The page <tt>index.html</tt> contains links to all other pages.</p>
<p>If the current directory contains the file <tt>newlispdoc.css</tt>, HTML output
will be formatted accordingly. For a sample file see
<tt>util/newlispdoc.css</tt> in the source distribution.</p>
<p>The command line flag <tt>-s</tt> can be supplied to additionally
generate syntax highlighted HTML versions of the source files and put a link
to the highlighted version of the source file on the documentation page:</p>
<blockquote><pre>
newlispdoc -s mysql.lsp odbc.lsp sqlite.lsp
newlispdoc -s *.lsp
</pre></blockquote>
<p>The <tt>-d</tt> flag supplies a download link to the raw source:</p>
<blockquote><pre>
newlispdoc -d *.lsp
newlispdoc -s -d *.lsp
</pre></blockquote>
<p>One or both options can be supplied.</p>
<p>Or on Windows:</p>
<blockquote><pre>
newlisp newlispdoc -s mysql.lsp odbc.lsp sqlite.lsp
</pre></blockquote>
<p>Since version 1.3 of newLISPdoc a file containing URLs of source file locations
can be specified. This allows indexing and documenting of newLISP source code distributed
on different sites:</p>
<blockquote><pre>
newlispdoc -url file-with-urls.txt
newlispdoc -s -url file-with-urls.txt
</pre></blockquote>
<p>Or on Windows:</p>
<blockquote><pre>
newlisp newlispdoc -url file-with-urls.txt
newlisp newlispdoc -s -url file-with-urls.txt
</pre></blockquote>
<p><tt>http://</tt> and <tt>file://</tt> URLs can be used. Like with individual files,
the <tt>-s</tt> switch can be specified to generate also syntax highlighted source files.
A URL file contains one URL per line. No other information is allowed in the file. The
following is a sample URL file:</p>
<blockquote><pre>
http://asite.com/code/afile.lsp
http://othersite.org/somefile.lsp
file:///usr/home/joe/program.lsp
</pre></blockquote>
<p>The last line shows a file URL from the local filesystem.</p>
<p>All generated files will be written to the current directory.</p>
<h3>Tags</h3>
<p>The following tags start at the beginning of a line with
2 semicolons and one space before the tag:</p>
<blockquote><pre>
;; @module one word for module name
;; @index Title and URL for index page
;; @description one line description of the module
;; @location the original URL location of the source file
;; @version one line version info
;; @author one line for author info
;; @syntax one line syntax pattern
;; @param name description on one line
;; @return description on one line
;; @example multiline code example starting on next line
</pre></blockquote>
<p>The only required tag is either the <tt>@module</tt> tag or alternatively
the <tt>@index</tt> tag. If neither one tag is present in the file, it will
not be processed. All other tags are optional. Only lines starting with ;;
(2 semicolons) are processed. Program comment text which should not appear
in the documentation should start with only one semicolon.</p>
<p>The one line description of the <tt>@description</tt> tag will be put under the module
name on the index and module doc page. This and the <tt>@location</tt> where added in
June 2007, and are not part of the newlispdoc program in the newLISP v. 9.1 release.</p>
<p>A function may have multiple <tt>@syntax</tt> tags each on consecutive lines.</p>
<p>The following is the only tag, which can be embedded anywhere in
the text. Between the tag link specification and description is exactly one
space:</p>
<blockquote><pre>
@link link description
</pre></blockquote>
<p>Custom tags can be made up by just prepending the custom name with a <tt>@</tt>.
The text after the custom tag will be translated as usual, e.g. it may contain
a <tt>@link</tt> tag. Like in most other tags, text is limited to the same line.</p>
<p>All words between <tt><...></tt> angle braces are displayed in italic.
Internally newLISPdoc uses <tt><em>,</em></tt> tags for formatting. They
should be used for parameter specs after the @param tag and in text referring
to those parameters..</p>
<p>All words between single quotes <tt>' ... '</tt> are printed in monospace.
Internally newLISPdoc uses <tt><tt>,</tt></tt> tags for formatting.</p>
<p>All other lines starting with 2 semicolons contain descriptive
text. An empty line with only 2 semicolons at the beginning
is a break between paragraphs of text.</p>
<p>Lines not starting with 2 semicolons are ignored by newLISPdoc. This
allows doing code comments with just one semicolon.</p>
<p>If more formatting is required than what is offered by newLISPdoc, the
following simple HTML tags and their closing forms may also be used:
<tt><h1></tt>,<tt><h2></tt>,<tt><h3></tt>,<tt><h4></tt>,
<tt><i></tt>,<tt><em></tt>,<tt><b></tt>,<tt><tt></tt>,<tt><p></tt>,
<tt><br></tt>,<tt><pre></tt>,<tt><center></tt>,<tt><blockquote></tt>
and <tt><hr></tt>.</p>
<h3>Linking to other module collections</h3>
<p>newLISPdoc generates and index page for all modules documented. A special tag <tt>@index</tt>
can be used to show a link on the index page to an index of other module collections. This way
multilevel indices of modules can be created. To display a link to another module collection
on the index page, create a file containing a <tt>@index</tt> and a <tt>@description</tt> link:</p>
<blockquote><pre>
; - other-collection.txt -
;; @index OtherCollection http://example.com/modules
;; @description Modules from OtherCollection
</pre></blockquote>
<p>Use one or more of these files on the newLISPdoc command line as any other
source file:</p>
<blockquote><pre>
newlispdoc -s other-collection.txt *.lsp
</pre></blockquote>
<p>This will show the index entry for OtherCollection on the module index before listing
all modules in <tt>*.lsp</tt>.</p>
<hr />
<a name="source"></a>
<h3>Examples</h3>
<p>The following is the commented source of and example program
followed by the pages generated in HTML:</p>
<blockquote><pre>
;; @module example.lsp
;; @author John Doe, johndoe@example.com
;; @version 1.0
;;
;; This module is an example module for the newlispdoc
;; program, which generates automatic newLISP module
;; documentation.
;; @syntax (example:foo <num-repeat> <str-message>)
;; @param <num-repeat> The number of times to repeat.
;; @param <str-message> The message string to be printed.
;; @return Returns the message in <str-message>
;;
;; The function 'foo' repeatedly prints a string to
;; standard out terminated by a line feed.
;;
;; @example
;; (example:foo 5 "hello world")
;; =>
;; "hello world"
;; "hello world"
;; "hello world"
;; "hello world"
;; "hello world"
(context 'example)
(define (foo n msg)
(dotimes (i n)
(println msg))
)
;; See the @link http://example.com/example.lsp source .
</pre></blockquote>
<p>Below the <tt>example.lsp.html</tt> and <tt>index.html</tt> page generated:</p>
<hr/>
<a name="example"></a>
<p><a href="#index">Module index</a></p><h2>Module: example.lsp</h2><b>Author: </b>John Doe, johndoe@example.com<br/>
<b>Version: </b>1.0<br/>
<p>
This module is an example module for the newlispdoc
program, which generates automatic newLISP module
documentation.
</p>
<p> </p><center>- § -</center><p> </p>
<a name="example_foo"></a><h3>Syntax: (<font color=#CC0000>example:foo</font> <em>num-repeat</em> <em>str-message</em>)</h3>
<b>parameter: </b><em>num-repeat</em> - The number of times to repeat.<br/>
<b>parameter: </b><em>str-message</em> - The message string to be printed.<br/>
<p><b>return: </b>Returns the message in <em>str-message</em></p>
<p> </p>
The function <tt>foo</tt> repeatedly prints a string to
standard out terminated by a line feed.
<p> </p>
<p> </p><b>example:</b><blockquote><pre>
(example:foo 5 "hello world")
=>
"hello world"
"hello world"
"hello world"
"hello world"
"hello world"</pre></blockquote>
See the <a href="#source">source</a>.
<p>#nbsp;</p><center>- ∂ -</center><br/>
<center><font face='Arial' size='-2' color='#444444'>
generated with <a href="http://newlisp.org">newLISP</a>
and <a href="http://newlisp.org/newLISPdoc.html">newlispdoc</a>
</font></center>
<hr />
<p>Below the index page <tt>index.html</tt> which was generated. When more than one module is
specified on the command line, the index page will show one link line for
each module.</p>
<hr />
<a name="index"></a>
<center><h2>Index</h2></center>
<blockquote>
<h2><a href="#example">Module: example.lsp</a></h2>
<a href="#example_foo">foo</a>
<p> </p><center>- ∂ -</center><br/>
<center><font face='Arial' size='-2' color='#444444'>
generated with <a href="http://newlisp.org">newLISP</a>
and <a href="http://newlisp.org/newLISPdoc.html">newlispdoc</a>
</font></center>
</blockquote>
<hr />
</body>
</html>