[Date Prev] [Date Next] [Thread Prev] [Thread Next] Date Index Thread Index Search archive:
Date:Mon Sep 18 08:10:47 2003 
Subject:Re: help system - ideas wanted 
From:x 
Volume-ID:1030918.02 

Steve,

In message <bkaibi$263h$1@soapbox.cs.bham.ac.uk>, steve@watchfield.com 
writes
>Hi,
>
>[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.
>
>

I would use marked up text, either xml or xhtml. Providing a filter to 
remove the tags is straight-forward. Styling via a set of standard 
cascading style sheets (CSS) would then give you a specific look and 
feel.

I think it is preferable to mark text using an acceptable standard to 
say that a line is a heading, than to invent yet another proprietary 
approach based on arbitrary conventions.

If you wanted to, a few editor routines could automatically apply tags 
to the background rendered text using your chosen stylistic preference 
rules applied to the input.

Your editor would become slightly more complex, with a rendered model 
and a tagged model of the same text, but I think the approach is so 
worthwhile that I am looking at applying it to code editing and viewing. 
The benefits of including non-code elements, such as links to 
requirements in a requirements specification, into a tagged code file, 
outweighs the additional cost to the editor.

Existing text tools can be applied by stripping selected tags according 
to a rule set that defines the type of output, e.g. for my purposes, a 
"compileable" rule-set defines the transformations to produce code to 
submit to a compiler. The rule set can be written in XSLT.

It is a lot easier to retain the text in a tagged format, provided you 
chose a very prominent standard, and manipulate it to generate the 
content you want, on the fly, than to try to generate sophisticated 
structured content, on the fly, from a plain-text that follows arbitrary 
stylistic conventions.

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

If you tag the text, generating these overviews is also simplified.

Regards,
-- 
Jeff Best