HTML documentation

Ka-Ping Yee ping@lfw.org
Tue, 1 Dec 1998 02:33:16 -0800 (PST)


> >It's not bad, but i wonder what's up with Frame having this
> >recurring size inconsistency.  The first occurrences of things
> >seem to often be larger than later occurrences, whereas the
> >monospaced example text seems to come in random sizes.
> 
> [?] Where?
> Please point me at some examples.  Thanks.

[#] Well, see the table of contents for instance.  The first
page at http://www.erights.org/doc/elang/web/control.html has
the Chapter 1 heading larger than all the others.

Then in http://www.erights.org/doc/elang/web/control.1.html,
the first chapter, the subheading "Control Flow Expressions"
is larger than the other subheadings.

Oh, wait a second.  That's because "The for Loop", "Defining",
and "Inheritance by Delegation" are part of the figure image,
while "Control Flow Expressions" is not.  That's weird.

Spacing in the examples is inconsistent, as on the page
http://www.erights.org/doc/elang/web/control.7.html.  Ouch,
http://www.erights.org/doc/elang/web/control.f.html got
hurt in the translation as well.

> But in the "Quick Links" figure in
> http://www.erights.org/doc/elang/web/control.1.html Frame didn't generate a
> working image map for the embedded links, even though I think I followed
> the directions correctly.

That's true.  I wish it did!


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

So, first note that it is actually possible to accomplish your scope
diagrams in "pure HTML", with a little trickery: that first figure
is not a graphic.  I actually like the look of this a little better,
as the colours interfere less with reading the code, and nicely show
multiple levels of scope.  The drawback is that it won't show up in
a printout.  (But perhaps that's what the PDF should be for...)

I applied character formatting to the instances of keywords and
parameters in the figure that appeared in the paragraph, to make
them stand out.  I also changed "body-expression" to "body-expr"
to make it consistent with "collection-expr", and changed "value-patt"
to "value-pattern" to make it consistent with the text.

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

The first paragraph is split into two smaller chunks for easier
digestion.  A couple of sentences were rephrased to make them a
bit clearer.

I fixed the spacing of the example code to look more like what
you'd really see in the E shell.

The last paragraph has some wording changes also, and drops the
brief digression about the key-value variant of the "for" loop
since there's now a separate section describing it.  Mentions of
"Tuple" are updated to reflect the new naming convention for
collections.

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.


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



!ping