Searching the Docs in Workbench

Is there a way to direct Workbench to reference the adv3Lite docs in its “Search User’s Manuals” field (in the top toolbar)?

I’ve tried uninstalling, reinstalling, copying the adv3Lite docs folder into the TADS 3 program directory, renaming it ‘doc’ (which is the name for the adv3 docs folder), and then searching for an item (I’ve been trying a search for hiddenIn, which I’m pretty sure is a term in adv3Lite but not in adv3). To quote the Rolling Stones, “Nothin’ I try don’t seem to work.” For a while I had Workbench crashing on me when it tried to search. Another uninstall/reinstall has fixed that, but I’m back where I started – the search function accesses adv3 docs, not adv3Lite docs.

Very possibly I’m overlooking something obvious. Or maybe what I’m trying can’t be done. Suggestions?

There’s no way I know of getting Workbench to search the adv3Lite docs. I couldn’t even persuade Workbench to open them to view in its help pane. Windows 7 defeated me with its Program Files gotcha - basically Windows won’t let you change any files in a Program Files folder, although it makes it appear that you have changed them. For this reason copying adv3lite docs to your TADS 3 program directory would be a bad idea under Windows.

In short, I doubt this is possible without changes to Workbench.

That’s a good explanation … except that I always install T3 to my root C: directory, not to Program Files.

I haven’t tried using a shortcut. Maybe I’ll try turning index.htm into a shortcut that redirects to the adv3Lite index.

[Edit:] Wow, even that doesn’t work. It still opens up the index for TADS 3, even after I’ve renamed my shortcut index.htm and given the T3 index a spurious name.

A couple of days back I tried editing the TADS 3 index.htm file to add a link to the adv3Lite docs. That didn’t work either. At least it worked fine if I opened the TADS 3 index.htm in a browser, but not if I tried to look at the docs from within Workbench, where I just saw the original unedited version of index.htm.

Yes, it can be done.

It’s relatively easy, except if you installed the Workbench in Program Files (x86), which I believe is the default location (and therefore the most likely place on most user’s systems; at any rate, it’s where mine is). Having to deal with Windows’ security measures requires jumping through a few hoops in order to write to the TADS system files. Otherwise, it’s just a matter of adding an href to the Workbench’s documentation index files.

The file that writes the Bookshelf (the page that appears when you click User Manual on the Help Menu) is named indexwb.htm (not index.htm, I assume wb is for Workbench) and it’s located in the C:/Program Files (x86)/TADS3/docs folder.

Or, you can add a link to the list of help topics displayed when you click the Workbench Help menu item. That file is named WBCONT.HTM and it’s located in the TADS3/doc/wb folder.

If the Workbench is installed under Program Files, it is probably easiest to copy these files out to a temp location, make your edits, then copy them back to the folder under Program Files. Otherwise, Windows will demand that you grant administrative permission each time you try to write to the file, and at least some editor programs will flat out refuse to write to the file while the Workbench is running. (I use Notepad++ and I run into that problem, although I believe I have used vim in the past without running into the problem. YMMV.)

Another complication when Workbench is in Program Files is a Windows security measure. You cannot link to a document that is not within the TADS3 file system under Program Files. Windows will insist that all links start from C:\Program Files…. That means that if your Adv3Lite library files are in some other location (I keep mine in D:\dev\TADS…), you won’t be able to point an href at the documentation files in that location. You will have to create a directory within the TADS file system and copy your Adv3Lite documentation to that location, then add a relative link to the Workbench files (relative to the location of the Workbench file you are editing).

I added an adv3Lite/docs folder to the TADS/lib/extensions folder in Program Files (x86) and then use this link in the Workbench files:

Actually, on the Bookshelf page, I copied the entire reference to the first book on the list, then changed all the URLS (two to the book, one to an image file) as follows…

[code]


Adv3Lite Documentation Index

Bookshelf for Adv3Lite documentation.

[/code]

Now, when I click on the User Manual item on the help menu, the Adv3 Bookshelf starts with a link to the Adv3Lite Bookshelf.

Jerry

