Since I have received several similar suggestion, mainly
related to formatting of the above document, I decided
to post my reponse publicly. Sorry for the noise.
Firstly, about the robots and the strange URL I posted.
I am not paranoic, just experienced. Our Haskell directory
has been already indexed anyway, but this document
is fresh and I would like to keep it sort of anonymous
for a time being. See below.
> You could use the robots exclusion standard to achieve this.
Some robots ignore "robots.txt", especially those without
symbolic names (with numerical IPs only); some would
even take over my (slow) server for hours a time - and going
where they are not invited at all. Blindly copying..
I could place the page with keys in a publicly accessible
directory but restrict access to files with text proper -
thus eliminating indexing noise and random ways of accessing
this document. Good robots would respect this, but bad ones
would not care.
I worry about noise because documents like this one have
by their nature plenty of possible keywords for indexing.
Although comparing people's intents with the result of their
search (referer logs vs. access logs) is sometimes
quite joyful but I do not care for random users at all.
But I care for Haskell users, of course.
I still do not have clear idea about the future of
this document and thus I am trying to keep very low
profile for now. The options are: abandon, continue more
or less as is, change the format, move it to Wiki,
move it to haskel.org, etc. Your input is really needed,
because - short of the option 1 - the stuff will be soon
indexed anyway.
> Some immediate comments: it's generally easier to read documents set
> in a narrower measure, so for this sort of thing, if you want to use
> frames, it would be better to split the page vertically with most of
> the width for the text. This is a bit clumsy for the contents, but
> one typically spends less time reading that.
Frames are the easiest to implement since they do not need any
special support from JavaScript or Java.
With the former I could implement some fancy features, such
as buttons instead of plain links to help the user with
navigation ("this button pressed - you are here!").
But I do not dare to use it at the moment because
I have seen so many broken scripts due to all sorts of
incompatibilities among browsers and versions of JavaScript.
I'd rather not use Java -- at least for a moment.
Visualization of the contents seems to me of the primary
importance. Grouping some related items, but not those in the
parent-child relation, on one horizontal line looks also as a good
idea. Having enough space for code exmples printed in fixed
font supports this choice too. Managing screen estate
by choice of very short keywords puts extra restraint and
reduces readability. These were the reasons why I have chosen
the horizontal split this time.
But I will think about how to accomodate those with
different "endianess" preferences. :-)
> Making the frame [width/hight] adjustable would be a help, too.
I played with this idea too, but my Netscape browser seemed
to ignore the hints. I forgot that reloading the page with
"frameset" definition would not do a job - for this I need
to retry it in a separate window. Now it works! I have updated
the hcompanion-frame.html file. But what I have read about it -
this might not work for MS Explorer. Sorry if this is a case and
let me know if this breaks the Explorer.
> Splitting the sections into smaller html parts would be a help too --
> over a phone line the types section takes a while to download, and if
> one only wants to read part of it, it would be nice to be able to save
> that time.
This is a very valid observation; I simply got carried away
with editing and one of the files is definitely too big!
I'll try to break the text into smaller chunks -
each grouping entries belonging to the same major section.
But be aware that some definitions are reused in different
places and I do not guarantee that entries in a single file
will be organized in some logical hierarchy.
>
> Another thing that would be helpful would be a link from each section
> to the next and back.
A lot of typing, but I will try to add it too.
Thanks for your input so far.
Jan
