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