Migrating Help Content from Versions of Maple Prior to 18
Description
Automatic Migration
Manual Migration
Maple 18 has new and improved help system and as a result, all existing help databases in .hdb format have to be converted to the new .help format.
This worksheet guides you through a process of converting old content to be compatible with Maple 18, or later.
Content in the new help system can be tagged by language, product, and category.
The HelpTools:-Database:-ConvertAll command will convert all .hdb files to .help files. This command looks for .hdb files located in any of the folders listed in libname.
To migrate all .hdb files to .help format, run this command:
HelpTools:-Database:-ConvertAll():
Step 1. Setup
Existing .hdb file
hdb_database := Maplets:-Examples:-GetFile('title' = "Help Database", 'filefilter'="hdb");
New .help database
help_database := cat(hdb_database[1..-4], "help");
Language
help_language := "en";
Product
help_product := "User Help";
Category
help_category := "Help Page";
Temporary directory into which the contents from .hdb file will be saved
temp_dir := StringTools:-Join([FileTools:-TemporaryDirectory(), "helpmigration", FileTools:-Basename(hdb_database)], kernelopts('dirsep'));
Create temporary directory if it does not exist
if not FileTools:-Exists(temp_dir) then FileTools:-MakeDirectory(temp_dir, 'recurse'=true); end if;
Create new help database, if it does not exist
if not FileTools:-Exists(help_database) then help_database := HelpTools:-Database:-Create(help_database); end if;
Step 2. Extract Contents from .hdb File
The ExtractContentsFromHDB command returns a table with three entries, "help pages", table of contents", and "task icons".
contents := HelpTools:-Database:-ExtractContentsFromHDB(temp_dir, hdb_database):
Step 3. Adjust Content (Optional)
Here you can examine and adjust the value of the contents variable.
List of all worksheets extracted from .hdb file:
indices(contents["help pages"], 'nolist');
Step 4. Store Content in the New Database
HelpTools:-Worksheet:-Store(contents["help pages"], help_database, 'language' = help_language, 'product' = help_product, 'category' = help_category);
Step 5. Add Table of Contents to the New Database
for toc in HelpTools:-TableOfContents:-ConvertFromXML(contents["table of contents"]) do HelpTools:-TableOfContents:-Load(toc, help_database); end do:
Step 6. Add Task Icons to the New Database
for icon_file in indices(contents["task icons"], 'nolist') do DocumentTools:-AddIcon(contents["task icons"][icon_file], 'path' = icon_file, 'hdb' = help_database); end do:
Step 7. Start Using Content from New Database
HelpTools:-Database:-Add(help_database):
Note: Unless new database is located in one of the folders listed in libname, it will not be used next time you start Maple.
See Also
updates/Maple18/HelpSystem
Download Help Document
