On Tuesday, Sep 16, 2003, at 12:57 Europe/London, Stephen Leach wrote:
[snip]
> I am intending to base the help system on the simple principles of the
> Poplog help system which I have always admired. There are several key
> ideas I want to copy and modify to include the advantages of HTML.
> However, I am appealing for other views about how to write a usable,
> portable, maintainable help system.
[snip]
> Similarly, headings might be identified as lines that begin with, say,
> a sequence of a couple of '.', '-' or '=' followed by a space. And
> the first few lines of the file could follow a set format.
>
> And we would need conventions for code or other quoted material. The
> simple convention of "preformatting" lines that do not begin in column
> 1 is probably good enough.
>
> Converting conventions these on-the-fly into decent looking HTML will
> be easy. Writing according to the conventions is also quite natural,
> as years of experience with Poplog has shown.
[snip]
> [3] Probably the main enhancement I propose is to have some
> dynamically generated overview files - the equivalent of ENTER help
> index. Those indexes are built statically. However, the great
> advantage of a web site is that you don't have to do that. Of course
> this means you cannot statically search those "files" - but that's
> unlikely to be a practical issue.
[snip]
</lurk>
The above suggest something wiki-ish in style to me. I've found wiki
variants a stupidly efficient way of quickly building up categorised
sets of documentation.
Also, writing a wiki and/or a blog seems to be the web application
version of "hello world" these days - so you'll need to write ones in
Spice anyway :-)
In might also be worth looking at Perl's POD format
(<http://www.perldoc.com/perl5.6/pod/perlpod.html>). Having something
you can inline with code (and possible move over into literate
programming territory) might be quite fun.
Adrian
<lurk>
|