Adding your own Help
- To: mathgroup at smc.vnet.net
- Subject: [mg47645] Adding your own Help
- From: "DrBob" <drbob at bigfoot.com>
- Date: Tue, 20 Apr 2004 03:18:49 -0400 (EDT)
- Sender: owner-wri-mathgroup at wolfram.com
For any who are interested, I've puzzled out some of the mysteries of
building my own Help entries, and I'll use this to illustrate what Wolfram
Help files SHOULD say but usually don't. I don't have all of it figured out,
but this takes care of the majority of what you need. Built-in Help is
little more than an annoying distraction by comparison.
Here's a step-by-step method for adding your own help to the Browser.
1) Put your material in a notebook such as
$BaseDirectory\Applications\xxx\Documentation\English\yyy.nb
I used xxx=yyy=DrBob. "yyy" will appear in the left-most Help Browser column
under Add-ons & Links.
2) yyy.nb must be outlined using Title, Section, and Subsection cells so
that the cell directly after a Title is always a Section or other Title, the
cell directly after a Section is always a Subsection or other Section, et
cetera. Otherwise you get an annoying error-message. I recommend putting a
Section cell after every Title and Subsection after every Section even if
you don't seem to need them in the outline; you WILL need them for building
keywords entries.
See step 3 if you want to use other styles instead.
3) Open the OpenAuthorTools palette from the File>Palette menu item. On this
palette, click MakeCategories to bring up another palette. On that palette,
click SelectedCellStyles if you want to change the outline styles. You can
use only three such styles, because the browser allows only four panes.
4) Make sure yyy.nb is selected, save it, and click MakeBrowserCategories,
which creates NewBrowserCategories.m in the same directory as your yyy.nb
file. Rename it, removing "New" from the file name. Open it and you'll see
how that Titles, Sections, and Subsections have been mapped into
BrowserCategory and Item objects. The CopyTag values have been added as cell
tags in yyy.nb, so save that file again.
5) Stare at BrowserCategories.m awhile and you should notice that
BrowserCategory is used for a Title or Section if and only if there are
lower level Section or Subsection cells below it in the outline. The
difference is important (though it shouldn't be). We'll easily create
hyperlinks to Item entries, but not to BrowserCategory entries.
6) Click on Help>Rebuild Help Index, and find your help files, looking for
xxx in the left column under Add-ons & Links.
IF YOU WANT TO BE ABLE TO HIGHLIGHT A KEYWORD AND PRESS THE HELP KEY
(WINDOWS F1) TO FIND ONE OF YOUR HELP TOPICS, READ ON. There are also steps
later on if you want to build hyperlinks to your material.
7) You're through with the MakeBrowser palette for now; you need the
MakeIndex palette instead. Open it by clicking on MakeIndex on the
OpenAuthorTools palette.
8) In yyy.nb, locate a cell you'd like to index with a keyword. This can not
correspond to a BrowserCategory in BrowserCategories.m. All other cells are
OK.
9) If the keyword you want appears in the cell (often true), then highlight
that word or phrase and click IndexCellOnSelection in the MakeIndex palette.
If it doesn't appear in the cell, you can push EditNotebookIndex instead,
but you may as well put the keyword in the cell, use the first method, and
then delete the keyword if you don't want it in the cell. EditNotebookIndex
is useful for removing tags, but otherwise you don't need it.
10) Add as many keywords as you want to each cell, one at a time. Add
keywords to as many cells as you want, also.
11) When that's done, click SetIndexFileName on the palette and change the
name to BrowserIndex.nb (rather than Index.nb). This avoids having to delete
the old BrowserIndex.nb if any and rename Index.nb to BrowserIndex.nb.
12) Click MakeBrowserIndex on the palette. This creates BrowserIndex.nb and
opens it. If you get error messages, it's probably because you broke the
rule in step 2. Now you'll see hyperlinks to your material. Any of these
cells can be copied to other notebooks, if you want to include such a
hyperlink -- but don't do that until you're done with yyy.nb, because as the
material changes so do the IndexTag values next time you run
MakeBrowserCategories. Later I'll show another way to create hyperlinks, but
the same caveat still applies. To see the structure of a hyperlink, select
the cell and use Format>Show Expression (or Windows Ctl-Shift-E) and you'll
see that the IndexTag value from BrowserCategories has been embedded in the
hyperlink.
13) Close both files and run Rebuild Help Index. Now if you type one of your
keywords, highlight it, and push F1, you should see the corresponding entry.
If some of your keywords are the same as built-in keywords, that's fine too;
you'll see links to your entries AND Wolfram's.
IF YOU WANT TO BUILD HYPERLINKS TO YOUR MATERIAL, READ ON.
14) The menu's Input>Create Hyperlink might be usable, but here's a useful
function...
makeHyper[keyword_String, indexTag_String] :=
CellPrint@Cell[TextData[ButtonBox[keyword,
ButtonData :> indexTag, ButtonStyle -> "AddOnsLink"]], "Text"]
To use this, locate an Item in BrowserCategories.m and find the IndexTag
there. "keyword" can be whatever text string you want to see when you look
at the link. This link will lead to the Title, Section, or Subsection cell
corresponding to the Item identified by the IndexTag. I haven't figured out
(so far) how to easily link to a cell farther down in the yyy.nb outline.
As mentioned before, IndexTag values can change next time you run
MakeBrowserCategories, and that can break hyperlinks if you're not careful.
That's it for now.
Dr. Bobby R. Treat
www.eclecticdreams.net
StringReplace["lAWyerbillAtsmallfoot.com"//ToLowerCase,Rule@@@Reverse/@ToLow
erCase//@{{"dR","lAwyer"},{"@","AT"},{"bIg","small"},{"bOb","bill"}}]