Thanks, Jerry. Creating a shortcut to the adv3Lite index.htm file doesn’t seem to work. What does work is copying that file, pasting it into the TADS/doc folder, renaming it indexwb.htm, and then editing it in a text editor to add …/adv3lite_doc/ to each and every relative link in the file. The brown and blue book covers in the Toolbar still open the T3/adv3 books, but the magenta one opens the adv3Lite documentation.

I got interested in this because I’m thinking of doing a Workbench tutorial video. At this point, though, I think that method may be more than I want to get into. “Create a shortcut to index.htm on your desktop” seems like a much simpler thing to recommend.

It does on my system.

I added the link as noted in my previous post, and the link points to the Lite Bookshelf, all images are in place, and all links work.

I don’t think you’re going to be able to do much with the buttons on the toolbar, or the specific doc links on the Help menu, unless you want to totally scrap the default Adv3 documentation. I played around with it some more, trying some html and javascript redirects, and neither worked.

If that’s what you’re going for—total replacement of the existing docs with the new Lite docset—then you’ll need to put the Lite docs into the folders created for the default docs. There may be some issues with naming conventions, though; the default Adv3 docs use html while the Lite docs use htm as filename extensions.

But IMHO that’s a deeper dive than is either warranted or wise. The Adv3 docs should remain in place; the Lite docs, like the Lite library, are additions to the TADS3 tool chest.

What I did simply adds Adv3Lite links to the existing Adv3 Bookshelf and Docs Contents pages.

Jerry

For the record, it’s not that hard to change the permissions of a directory in Program Files to avoid requiring admin privileges, either from the command line with icacls (which used to be cacls) or from the Explorer GUI. I’ve done this before (with T3 even) to get around some issues of running a program as non-admin.

Armed with Jerry’s tip that the file that needs to be changed was indexwb.htm rather than index.htm, I managed to get the adv3Lite documentation up in Workbench quite easily.

My approach was to right-click on Notepad++ in my start menu and select “Run as adminstrator”. This allowed me to edit files in the TADS 3 program directory without any further fuss. I then inserted the following into indexwb.htm immediately before the tag that’s just above the Change Logs headings:


<tr>
<td class=bookimg>
<a href="file:///C:/Users/Eric/Documents/TADS%203/extensions/adv3Lite/docs/index.htm">
<img class=book src="file:///C:/Users/Eric/Documents/TADS%203/extensions/adv3Lite/docs/manual/mancover.jpg">
</a>

<td>
<a href="file:///C:/Users/Eric/Documents/TADS%203/extensions/adv3Lite/docs/index.htm" class="title">
Adv3Lite Bookshelf
</a>
<br>by Eric Eve
 
<p>This is the documentation for the alternative adv3Lite
Library.

I didn’t experience any problem with linking from the TADS 3 program directory (under Program Files (x86)) to the location of the adv3Lite docs under Documents. On opening Workbench I can now see AdvLite Bookshelf added as an option from the main docs page as expected, and I can click on the links in Workbench and open the adv3Lite docs from there.

P.S. But this still doesn’t allow you to search the adv3Lite docs in Workbench, which was Jim’s original concern.

I still find it difficult to edit files in Program Files directories. When I try to save the file back, I get told the file is open in some other application, even after I shut Workbench down. The easiest thing for me is to save to temp then manually copy the file back to Prograqm Files. If I find I’m doing it a lot as I edit the file, I create a .bat file to do the copying.

Well, yeah. Me to. Don’t know what I did before, fat fingered a URL, I guess. But now it does work. So hooray.

True, but you can’t search the lite docs when they aren’t in Workbench, either, so there’s still an upside to doing this.

Speaking of which (upside, I mean), perhaps I got carried away, but after doing all the work to figure it out I didn’t want it to fade away in the mists of time, so I wrote up what I did and a) generated a PDF with pictures and everything and b) posted it in the TADS Wiki at http://tads3.gerynarsabode.org/index.php?title=Adding_Adv3Lite_Documentation_to_Workbench

http://www.electraink.com/if/docs/adding_links_to_workbench.pdf
http://tads3.gerynarsabode.org/index.php?title=Adding_Adv3Lite_Documentation_to_Workbench

Jerry

Way cool, Jerry. Thanks!