[Date Prev] [Date Next] [Thread Prev] [Thread Next] Date Index Thread Index Search archive:
Date:Mon Sep 17 21:05:54 2003 
Subject:help system - ideas wanted 
From:steve 
Volume-ID:1030917.02 

Hi,

I am in the process of designing the on-line help system for my Open Spice website; Spice is a programming language that is heavily influenced by Pop-11.  

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.

These are the points I see as especially worthwhile:

[1] I want to retain the basic division into doc/help/ref/teach directories.  However, I am thinking of adding several new directories such as "example" and "how-to".  

The "example" directory is, I think, uncontroversial.  It is simply a place to collect annotated programs.  Logically it could go under "teach", I suppose, but it is important to be able to separate the program from the tutorial text.  I am confident that this is a sensible addition & probably should be added to Poplog itself.

The "how-to" directory would contain recipes for doing specific things.  In the Poplog system this type of material could arguably go under "help" or "teach".  Good examples would be HELP *INITIAL (how-to customize Poplog) and HELP *EFFICIENCY (how-to write efficient code).  As a result I expect the help directory will contain files that are either about syntax keywords or built-in packages and their classes, methods/functions, and variables.

It might also be a good idea to have another directory "news" for containing version change information, along the lines of HELP *NEWS, PLOGHELP *NEWS etc.


[2] Ved originally had no styling information at all - just plain text formatting supported by simple conventions.  As far as I am concerned, that was a great idea and I would like to go back to that.

The idea I have is that there will be an automatic, dynamic conversion to HTML, since web browsers are likely to be the most commonly available viewer.  However, the source text will be plain UTF-8 supported by some very simple textual conventions for styling.

This would mean that help text could be prepared without the use of fancy editors, viewed in plain text, and searched using the familiar gamut of UNIX tools.

For example, cross-references to other topics could be of the form 
	category *topic/subtopic...
such as
	HELP *reverse
Familiar?

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.


[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.


-- 
Steve