Spin`Algebra

HelpBuilder

© 2007 Yuri E. Kandrashkin

Installation

Find the installation directory

Evaluate the following cell to get user base directory on your system:

This gives the folders where the package can be placed.

Copy files to a selected directory

If previous version of HelpBuilder was installed remove its folder. Unpack and copy the directory HelpBuilder into Applications subdirectory of $BaseDirectory or $UserBaseDirectory.
This allows loading the package through its context name or short path:

Rebuild Help Index

Execute the menu command Help > Rebuild Help Index

This adds HelpBuilder help file in Help Browser.

spalg_1

Preparing Documentation for HelpBrowser

Mathematica provides the package AuthorTools` designated for building of different kind of documentation. HelpBuilder simplifies the part of this job, a conversion of files into Help Browser format. The creation of help documentation by HelpBuilder includes the following steps:
1. Creating a project file. It has the same structure as AuthorTools` project file so one can use an interactive dialog window MakeProject. There is one optional change. If the project file is placed in the same directory as files with documentation which is usually the case then it better to use option Directory"→ ". In this case the project directory will be determined from the directory of the project file so one doesn't need to edit the project file if its directory is changed.
2. Evaluating HelpBuilder["projectfile"] to execute the following tasks:
- Creating a new directory Documentation\English. If the directory Documentation exists it appends a number to the name of directory to make it unique.
- Copying all project files and all StyleSheets into created directory
- Converting CellTags from cells of selected style to TaggingRules. TaggingRules are used by AuthorTools`MakeIndex to make links to cells from the BrowserIndex.
The conversion is optional because the package AuthorTools` provides a tool for direct editing of TaggingRules. I prefer to use CellTags in original files for further indexing because of convenience of editing and clearer structure of notebooks.
- Paginating
- Making BrowserCategories
- Adding links to Contents and Index into BrowserCategories (optional).
- Generating a palette to make browser index and contents and set delimiters to browser categories.
3. Using HelpBuilder palette for the following tasks:
- Making Index file. I have changed the procedure of sorting because the Mathematica function Sort seems to have problems with non-ANSI characters, for example, it doesn't sort properly words written in Cyrillic alphabet.
- Generating a table of contents of a project. For some reason direct execution of this task from the HelpBuilder occasionally generates errors due to problems with Notebook cache.
- Launching SetDelimiters dialog window for visual editing of BrowserCategories delimiters.
4. Editing delimiters of BrowserCategories.
5. Copying the directory Documentation\English into directory Applications\ProjectName of $UserBaseDirectory
6. Rebuilding Help Index by menu command Help > Rebuild Help Index.

HelpBuilder Guide

Work with HelpBuilder

Strating with HelpBuilder

To start HelpBuilder get the corresponding package:

There are several ways of beginning the work with HelpBuilder. HelpBuilder["projectfile"] creates help browser documentation based on the list of files in "projectfile". HelpBuilder[] opens FileBrowse dialog to select the project file:

And finally HelpBuilder[MakeProject] calls the dialog window of AuthorTools`MakeProject to create a new project file (refer to section ">HelpBuilder project file)

HelpBuilder copies files and style sheets in directory Documentation/English.  If the directory Documentation exists, HelpBuilder creates directory Documentation0. If this directory is also exists HelpBuilder appends next number to directory name and so on. Thus the new directory to make help documentation is always unique.  

HelpBuilder automatically paginates the project notebooks and generates BrowserCategories.  The further tasks are evaluated interactively under user control. They include making the index and contents and inserting the delimiters in BrowserCategories. These commands are executed as functions of buttons of palette generated by HelpBrowser.

spalg_2

HelpBuilder Palette: Making Index and Contents

The last step of creation interactive help documentation includes three steps: making documentation contents and index and inserting separating lines (delimiters) in panel of documentation.

AuthorTools` function MakeIndex is used to make documentation index. It refers to TaggingRules which can be set within special palette Edit Notebook Index of AuthorTools`. HelpBuilder supports an additional ability to create TaggingRules from CellTags which seems to be more convenient because of advanced tools of Mathematica to work with CellTags.

BrowserIndex file has the following form:

    main,
         sub1
         sub2

where "main" is specifies a term in the index and "sub" is subentry.

MakeIndex occasionally could not find TaggingRules links thus this step is separated from previous tasks of HelpBuilder.

Making contents uses the AuthorTools` function MakeContents which work with the notebook cache and sensitive to changes in the notebook. This function works instable if it is executed within the body of HelpBuilder.

Button Set Delimiters calls the function SetDelimiters.

HelpBuilderOptions

HelpBuilder uses the functions AuthorTools` for all main steps except the editing of BrowserCategories delimiters. But there are extra tasks which might be useful. Their actions are controlled by corresponding options. All options of HelpBuilder are collected as the value of HelpBuilderOptions:

    HelpBuilderOptions -> {
        "CopyStyleSheets" -> Automatic,
        "IndexToBrowserCategory" -> True,
        "ContentsToBrowserCategory" -> True,
        "IndexStyleDefinitions" -> "HelpBrowser.nb",
        "TagsToTaggingRulesOptions" -> {
            "TagsToTaggingRules" -> True,
            "IndexedCells" -> All,
            "SubEntryDivider" -> ": "},
        "PaginateOptions" -> {},
        "MakeBrowserCategoriesOptions" -> {},
        "MakeContentsOptions" -> {},
        "MakeIndexOptions" -> {}}

To edit the values of options one can use function OptionsExplorer which is available from websites wolfram.com/library or spinalgebra.com.

HelpBuilderOptions controls the following actions:

• CopyStyleSheets copies notebooks with style sheets into directory with documentation. There are three possible values: True, False and Automatic (default). The value Automatic copies only style sheets which are not within Mathematica system files in directory SystemFiles/FrontEnd/StyleSheets/.

• IndexToBrowserCategory and ContentsToBrowserCategory determine if the corresponding files should be added into BrowserCategory and HelpBrowser panel.

• IndexStyleDefinitions sets the name of StyleSheet of Index file.

• TagsToTaggingRulesOptions is a set of rules used for conversion CellTags to TaggingRules which used for indexing cells to access via HelpBrowser search engine. For more information refer to AuthorTools Guide.

• TagsToTaggingRules determines the conversion of CellTags to TaggingRules

• IndexedCells defines styles of cells which CellTags are converted to TaggingRules

• SubEntryDivider sets a string separating the index entry and subentry. For example, by default cell tag "main: sub" is converted to entry "main" with subentry "sub".

• PaginateOptions, MakeBrowserCategoriesOptions, MakeContentsOptions and MakeIndexOptions used to enter options for AuthorTools` functions Paginate, MakeBrowserCategories, MakeContents and MakeIndex.

spalg_3

HelpBuilder project file

HelpBuilder needs a project file. It has the same form as a project file of AuthorTools`. A project file is a plain text file with a .m suffix. The file must include data in the following format.

{"Name" -> name,
"Directory" -> directory,
"Files" -> {nb1, nb2,...}}

Here name is the name of the project, directory is the full path name of the project directory, and {nb1, nb2,...} is a list of all notebooks that make up the project. If directory is replaced by HelpBuilder will use the directory of project file.

The command HelpBuilder[MakeProject] opens the dialog window of AuthorTools`MakeProject to create a new project file (refer to section HelpBuilder project file)

Using CellTags for BrowserIndex

CellTags as TaggingRules

HelpBuilder uses the package AuthorTools` to create help browser files. AuthorTools` uses the option TaggingRules to incorporate index links. HelpBuilder supports an additional ability to create TaggingRules from CellTags. This method seems to be more convenient because CellTags are typically used to refer to cells and because of  Mathematica FrontEnd has advanced tools to work with CellTags.

Option TagsToTaggingRulesOptions regulates the parameters of conversion CellTags to TaggingRules. It has sub-options:

• TagsToTaggingRules is True if CellTags would be transformed to TaggingRules and False otherwise

• IndexedCells is a set of styles of cells which will be examined for presence of CellTags. The value "IndexedCells"->{"Section","Text"} determines that only CellTags of cells with styles Section and Text would be transformed to TaggingRules. The default value "IndexedCells"->All checks all cells.

• SubEntryDivider sets a string separating the index term entry and subentry. With the default value is SubEntryDivider"->": cell with CellTags->{"main: sub1, main: sub2"} forms entry "main" with subentries "sub1" and "sub2" and the index file will look like

    main,
         sub1
         sub2

Editing CellTags

• To show all CellTags of a notebook select the command ShowCellTags of menu Find.

• To edit CellTags use keyboard shortcut [CTRL]-[J].

• To follow the tag use menu command Find > CellTags.

spalg_4

SetDelimiters

SetDelimiters["file"] opens "file" with BrowserCategory for interactive editing of its delimiters. SetDelimiters[] allows to choose a file via dialog menu. SetDelimiters dialog window has similar structure as HelpBrowser. The click on the title opens its substructure. Bold font is used to show the path of open sections:

The click on the button ⇔ inserts or removes the delimiter above the title. The edited BrowserCategory might be saved in the same file (button Save) or with a different name (button Save As). The button Cancel closes BrowserCategory unaltered. The button Help opens the SetDelimiters help file in HelpBrowser.

Reference Guide

spalg_5

HelpBuilder

• HelpBuilder["project"] loads file "project" and makes Help files
• HelpBuilder[] opens FileBrowse dialog window to load project file
• HelpBuilder[MakeProject] opens MakeProject dialog palette of the package AuthorTools` to create a new project file.

• HelpBuilder executes the following tasks:

- Creating a new directory Documentation\English. If the directory Documentation exists it appends a number to the name of directory to make it unique.
- Copying all project files and all Style Sheets into created directory
- Converting CellTags from cells of selected style to TaggingRules. TaggingRules are used by AuthorTools`MakeIndex to make links to cells from the BrowserIndex.
The conversion is optional because the package AuthorTools` provides a tool for direct editing of TaggingRules. I prefer to use CellTags in original files for further indexing because of convenience of editing and clearer structure of notebooks.
- Paginating
- Making BrowserCategories
- Adding links to Contents and Index into BrowserCategories (optional).
- Generating a palette to make browser index and contents and set delimiters to browser categories.

• HelpBuilder has an option HelpBuilderOptions with the list of possible options.

spalg_6

HelpBuilderOptions

• HelpBuilderOptions is an option of HelpBrowser

• Default value of HelpBuilderOptionsis a list of rules:

    HelpBuilderOptions -> {
        "CopyStyleSheets" -> Automatic,
        "IndexToBrowserCategory" -> True,
        "ContentsToBrowserCategory" -> True,
        "IndexStyleDefinitions" -> "HelpBrowser.nb",
        "TagsToTaggingRulesOptions" -> {
            "TagsToTaggingRules" -> True,
            "IndexedCells" -> All,
            "SubEntryDivider" -> ": "},
        "PaginateOptions" -> {},
        "MakeBrowserCategoriesOptions" -> {},
        "MakeContentsOptions" -> {},
        "MakeIndexOptions" -> {}}

• CopyStyleSheets copies notebooks with style sheets into directory with documentation. There are three possible values: True, False and Automatic (default). The value Automatic copies only style sheets which are not within Mathematica system files in directory SystemFiles/FrontEnd/StyleSheets/.

• IndexToBrowserCategory and ContentsToBrowserCategory determine if the corresponding files should be added into BrowserCategory and HelpBrowser panel.

• IndexStyleDefinitions sets the name of StyleSheet of Index file.

• TagsToTaggingRulesOptions is a set of rules used for conversion CellTags to TaggingRules which used for indexing cells to access via HelpBrowser search engine. For more information refer to AuthorTools Guide.

• TagsToTaggingRules determines the conversion of CellTags to TaggingRules

• IndexedCells defines styles of cells which CellTags are converted to TaggingRules

• SubEntryDivider sets a string separating the index entry and subentry. For example, by default cell tag "main: sub" is converted to entry "main" with subentry "sub".

• PaginateOptions, MakeBrowserCategoriesOptions, MakeContentsOptions and MakeIndexOptions used to enter options for AuthorTools` functions Paginate, MakeBrowserCategories, MakeContents and MakeIndex.

SetDelimiters

• SetDelimiters["file"] opens "file" with BrowserCategory for interactive editing of its delimiters
• SetDelimiters[] allows to choose BrowserCategory file via FileBrowse dialog menu.

The following buttons and actions are available:

• Panel title or subtitle – opens substructure

• ⇔ – inserts or removes the delimiter above the title

• Save – saves BrowserCategory in the original file and closes SetDelimiters dialog window

• Save As – opens FileBrowse dialog to save BrowserCategory in a file and closes SetDelimiters dialog window

• Cancel – closes SetDelimiters dialog window

• Help – opens the SetDelimiters help file in HelpBrowser.

   Last modified: January 27, 2007