? on 1-letter search in WebHelp

Please post all questions on Help+Manual 8 here

Moderators: Alexander Halser, Tim Green

Post Reply
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

? on 1-letter search in WebHelp

Unread post by Dave Gehman »

*sigh* I promised I would ask the following:

We have a function named "R" in our software. Yes, that's it, just R.

Can the WebHelp search function find topics in our online help that contains this "R"?

I just tried the search and got this: "The following word(s) are in the skip word list and have been omitted from your search: "r".
No results found."

I thought that maybe searching on a single letter would be problematic...
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: ? on 1-letter search in WebHelp

Unread post by Tim Green »

I thought that maybe searching on a single letter would be problematic...
You thought correctly. Online search of multiple web pages can never actually search the actual pages when you initiate the search. That is impossible. Instead, an "index" of all words in the pages and their positions in the pages is created in advance. (That is what Google does as well.) In Help+Manual this is created from the files in your WebHelp output folder, directly after you publish your WebHelp. The index is contained in several files with names starting with "zoom..".

When you perform the search, the index is checked for whether the sequence of letters you enter occurs -- not only as words but also within words. If you reduce the minimum word length to 1 letter, Zoom will have to index every occurrence of every letter in the alphabet in your entire project, and then include all that information in the search index. No. Just. Don't. Do. That. 8)
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: ? on 1-letter search in WebHelp

Unread post by Dave Gehman »

I have played with it, and found that if I put modifiers in the keyword for a topic, I can search on the modified string. For example:

Big R
R function
R object
... other permutations

While I haven't looked in your documentation, do you know offhand if there is a way to attach a tooltip to the WebHelp search input?

Asking because our development group is using R ("Big R") to hold just about every blinking thing they have to concoct because JavaScript doesn't have a way of doing this or that. It has 8 functions today and grows with each code build... and code builds are on average once a week*...

As a result, everyone will be searching on it, and I'd like at least a tooltip that says "For R, enter 'big r'"

*It's a 3-year old baby and experiencing a huge growth spurt...
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: ? on 1-letter search in WebHelp

Unread post by Tim Green »

do you know offhand if there is a way to attach a tooltip to the WebHelp search input?
That depends what you mean exactly. If you just want a standard tooltip for the search field that would be easy to achieve. You'd just need to add a title tag to the corresponding input field -- all I'd need for that would be the name of the skin you're using.

That being said, I'd tend more towards refactoring to use at least three characters for your namespace, if possible. A single-character namespace is bound to be problematic. Frameworks like jQuery can get away with it because the $ is the namespace of the entire system, and thus never needs to be searched on its own. :?
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: ? on 1-letter search in WebHelp

Unread post by Dave Gehman »

Tim Green wrote: Mon Sep 28, 2020 1:42 pm That depends what you mean exactly. If you just want a standard tooltip for the search field that would be easy to achieve....-- all I'd need for that would be the name of the skin you're using.
WebHelp_SlateGrey.hmskin
That being said, I'd tend more towards refactoring to use at least three characters for your namespace, if possible.
OK, I had to look up 'namespace.' Do you mean rename our function bucket , in this case, "R" ? I'll propose it, but first I need to find my crash helmet. :lol:
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: ? on 1-letter search in WebHelp

Unread post by Tim Green »

Dave Gehman wrote: Mon Sep 28, 2020 2:16 pm Do you mean rename our function bucket , in this case, "R" ? I'll propose it, but first I need to find my crash helmet. :lol:
Yes, because it forces you to look for a one-letter word in the documentation, and that will always be problematic. If you ask a programmer they will immediately understand why it's a problem. I would definitely check that first because it would be the best solution here. Instructing people how to look for a single letter is a kludge, and it still leaves you with an unnecessarily bloated search index.
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Tim Frost
Posts: 319
Joined: Mon Nov 22, 2004 11:45 pm

Re: ? on 1-letter search in WebHelp

Unread post by Tim Frost »

Have you thought about using the keyword index to find all the references to "R/this" and "R/that"? I have tried to educate our users (and my colleagues) to always try the keyword index first, and only use the full-text search as a last resort for things that are obscure and which may only show up on a full-text search. By definition, this second category would exclude your single-word texts.

It may be too much work for you to implement if you have not been building it up as you go along, but H&M makes it reasonably straightforward to maintain the keyword index in the topic keyword and anchor keyword dialogs. I try make a habit of never using a keyword alone, so your entries would always need to be:

R
this

R
that

R
the other

Our users, once they get the idea, also find it so much quicker to use than having a search which returns a dozen or more occurrences, often with the searched word buried (even if bold) in the returned text. It's like going to the well-organised index at the end of a book instead of having to search all the pages for the occurrences which are relevant.

[ how can I indent the sub-index entries here?]
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: ? on 1-letter search in WebHelp

Unread post by Martin Wynne »

Tim Frost wrote: Mon Sep 28, 2020 4:38 pmHave you thought about using the keyword index to find all the references to "R/this" and "R/that"? I have tried to educate our users (and my colleagues) to always try the keyword index first, and only use the full-text search as a last resort
Hi Tim,

Bang on. I've been telling my users to treat the Index as the primary resource for years, and ideally ignore Search entirely. If someone needs to use Search, I regard it as a failure of my indexing.

The trick is to rename it from "Keyword Index" to A-Z Index. Then they all know exactly what it is, how to use it, and many actually prefer it to searching. It can be renamed in the TOC templates.

There's a problem with the responsive skins that you can't scroll to and fro through the entire index, which is why I prefer the older skins.

p.s. [ how can I indent the sub-index entries here?]

Insert a no-breaking space. Hold down ALT, and 0160 on the numeric pad. Then don't preview or edit your post, or will need to redo them:

R
 stuff
 other stuff

cheers,

Martin.
Tim Frost
Posts: 319
Joined: Mon Nov 22, 2004 11:45 pm

Re: ? on 1-letter search in WebHelp

Unread post by Tim Frost »

The trick is to rename it from "Keyword Index" to A-Z Index.
Thanks for reminding me; since switching our context-sensitive help to Ewriter ours has accidentally reverted to 'keyword'.

And for emphasising the importance of an index: in the wider world one hears of it being the only thing some people read, for example in an autobiography.
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: ? on 1-letter search in WebHelp

Unread post by Tim Green »

There's a problem with the responsive skins that you can't scroll to and fro through the entire index, which is why I prefer the older skins.
That's an interesting point that hasn't come up yet -- we haven't had any feedback on it at all. I'll look into making this a selectable option. What we could do is make it a full list on desktop browsers but keep the current dynamically-generated list on mobile devices.
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: ? on 1-letter search in WebHelp

Unread post by Dave Gehman »

Thanks, all. I'm digging into the Index-as-real-Index idea, which is very promising.
Post Reply