File: newLISPdoc.html

package info (click to toggle)
newlisp 10.7.5-2
links: PTS, VCS
area: main
in suites: bookworm, bullseye, forky, sid, trixie
size: 6,248 kB
sloc: ansic: 33,280; lisp: 4,181; sh: 609; makefile: 215
file content (334 lines) | stat: -rw-r--r-- 11,373 bytes
parent folder | download | duplicates (3)
<?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>&lt;...&gt;</tt> angle braces are displayed in italic. 
Internally newLISPdoc uses <tt>&lt;em&gt;,&lt;/em&gt;</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>&lt;tt&gt;,&lt;/tt&gt;</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>&lt;h1&gt;</tt>,<tt>&lt;h2&gt;</tt>,<tt>&lt;h3&gt;</tt>,<tt>&lt;h4&gt;</tt>,
<tt>&lt;i&gt;</tt>,<tt>&lt;em&gt;</tt>,<tt>&lt;b&gt;</tt>,<tt>&lt;tt&gt;</tt>,<tt>&lt;p&gt;</tt>,
<tt>&lt;br&gt;</tt>,<tt>&lt;pre&gt;</tt>,<tt>&lt;center&gt;</tt>,<tt>&lt;blockquote&gt;</tt>
and <tt>&lt;hr&gt;</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 &lt;num-repeat&gt; &lt;str-message&gt;)
;; @param &lt;num-repeat&gt; The number of times to repeat.
;; @param &lt;str-message&gt; The message string to be printed.
;; @return Returns the message in &lt;str-message&gt;
;;
;; The function 'foo' repeatedly prints a string to 
;; standard out terminated by a line feed.
;;
;; @example
;; (example:foo 5 "hello world")
;; =&gt;
;; "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:&nbsp;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>&nbsp;</p><center>- &sect; -</center><p>&nbsp;</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>&nbsp;</p>
 The function <tt>foo</tt> repeatedly prints a string to 
 standard out terminated by a line feed.
<p>&nbsp;</p>
<p>&nbsp;</p><b>example:</b><blockquote><pre>
 (example:foo 5 "hello world")
 =&gt;
 "hello world"
 "hello world"
 "hello world"
 "hello world"
 "hello world"</pre></blockquote>
 See the <a href="#source">source</a>.
<p>#nbsp;</p><center>- &part; -</center><br/>
<center><font face='Arial' size='-2' color='#444444'>
generated with <a href="http://newlisp.org">newLISP</a>&nbsp;
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:&nbsp;example.lsp</a></h2>
<a href="#example_foo">foo</a>&nbsp; &nbsp; 
<p>&nbsp;</p><center>- &part; -</center><br/>
<center><font face='Arial' size='-2' color='#444444'>
generated with <a href="http://newlisp.org">newLISP</a>&nbsp;
and <a href="http://newlisp.org/newLISPdoc.html">newlispdoc</a>
</font></center>
</blockquote>

<hr />

</body>
</html>