Re: HTML documentation Ka-Ping Yee (ping@lfw.org)
Wed, 2 Dec 1998 01:31:09 -0800 (PST)

On Tue, 1 Dec 1998, Mark S. Miller wrote:

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

[+] Cool! Glad you like it.
The scope diagram is a somewhat elaborate table. It should render fine in any browser that can do tables with cell background colours (Netscape 3 and up; IE 3 and up). In Netscape 2, which can do tables but not cell backgrounds, the code in the diagram should appear fine but the scope shading would not be visible.

Although the HTML is much more complex for this bit of voodoo than a simple image, it happens to have the advantage that the code in the diagram is readable in Lynx (though the scope shading is not visible), and because the text is "real" it can be selected, pasted, and Critted.

Hmm... i was afraid that Critting the diagram would mess up its table formatting, but actually it seems to hold up fairly well. See:

http://crit.org/http://crit.org/~ping/e-forloop.html

Not that i can really see a dire and frequent need to Crit such a diagram -- but anyway...

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

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

> [%] Oh.

[?] What Criticon is that? A mark of exasperation? :)

> >[] 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?

[-] Two reasons why HTML alone is insufficient. The first reason you provide yourself: you can't edit and maintain inline diagrams in HTML with any convenience.

The second is more fundamental, and has been a long-standing beef with HTML for me all along. HTML is too low-level. Even if you work around the issue of tedious hand-editing by using some fancy Web page editor, you still cannot get around the lack of semantic information in HTML. To generate any half-decent looking documents with any degree of ease, you *must* have a stylesheet or macro facility of some kind. Because browsers *still* don't support stylesheets for the most part, we're forced to implement some sort of macro expansion mechanism and use something else as the source format, with HTML as the expanded output format.

It is kind of surprising to me that in all these years and hundreds of thousands of pages of frenzied authoring that no one has really come up with a decent Unix-based tool for doing this. There are some contenders (Python's HTMLgen, php, various Perl hacks, pop!site for Windows) but none are quick and convenient enough to use to have wiped out the use of vi on plain HTML -- which is really a shame. (Note huge product opportunity here. Can't believe this vacuum has lasted so long.)

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

[+] This is a perfect example of the semantic issue. We are crying out for a macro language here.

I have tried several of the above solutions myself, as well as other more unconventional ones (like cpp and m4) without huge success. This is why i'm thinking of creating a converter that will do this stuff right for the E documentation.

But now we come back to your requirement that diagrams be easy to edit inline -- which restricts us to Frame as the main editor. And that is why i asked about the openness of the FrameMaker document storage format.

> 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. What you are describing sounds like it could be more work (three interacting processes instead of one). The conversion and its parameters introduce an unknown element into the pipeline, making it tougher to predict what comes out. There also might not be enough information left in the HTML output to tweak. 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.

!ping