Manual Maintenance is now Tightly Coupled with the Program Code

If some section of the CINELERRA-GG manual gets renamed and is used for Context Help, the corresponding help keywords should be adjusted too. All the keywords used can be listed via the following example command:

	grep -F context_help `find . -name '*.C' -print` | grep -F '"'

—————-

Note that the keyword does not have to exactly match the section title; it can also be a case insensitive substring of the section title.

If some new CINELERRA-GG window or dialog is created and documented, the inclusion of context_help_set_keyword() calls and/or adaptation of keypress_event() handler (if any) should be included in the program code.

If some new CINELERRA-GG plugin is created, it is best to document it in the section entitled exactly equal to that plugin's title. Then probably its context help will work out of the box. Otherwise, some adaptation to its keypress_event() (if any) or to the

Why the local copy of CINELERRA-GG manual should be used?

1. For context help keyphrases matching, the local copy of Contents.html and Index.html is necessary anyway.
2. Grepping CinelerraGG_Manual/*.html files of the remote manual from the website cannot work per definition.
3. The local copy usage ensures exact matching of the version of the manual to the version of CINELERRA-GG. Otherwise, if one uses for some reason an older version of CINELERRA-GG with the help fetched from the newer version of the website manual, various incompatibilities can be expected.
4. Packing the manual into AppImage, the current method of CINELERRA-GG packaging, should be much easier than merging two different git branches when building from source packages, as was done earlier.

What about Localization?

For now, CINELERRA-GG context help is not localized at all. There is no complete CINELERRA-GG manual in any language except English. But even should the manual be translated to other languages, the context help keywords must remain unlocalized literal string constants. First, because the set of languages known to CINELERRA-GG itself is not the same as the set of languages the manual will be translated to. If some "translated keyword" is fed to the help system, while the manual in this language does not exist, keyword matching cannot succeed. Second, such a help localization with the translation of all keywords can be done and then maintained much easier and much more reliably inside the ContextManual.pl script rather than in the CINELERRA-GG binary.

More about ContextManual.pl file?

The bin/doc/ContextManual.pl script can be configured further. Look in the script text. You can define your preferable web browser, or redefine it to 'echo' for debug purposes. There are also some predefined HTML pages for Contents and Index, and several explicitly rewritten keyphrases.

After the first invocation of context help the system-wide script, bin/doc/ContextManual.pl, copies itself into the user's config directory, $HOME/.bcast5. If the user needs to modify ContextManual.pl, it should be done on that copy from .bcast5 rather than the system-wide one. On all subsequent context help requests this (possibly modified) .bcast5 version of the script will be called. If later the CINELERRA-GG package gets upgraded containing a newer, not 100% compatible version of ContextManual.pl script, and/or not compatible structure of the HTML manual itself, the new system-wide version of the script will be copied into .bcast5 again to ensure context help functionality. The older version of the script will be backed up (with the .bak suffix) as a reference of the modifications done by the user.