On using regular expressions for searching documentation

The following was intended to be a post on the GitBook message board in support of a feature request for exporting to PDF or other formats. Exccept I couldn’t post it—see the next entry for details.)

Consider the Asterisk documention. The Asterisk core and the version 13 docs combined have nearly 364,000 words in over 1,300 individual HTML pages. Now I want to look for information on calls and logs.

Search for “call”: 3,100+ hits, including “automatically”, “callback”, “called”, “caller”, “callgroup”, “calling”, “dynamically”, “locally”, “parked_call”, “recall”, “typically” … you get the idea.

Search for “log”: 7,800 hits, including “analog”, “blog”, “cataloguing”, “dialog”, “logged in”, “logging”, “logic”, “terminology”, etc.

Wouldn’t it be nice if one could search the entire space on whole words only, and have those words be an AND search to distinguish it from a phrase consisting of “call<space>log”? For example:

SEARCH: WHOLE_WORD="call" AND WHOLE_WORD="log"

You can, with regular expressions. For example:

egrep '\bcall\b.*\blog\b' *

The “\b” is a regular expression construct that means “word must start with (or end with) with non-alphanumeric characters such as punctuation, or be at the start or end of a line.” The “.*” bit means “any number of any characters, or no characters at all, can appear in this space.” The trailing “*” tells egrep to search all files in the current directory.

Running the above search on the Asterisk documentation described above returns the following results:

Assigning-Agents-to-Queues:
    The call to queue-success() gives some feedback to the agent as they log

Call-Event-Log-(CEL)-Driver-Modules:
    call event log might show that Alice called Bob, that Bob's phone rang for

Call-Identifier-Logging:
    generated by a thread with a call ID bound or to any log messages

ManagerAction_Events:
    system,call,log,... - To select which flags events should have to

Some-Standard-AMI-Headers:
    Privilege: <privilege> – AMI authorization class (system, call, log,

Skinny-call-logging:
    Calls are logged in the devices placed call log (directories->Place Calls)
    If a call is not placed to a channel they will not be recorded in the log.

Feedback to gitbook.com

I am EXTREMELY disappointed. I specifically registered an account here and spent over an hour formatting a post for the “PDF Export (and other formats?)” feature request, only to discover I couldn’t submit it.

Why? BECAUSE YOU’RE NOT HOSTING YOUR OWN MESSAGE BOARD! If I want that comment to appear, I have to create another account at a different site. This makes for a very bad user experience.

Not to menton that the tiny little dialogue box for this “message” thingy makes it difficult to review my input–and I can’t resize it. Frankly, some aspects of “modern web UX” are just terrible.