HTML documentation

[Mark S. Miller]

At 02:33 AM 12/1/98 , Ka-Ping Yee wrote:
>[] An example of a revised page: http://crit.org/~ping/e-forloop.html.
>I'll explain what i did to it, as compared to the original page at
>http://erights.org/doc/elang/web/control.e.html.

[+] Ping, I love your alternate page.  
The non-graphic scope diagram is pure magic!  How does it work?  Is it
really browser independent?

One suggested wording change: "In the case of a List, the keys are
integers" should be "In the case of a List, the keys are the indices".


>... The drawback is that it won't show up in
>a printout.  (But perhaps that's what the PDF should be for...)

[-] If we keep frame/pdf.  More below


>I removed the parenthetical comment "(In Perl, it's called foreach.)".
>In Larry Wall's time-honoured tradition of multiple ways to do things,
>Perl accepts both "for" and "foreach" as synonyms.  (I think this is
>horrible.)

[%] Oh.


>I hope you find, as i do, that the page is pleasant to read when
>formatted this way.  It would be great if we could get all the
>documentation to come out this nicely.

[+] I love it.


>[] Does Frame store its documents in an open format?  If we still
>want to use Frame as the source format, then perhaps we can put
>together our own converter and stick to simple conventions in
>Frame that our converter can understand.

[+] It does, but why bother?  

Frame vs Wysiwyg Html:
I'd much rather do wysiwyg html editing if it can be made pleasant enough.
The wysiwyg html editor I use, VisualPage form Symantec, is pretty good,
but I don't know how well it would do on your magic scope diagram.  It does
show it as a complex arrangement of table cells -- jeez, I see how you did
it! -- but What You See in visual-page is not What You Get in internet
explorer.

How well do you think you can render the fundamental diagram in portable
html?  ;)  In all seriousness, the big hangup is the insertion and
maintenance of lots of little MacDraw-like diagrams.  Microsoft Word is the
only other html editor that I know of that has its own built-in drawing
program, but this drawing program falls just below tolerable, and Word's
html isn't wysiwyg.  I could deal with a separate drawing program I had up
alongside my editor iff it let me edit many small drawings in one session,
and let me output generated gif images of them all to separately hand-named
gif files.

Another normal html pain that Frame made pleasant was the automatic
generation of [Previous][Contents][Next] links on each page.  This feature
alone has me tempted to suck the other chapters into Frame.  So, getting
back to your original question...

Frame's open format is called "mif" (Maker Interchange Format), and I seem
to recall it was well defined, well documented, and easily machine
understandable.  We actually did some automatic mif generation in a
javadoc-like tool at Xanadu.  (We also generated emacs info & hypercard,
all from the same sources.)  

Converting mif to html ourselves, though, is a lot of work, and there are
already four commercial products (counting Frame's own converter) with
varying degrees of parameterizability.  So if we stick with Frame, I think
we're better off tweaking the document, the conversion parameters, and the
html output.  Ping, do you know anything about writing automatic
html-to-html transformers?  ;)

Btw, I wouldn't have any problem with these transformers being in E, since
this wouldn't create a cyclic build dependency.

	Cheers,
	--MarkM