HTML documentation

[Mark S. Miller]

At 01:31 AM 12/2/98 , Ka-Ping Yee wrote:
>[+] Better wording looks good.  Have a look at the page again; i
>have revised it a little more, and re-revised the second page too.

[+] Looks good.  Some further suggestions:

The new collection terminology is EList, ConstList, FlexList, EMap,
ConstMap, and FlexMap.  Wherever you say "List", you should probably say
either "EList" or "list".

I like Bill's suggestion that "average" protect itself from a misbehaving
alleged list (much like asynchAnd protects itself from a misbehaving
alleged boolean).  The one way bad supposed list behavior could screw us up
is to report a size inconsistent with the number of iterations.  Here's
defensive average function:

	? define average(samples) {
	>     define sum := 0
	>     define size := 0
	>     for value in samples {
	>         sum += value
	>         size += 1
	>     }
	>     sum / size
	> }

It's better code, but I don't know if it's a better example.  It probably
is a better example, since we are leading up to explaining secure
programming patterns.


>[-] Two reasons why HTML alone is insufficient.
>... you can't edit and
>maintain inline diagrams in HTML with any convenience.
>... To generate any half-decent looking
>documents with any degree of ease, you *must* have a stylesheet or
>macro facility of some kind. ...  (Note huge product opportunity here.
>Can't believe this vacuum has lasted so long.)
>
>> ... automatic
>> generation of [Previous][Contents][Next] links on each page. ...
>
>[+] This is a perfect example of the semantic issue.  We are
>crying out for a macro language here. ... creating a converter that
>will do this stuff right for the E documentation.
>... requirement that diagrams be easy
>to edit inline 
>
>> So if we stick with Frame, I think
>> we're better off tweaking the document, the conversion parameters, and 
>> the html output.
>
>[-] I'm not so sure.  ...


[-] Do something easy and adequate for now.  Do it right in E later.

FrameMaker is a good piece of software, done well.  Adobe seems to have
done a good job on several pieces of software.  Neither they nor three
other commercial products has been able to convert Frame to HTML well.  One
suspects that it might be a hard problem, or at least a lot of work.  If we
built a decent such tool, what would it look like?  Well, it'd probably
have a bunch of tweakable conversion parameters.  Once we built the tool,
*we* would use it largely by tweaking the document and the conversion
parameters, so why not use their tools the same way?  I can't imagine how a
from-scratch converter could take you less than six month just to get to
the level of bad functionality provided by the other four products.

Java's Swing does contain an HTML editing widget, which I believe supports
arbitrary other widgets embedded in the text.  There must be MacDraw-like
editors-as-Swing-widgets by now, or will be shortly.  Assuming these can be
embedded in the HTML editor, and that the resulting document can be saved
in two forms: preserving the structured graphics vs converting to gif.
Then Javasoft has already done most of the work of creating the wysiwyg
editor we need.  <fingersCrossed>All</fingersCrossed> we would need to do
is write some E code to tie it all together, and we'll have the html-based
successor to Elmer.  I'm not saying this isn't a lot of work -- I'm sure it
is -- it's just that the work will invested in the right place: E.


>Do you use a style sheet in Frame to semantically tag
>the text for formatting?  (e.g. code, keyword, parameter, etc.)
>This information would be very useful to a conversion program.

[+] Yes it does, and quite well too.  
I think what we most need (of things we can afford to build) is a set of
Frame paragraph and character styles built for the purpose of 1)
representing the semantic (and formatting) distinctions needed by E
documentation, and 2) being convertable to html in as close to wysiwyg as
we can get.

Do you have Frame?  If not, could you list a set of styles where each has

a) an identifier as a name
b) semantics / usage recommendations
c) html tag to translate to.

I'll consider the standard html tags to be implicitly included, except for
those you wish to exclude.  If you do this, I'll try to create the
corresponding Frame styles.  The shorter you keep the overall list the better.

I'm going to ignore tables for the moment.  (All the tools supposedly
convert them, but I haven't tried yet.)

	Cheers,
	--MarkM