[plt-dev] Re: doc searches

From: Eli Barzilay (eli at barzilay.org)
Date: Sun Jun 7 13:07:45 EDT 2009

[Note: moved to plt-dev, since this is off-topic for the general

On Jun  7, Henk Boom wrote:
> 2009/6/7 Eli Barzilay <eli at barzilay.org>:
> > On Jun  7, Henk Boom wrote:
> >>
> >> Why not keep only the identifier and module names in the main index,
> >> then when the user clicks on the link get the html information from
> >> a .js file based on a hash of the name? Just from looking at the
> >> index file it seems that this would shrink it quite a bit.
> >
> > * Note that as soon as you stop typing, it starts a search, and to
> >  display the results it will need the rest of the information.  (You
> >  could argue for changing that interface though, and make it require
> >  clicking some search button or hitting enter -- but see below.)
> >
> > * If the hashes are good, it means that results will be distributed
> >  nicely over all sub-files, which means that an average batch of
> >  results will hit all of them, so you'll end up loading all data
> >  anyway, and possibly slower, since it'll neead to read a file, and
> >  merge the data into the main index vector, with all the accounting
> >  that it implies.
> >
> > * Another problem is what I mentioned earlier -- it requires runtime
> >  loading of files, which can be a pain when used with local pages.
> >
> > * In addition, there are additional bits of information that are
> >  needed:
> >  - What's the type of the entry (eg, you can use `M:' to search only
> >    for bindings)?
> >  - Which module is it coming from (the full version of that operator
> >    is `M:<module>' to restrict searches only for bindings in matching
> >    modules)?
> >  - Which manual is it coming from (the `T:' operator makes the search
> >    specific to a manual)?
> Ah, I see it's more complicated than I thought. I can reply to some
> of the points you bring up, but not all:

Well, I'm not trying to get into some flamewar over the details -- I'm
just listing the problems that I can expect or went through.  So yes,
some of these can be addressed, in some way that is bad to some
degree, but that doesn't help with actually getting a solution.

> Why does it need the rest of the information to display the results?
> If you only fetch the URL when the user clicks the link it seems
> that only the name and the module are needed for display. This means
> that typically you would need only to load a single one of the hash
> .js files.

Loading on a click is worse that what I thought you suggested.  It
means that the link cannot point to the right manual which means that
you can't see in your browser's status line where it will take you
(that's something that I consider pretty rude...).  But ignoring that,
it means that at the moment when the link is clicked, the code should
retrieve the file to know where to jump to -- which will delay the
action, and in some cases it will just appear that the page is not
working at all.

In addition to that you run into a bunch of problems at the low-level
that the browser should really take care of.  For example, you can
just make the browser jump to a page -- you need to check the ctrl and
shift status to know if the user wanted a new window or tab, taking
into consideration the different interfaces in different browsers, and
ignoring browsers that might be user-customized (which will just have
to face the fact that the plt pages behave like we want them to,
ignoring what you like), and assuming that there *is* a way to open a
new tab or a new window reliable (probably not, since it's rare to see
a browser without some popup blocker these days).

You also need to deal gracefully with failures -- a second click
before the index is retrieved should be ignored *unless* enough time
has passed which means that we should give up on getting it.  (And
this is much more of a problem than it seems -- the first thing anyone
will do when a link doesn't respond is to immediately click it
repeatedly a few times.)

> If you include the module name and the manual name (perhaps by index)
> in the main .js file then M: and T: should work fine as far as I can
> tell.

That's already most of the data.

          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
                  http://www.barzilay.org/                 Maze is Life!

Posted on the dev mailing list.