Hello.
Thank you, Lutz, for your thoughtful reply.
Another documentation option is to add embedded documentation built-ins to newLisp.
For example:
Code: Select all
(doc:section
(head "Hello World Program")
(para "This program prints out (i "Hello, World"))
)
(print "Hello, World")
newLisp could work like Perl does with
POD.
POD contains mark-up (that looks like
=begin and
=end) for headings, paragraphs, and lists, and additional inline markup for filenames, indexes,
italics, literal code, cross-references, et cetera. Perl ignores every line that starts with
=. Scripts can extract and preprocess the documentation for
latex and
troff, or transform the documentation directly into
html.
The POD systems lets authors who publish their code to CPAN rely on one documentation mark-up language to document their modules. What if newLisp starts a
CNAN (
Comprehensive newLisp Archive Network)?
You can publish embedded documentation specifications for newlisp modules. The specifications will allow programmers to author modules that contain newlisp documentation that fits a standard format that newLisp ignores.
Maybe newLisp could ignore documentation code unless prompted to process it using a command-line switch.
doc: would be a possible namespace prefix (unless/until you make a switch to using namespace uri associations to distinguish namespaces). Then newlisp could output either formatted content with a particular target, or just the documentation code.
For example:
Code: Select all
$newlisp --doc hello_world.lsp
(doc:section
(head "Hello World Program")
(para "This program prints out (i "Hello, World"))
)
$newlisp --doc="nldoc2html.lsp" hello_world.lsp
<html>
<head>
<title>Hello World Program</title>
</head>
<body>
<h1>Hello World Program</h1>
<p>This program prints out <i>Hello, world</i></p>
</body>
</html>
Embedded documentation would help a standard set of documentation grow quickly, and allow you to build a public module distribution and documentation system efficiently. You intend newLisp users to rely on your system, so you keep the mark-up language as minimal as
POD.
Perl provides
information about how to manage submission of perl modules. They make a special request that authors check existing namespaces before submitting additional code.
This points out a possible advantage of separating namespaces from namespace prefixes. It's easier to create a unique namespace uri than it is to create a unique object prefix, particularly a short one that makes some sense.
I certainly understand your feelings about documentation needing to have character and be published by individuals. That's what books published by companies like O'Reilly have, and that's a good thing. Cormullion's tutorial is analogous to a
Learning newLisp book, while Mr. Small's book could be expanded into a
newLisp Pocket Reference (because it's so terse), with addition of appropriate reference information.
I'm just hoping that through standardization, a system of documentation will develop in which the community of users can provide basic information without worrying about whether their writing has any character or personality. Something like the Perl
POD system.
-Noah