[Date Prev] [Date Next] [Thread Prev] [Thread Next] Date Index Thread Index Search archive:
Date:Mon Sep 17 23:36:38 2003 
Subject:Re: help system - ideas wanted 
From:adrianh 
Volume-ID:1030917.01 

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>