Re: WANTED: Design for documentation (Photoshop power users!)

[Robin Bannister]

Some thoughts on searching. 



Valentin Villenave wrote:
> the search function should show the results in the main "frame" 
> on the right, without making the tocframe disappear

The toc pane and the main pane are a coherent unit. 
The user refers to the toc to see  e.g.
- what part of the document the main pane is showing (the breadcrumbs) 
- if there are immediately relevant sections nearby. 
And after a navigation move, the toc provides confirmation of the move. 
(Exception: meta-infos [Contents] and [?] are not shown as being inline.)

If the toc pane can get disengaged, people will lose confidence in it. 
And those who don't realise it has become disengaged will be disoriented. 
So (without knowing the pros), definitely not. 


> a search box at the top of the tocframe 

This search box is too small for something realistic like, say
> VerticalAxisGroup #'minimum-Y-extent 
Anything big enough would be wasting valuable toc space. 

To do realistic searches you would use something else which, 
at the very least, would have a bigger box. 
But then you could use this for the simpler searches too. 
This (of course!) leads to what I hinted at in a previous post [1]:

The toc pane offers just a [search] link, no box. 
This takes you to a search page with a bigger box and some other features. 
It is an ordinary link; you can easily open it in another window if you like. 
And the cursor is already there in the box, so no extra clicks are needed. 

The search page is a separate file, e.g. in doc root. 
So it is easy to have variants, e.g. offer an offline version for the tarball. 



Sebastian Menge wrote:
> Another refinement
> Add "intitle:Manual" or "intitle:Reference" 
> to search only the manual or the reference. 

Well, you also get Manual beams in NR, or the big-page for IR. 

This got me wondering how far you could go with "inurl:". 
And then, instead of just wondering, I built a testrig to try it out. 
While playing around with this, I discovered inurl could match not just 
"learning" but "lilypond-learning", an important feature, 
but one which Google seems to imply doesn't exist. 

To make inurl searches completely unambiguous, you could embed some sort of 
codewords in the current urls. 
But with the above feature, you can get most things filtered correctly, 
except for NR, which (for historical reasons ?) has a very generic url. 
So I suggest (to ease path-filtered searching):

J
Rename NR root from "lilypond" to "lilypond-notation". 


The next suggestion would be for everything english to have .en. 
That would make filtering easier, but are there special categories of 
english which should be filtered differently?   e.g. 
- IR (never to be translated?)
- translation pending. 
And Google's "lr" (language restrict) might be more suitable. 


The testrig demonstrates how well/badly things work and documents these issues. 
So I have polished it up a bit and attached it to this post. 
It is OK with my IE6 on XP SP3; it might just work somewhere else too. 



The search results only resolve whole web pages. 
So you often need to start a search inside the page to find what Google found. 
I prefer a fast scroll through the cached version looking for highlighting. 
But I can't do this with the new docs: (in the full version) the page is 
right shifted and the scrollbar is disabled.


[1] http://lists.gnu.org/archive/html/lilypond-user/2008-10/pngwjlRMg29EL.png


Cheers,
Robin









LANGUAGE
 any
 en
 fr
 es
 de

OTHER OPTIONS
exclude pdf / big-page
            
stable     
development

SEARCH IN
everything
NR               
LM
IR
AU
Snippets
Snippet source 

FOR 


GO

Testbed for URL-filtered googling of the online docs

Select the filtering and enter your search terms.
The quotes are for phrases, and can be left empty.
Use the Escape key to discard all search terms.

The Enter key opens the search results in this window.
GO does that too, but you can also
- drag it onto an existing window / tab
- let it open in a new window / tab.

[context] 
[words in google] 
[words in urls]