doc/newLISPdoc.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <META http-equiv="Content-Type" content="text/html; charset=utf-8">
   5 <title>newLISPdoc</title>
   6
   7 <style type="text/css" media="screen">
   8 <!--
   9 span.arw {
  10         color:#666666;
  11         font-size: 100%;
  12         }
  13
  14 body, p {
  15         font-family: Georgia, Times New Roman, Times, serif;
  16         line-height: 115%;
  17         }
  18
  19 h1 {
  20         font-family: Georgia, Times New Roman, Times, serif;
  21         font-size: 130%;
  22         }
  23
  24 h2, h3, h4 {
  25         font-family: Georgia, Times New Roman, Times, serif;
  26         font-size: 110%;
  27         }
  28
  29 pre {
  30         font-family: Andale Mono, "Bitstream Vera Sans Mono", Monaco, "Courier New";
  31         font-size: 100%;
  32         }
  33
  34 tt {
  35         font-family: Andale Mono, "Bitstream Vera Sans Mono", Monaco, "Courier New";
  36         font-size: 100%;
  37         }
  38 -->
  39 </style>
  40 </head>
  41 <body style="margin: 20px;" text="#222222" bgcolor="#FFFFFF"
  42                         link="#376592" vlink="#551A8B" alink="#ffAA28">
  43
  44 <center>
  45 <h1>newLISPdoc - the newLISP documentation program</h1>
  46 <font size="-1">last edited 2008-02-27</font>
  47 </center>
  48
  49 <p>Comments in newLISP source files can be converted
  50 to HTML documentation using only a few tags in comments. The newLISPdoc system
  51 is designed to use a minimum of tags and leave the tagged comments still readable.</p>
  52
  53 <p>newLISPdoc also generates an index page for all newLISP source files
  54 generated.</p>
  55
  56 <p>See here for the <a href="http://newlisp.org/syntax.cgi?code/newlispdoc.txt">source of newLISPdoc</a> .
  57 The program and this documentation are also part of the
  58 source distribution of newLISP since version 9.0. Since newLISP version 9.1 syntax
  59 highlighting is built into <tt>newlispdoc</tt> which is installed
  60 in the same directory as the main newLISP executable program. The script
  61 <tt>syntax.cgi</tt> is still available for web site installations, but is not
  62 required anymore for <tt>newlispdoc</tt>.</p>
  63
  64 <h3>Usage</h3>
  65 <p>From within the directory where the modules are, execute with all module filenames
  66 to process on the commandline. For example to process the files <tt>mysql.lsp</tt>,
  67 <tt>odbc.lsp</tt> and <tt>sqlite3.lsp</tt> do:</p>
  68
  69 <blockquote><pre>
  70 newlispdoc mysql.lsp odbc.lsp sqlite.lsp
  71 </pre></blockquote>
  72
  73 <p>Or on Win32:</p>
  74
  75 <blockquote><pre>
  76 newlisp newlispdoc mysql.lsp odbc.lsp sqlite.lsp
  77 </pre></blockquote>
  78
  79 <p>This will generate <tt>index.html</tt>, <tt>mysql.lsp.html</tt>, <tt>odbc.lsp.html</tt>
  80 and <tt>sqlite.lsp.html</tt> all in the same directory, where the command was executed.
  81  The page <tt>index.html</tt> contains links to all other pages.</p>
  82
  83 <p>The command line flag <tt>-s</tt> can be supplied to additionally
  84 generate syntax highlighted HTML versions of the source files and put a link
  85 to the highlighted version of the source file on the documentation page:</p>
  86
  87 <blockquote><pre>
  88 newlispdoc -s mysql.lsp odbc.lsp sqlite.lsp
  89 newlispdoc -s *.lsp
  90 </pre></blockquote>
  91
  92 <p>Or on Win32:</p>
  93
  94 <blockquote><pre>
  95 newlisp newlispdoc -s mysql.lsp odbc.lsp sqlite.lsp
  96 </pre></blockquote>
  97
  98 <p>Since version 1.3 of newLISPdoc a file containing URLs of source file locations
  99 can be specified. This allows indexing and documenting of newLISP source code distributed
 100 on different sites:</p>
 101
 102 <blockquote><pre>
 103 newlispdoc -url file-with-urls.txt
 104 newlispdoc -s -url file-with-urls.txt
 105 </pre></blockquote>
 106
 107 <p>Or on Win32:</p>
 108
 109 <blockquote><pre>
 110 newlisp newlispdoc -url file-with-urls.txt
 111 newlisp newlispdoc -s -url file-with-urls.txt
 112 </pre></blockquote>
 113
 114 <p><tt>http://</tt> and <tt>file://</tt> URLs can be used. Like with individual files,
 115 the <tt>-s</tt> switch can be specified to generate also syntax highlighted source files.
 116 A URL file contains one URL per line. No other information is allowed in the file. The
 117 following is a sample URL file:</p>
 118
 119 <blockquote><pre>
 120 http://asite.com/code/afile.lsp
 121 http://othersite.org/somefile.lsp
 122 file:///usr/home/joe/program.lsp
 123 </pre></blockquote>
 124
 125 <p>The last line shows a file URL from the local filesystem.</p>
 126
 127 <p>All generated files will be written to the current directory.</p>
 128
 129 <h3>Tags</h3>
 130
 131 <p>The following tags start at the beginning of a line with
 132 2 semicolons and one space before the tag:</p>
 133
 134 <blockquote><pre>
 135 ;; @module one word for module name
 136 ;; @index Title and URL for index page
 137 ;; @description one line description of the module
 138 ;; @location the original URL location of the source file
 139 ;; @version one line version info
 140 ;; @author one line for author info
 141 ;; @syntax one line syntax pattern
 142 ;; @param name description on one line
 143 ;; @return description on one line
 144 ;; @example multiline code example starting on next line
 145 </pre></blockquote>
 146
 147 <p>The only required tag is either the <tt>@module</tt> tag or alternatively
 148 the <tt>@index</tt> tag. If neither one tag is present in the file, it will
 149 not be processed. All other tags are optional. Only lines starting with ;;
 150 (2 semicolons) are processed. Program comment text which should not appear
 151 in the documentation should start with only one semicolon.</p>
 152
 153 <p>The one line description of the <tt>@description</tt> tag will be put under the module
 154 name on the index and module doc page. This and the <tt>@location</tt> where added in
 155 June 2007, and are not part of the newlispdoc program in the newLISP v. 9.1 release.</p>
 156
 157 <p>A function may have multiple <tt>@syntax</tt> tags each on consecutive lines.</tt>
 158
 159 <p>The following is the only tag, which can be embedded anywhere in
 160 the text. Between the tag link specificaton and description is exactly on
 161 space:</p>
 162
 163 <blockquote><pre>
 164 @link link description
 165 </pre></blockquote>
 166
 167 <p>All words between <tt>&lt;...&gt;</tt> angle braces are displayed in italic.
 168 Internally newLISPdoc uses <tt>&lt;em&gt;,&lt;/em&gt;</tt> tags for formatting. They
 169 should be used for parameter specs after the @param tag and in text referring
 170 to those parameters..</p>
 171
 172 <p>All words between single quotes <tt>' ... '</tt> are printed in monospace.
 173 Internally newLISPdoc uses <tt>&lt;tt&gt;,&lt;/tt&gt;</tt> tags for formatting.</p>
 174
 175 <p>All other lines starting with 2 semicolons contain descriptive
 176 text. An empty line with only 2 semicolons at the beginning
 177 is a break between paragraphs of text.</p>
 178
 179 <p>Lines not starting with 2 semicolons are ignored by newLISPdoc. This
 180 allows doing code comments with just one semicolon.</p>
 181
 182 <p>If more formatting is required than what is offered by newLISPdoc, the
 183 following simple HTML tags and their closing forms may also be used:
 184 <tt>&lt;h1&gt;</tt>,<tt>&lt;h2&gt;</tt>,<tt>&lt;h3&gt;</tt>,<tt>&lt;h4&gt;</tt>,
 185 <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>,
 186 <tt>&lt;br&gt;</tt>,<tt>&lt;pre&gt;</tt>,<tt>&lt;center&gt;</tt>,<tt>&lt;blockquote&gt;</tt>
 187 and <tt>&lt;hr&gt;</tt>.</p>
 188 <h3>Linking to other module collections</h3>
 189 <p>newLISPdoc generates and index page for all modules documented. A special tag <tt>@index</tt>
 190 can be used to show a link on the index page to an index of other module collections. This way
 191 multilevel indices of modules can be created. To display a link to another module collection
 192  on the index page, create a file containing a <tt>@index</tt> and a <tt>@descrption</tt> link:</p>
 193
 194 <blockquote><pre>
 195 ; - other-collection.txt -
 196 ;; @index OtherCollection http://example.com/modules
 197 ;; @description Modules from OtherCollection
 198 </pre></blockquote>
 199
 200 <p>Use one or more of these files on the newLISPdoc command line as any other
 201 source file:</p>
 202
 203 <blockquote><pre>
 204 newlispdoc -s other-collection.txt *.lsp
 205 </pre></blockquote>
 206
 207 <p>This will show the index entry for OtherCollection on the module index before listing
 208 all modules in <tt>*.lsp</tt>.</p>
 209
 210 <hr>
 211
 212 <a name="source"></a>
 213 <h3>Examples</h3>
 214
 215 <p>The following is the commented source of and example program
 216 followed by the pages generated in HTML:</p>
 217
 218 <blockquote><pre>
 219 ;; @module example.lsp
 220 ;; @author John Doe, johndoe@example.com
 221 ;; @version 1.0
 222 ;;
 223 ;; This module is an example module for the newlispdoc
 224 ;; program, which generates automatic newLISP module
 225 ;; documentation.
 226
 227
 228 ;; @syntax (example:foo &lt;num-repeat&gt; &lt;str-message&gt;)
 229 ;; @param &lt;num-repeat&gt; The number of times to repeat.
 230 ;; @param &lt;str-message&gt; The messsage string to be printed.
 231 ;; @return Returns the message in &lt;str-message&gt;
 232 ;;
 233 ;; The function 'foo' repeatedly prints a string to
 234 ;; standard out terminated by a line feed.
 235 ;;
 236 ;; @example
 237 ;; (example:foo 5 "hello world")
 238 ;; =&gt;
 239 ;; "hello world"
 240 ;; "hello world"
 241 ;; "hello world"
 242 ;; "hello world"
 243 ;; "hello world"
 244
 245 (context 'example)
 246
 247 (define (foo n msg)
 248         (dotimes (i n)
 249                 (println msg))
 250 )
 251
 252 ;; See the @link http://example.com/example.lsp source .
 253 </pre></blockquote>
 254
 255 <p>Below the <tt>example.lsp.html</tt> and <tt>index.html</tt>  page generated:</p>
 256
 257 <hr>
 258 <a name="example"></a>
 259 <p><a href="#index">Module index</a></p><h2>Module:&nbsp;example.lsp</h2><b>Author: </b>John Doe, johndoe@example.com<br/>
 260 <b>Version: </b>1.0<br/>
 261 <p></p>
 262  This module is an example module for the newlispdoc
 263  program, which generates automatic newLISP module
 264  documentation.
 265
 266
 267 <p></p><center>- &sect; -</center><p></p>
 268 <a name="example_foo"></a><h3>Syntax: (<font color=#CC0000>example:foo</font> <em>num-repeat</em> <em>str-message</em>)</h3>
 269 <b>parameter: </b><em>num-repeat</em> - The number of times to repeat.<br/>
 270 <b>parameter: </b><em>str-message</em> - The messsage string to be printed.<br/>
 271 <p><b>return: </b>Returns the message in <em>str-message</em></p>
 272 <p></p>
 273  The function <tt>foo</tt> repeatedly prints a string to
 274  standard out terminated by a line feed.
 275 <p></p>
 276 <p></p><b>example:</b><blockquote><pre>
 277  (example:foo 5 "hello world")
 278  =&gt;
 279  "hello world"
 280  "hello world"
 281  "hello world"
 282  "hello world"
 283  "hello world"</pre></blockquote>
 284  See the <a href="#source">source</a>.
 285 <p></p><center>- &part; -</center><br/>
 286 <center><font face='Arial' size='-2' color='#444444'>
 287 generated with <a href="http://newlisp.org">newLISP</a>&nbsp;
 288 and <a href="http://newlisp.org/newLISPdoc.html">newlispdoc</a>
 289 </font></center>
 290 </blockquote>
 291
 292 <hr>
 293
 294 <p>Below the index page <tt>index.html</tt> which was generated. When more than one module is
 295 specified on the command line, the index page will show one link line for
 296 each module.</p>
 297
 298 <hr>
 299
 300 <a name="index"></a>
 301 <blockquote>
 302 <a href="#example"><h2>Module:&nbsp;example.lsp</h2></a>
 303 <a href="#example_foo">foo</a>&nbsp; &nbsp;
 304 <p></p><center>- &part; -</center><br/>
 305 <center><font face='Arial' size='-2' color='#444444'>
 306 generated with <a href="http://newlisp.org">newLISP</a>&nbsp;
 307 and <a href="http://newlisp.org/newLISPdoc.html">newlispdoc</a>
 308 </font></center>
 309 </blockquote>
 310
 311 <hr>
 312
 313 </body>
 314 </html>