Skip to content

Override helpfiles

M. Dent requested to merge dentm42/core:override-helpfiles into dev

Add support for overriding helpfiles by either providing an entirely new root directory to replace "doc/", or by overriding specific helpfiles. When overriding the whole documentation root directory, be sure to include a "{newroot}/about/about.[bb|md|html]" as this will be used as the 'fail-safe' if a requested file is not found.

The following can be used in .htconfig or another appropriate place:

\App::$override_helproot = "path"; // default = "doc/".  Unless fully qualified, path is relative to the install directory.
\App::$override_helpfiles ["_default_path_"] = "_new_path_"; // \App::$override_helproot will NOT be applied
                                                             // if a specific file is overridden in this way.
                                                        // _default_path_ and _new_path_ should NOT include 
                                                        //                                       the file extension
                                                        // The file extension will be auto-detected in this order: 
                                                        //          .md   .bb   .html
                                                        // NOTE: Specific language files CAN be overridden using this method.

//Example specific language override
\App:$override_helpfiles ["en-gb/myhelpfile"] = "engb-docs/myhelpfile"; //will use {installroot}/engb-docs/myhelpfile
                                                                        //if the browser requests
                                                                        //       https://my.hub/help/myhelpfile
                                                                        //and the language is set to en-gb.

NOTE: The changes made retain the unfortunate behavior of returning the default about/about page if a specific language is requested in the URL sent to the application but the specific requested translation for that particular page does not exist. For example, if the user language resolves to en-gb (a language for which NO translations are present in the doc/ tree), a specific request to https://my.hub/help/en-gb/member/member_guide will error out and return present the user with the about/about page. The expected behavior would be to return member/member_guide (ignoring the specifically requested translation). This is an edge case, but worth noting someplace in case someone in the future is motivated to fix it.

This behavior existed before the changes in this patch were made.

Edited by M. Dent

Merge request reports