feat(help): rework help system and add French translations #1469

Nelson-numerical-software · 2025-10-20T18:50:52Z

This commit significantly improves Nelson's help documentation system:

Replaces the deprecated help_browser module with a modern help tools implementation.
Transitions help files from .qch (Qt Compiled Help) to .nhz (Nelson Help Zip) format.
Adds complete French (fr_FR) documentation for the following modules:
Enhances English documentation better chapter descriptions.
Updates build configuration and installation scripts to reflect the new help system.

Copilot

Pull Request Overview

This pull request significantly reworks and improves Nelson's help documentation system. It replaces the help browser module with a more modern help tools implementation and transitions from .qch (Qt Compiled Help) format to .nhz (Nelson Help Zip) format. The PR also adds comprehensive French (fr_FR) translations for multiple modules including control_system, constructors_functions, console, and com_engine, along with improvements to English documentation.

Key changes:

Removes the help_browser module dependency and replaces help file format from .qch to .nhz
Adds complete French documentation for control system, constructor functions, console, and COM engine modules
Enhances English documentation with runnable example attributes and improved chapter descriptions
Updates build configuration and installation scripts to reflect new help system

Reviewed Changes

Copilot reviewed 279 out of 3118 changed files in this pull request and generated 23 comments.

Show a summary per file

File	Description
modules/control_system/help/fr_FR/xml/*.xml	New French documentation for 30+ control system functions
modules/control_system/help/en_US/xml/*.xml	Enhanced English docs with runnable example attributes and typo fixes
modules/constructors_functions/help/fr_FR/xml/*.xml	New French documentation for constructor functions
modules/constructors_functions/help/en_US/xml/*.xml	Enhanced English docs with runnable attributes
modules/console/help/fr_FR/xml/*.xml	New French documentation for console module
modules/console/help/en_US/xml/*.xml	Enhanced English docs with runnable attributes
modules/com_engine/help/fr_FR/xml/*.xml	New French documentation for COM engine
modules/com_engine/help/en_US/xml/*.xml	Enhanced English docs with runnable attributes
modules/*/CMakeLists.txt	Updated to install `.nhz` instead of `.qch` files
modules/*/module.iss	Updated installer scripts for new help format
modules/commons/src/include/nlsBuildConfig.h.*	Removed help_browser module dependency
modules/CMakeLists.txt	Removed HELP_BROWSER from module list

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

modules/control_system/help/fr_FR/xml/compreal.xml

modules/control_system/help/fr_FR/xml/c2d.xml

modules/control_system/help/fr_FR/xml/bdschur.xml

modules/control_system/help/fr_FR/xml/balreal.xml

modules/control_system/help/fr_FR/xml/lqed.xml

modules/control_system/help/fr_FR/xml/lqe.xml

modules/help_tools/resources/help_viewer.html

modules/help_tools/resources/nelson_help.js

modules/help_tools/resources/search_results.html

Copilot

Pull Request Overview

Copilot reviewed 279 out of 3118 changed files in this pull request and generated no new comments.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot

Pull Request Overview

Copilot reviewed 279 out of 3126 changed files in this pull request and generated 1 comment.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

modules/control_system/help/fr_FR/xml/isstatic.xml

Copilot

Pull Request Overview

Copilot reviewed 279 out of 3126 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (3)

modules/control_system/help/en_US/xml/bode.xml:40

The description text is in English but appears in a French translation context. This is likely a copy-paste error that wasn't corrected during translation.

            <param_description>Phase: size 1 x 1 x k (SISO).</param_description>

modules/control_system/help/en_US/xml/bode.xml:44

Similar to phase parameter, this description is in English within what should be French translation context based on file structure patterns.

            <param_description>Frequencies: a vector: 1 x k.</param_description>

modules/control_system/help/en_US/xml/bode.xml:1

The entire description block (lines 50-57) is in English in what appears to be the en_US file, which is correct. However, this English text was not translated in the fr_FR version of this file.

<?xml version="1.0" encoding="UTF-8" ?>

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot

Pull Request Overview

Copilot reviewed 279 out of 3126 changed files in this pull request and generated no new comments.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

modules/file_archiver/src/cpp/Unzip.cpp

modules/help_tools/src/c/cmark/blocks.c

modules/help_tools/src/c/cmark/buffer.c

modules/help_tools/src/c/cmark/buffer.h

modules/help_tools/src/c/cmark/commonmark.c

modules/help_tools/src/c/cmark/html.c

modules/help_tools/src/c/cmark/inlines.c

modules/help_tools/src/c/cmark/latex.c

modules/help_tools/src/c/cmark/man.c

modules/help_tools/src/c/cmark/node.c

modules/help_tools/src/c/cmark/utf8.c

modules/help_tools/src/c/cmark/xml.c

modules/help_tools/src/cpp/XmlDocBuild.cpp

modules/help_tools/src/cpp/XmlDocListOfFiles.cpp

modules/help_tools/src/cpp/XmlDocMergeSummary.cpp

modules/help_tools/src/cpp/XmlDocSummary.cpp

modules/help_tools/src/cpp/XmlTransform.cpp

modules/help_tools/src/cpp/XmlDocMergeSummary.cpp

+
+//=============================================================================
+static void
+addRawXml(xmlNodePtr parent, const std::string& rawxml)


To resolve this issue, we should remove the entire definition of the unused static void addRawXml function from this file. Specifically, delete lines 229 through 243 of XmlDocMergeSummary.cpp, which include the function's signature, body, and trailing comment-delineated separator. No other changes or imports are needed elsewhere; simply deleting this function is safe and maintains existing functionality.

- html and md generation working - local help indexing working - some cleanup of helptools module - removed qch/qhcp generation (not used anymore) - removed hoedown (replaced by cmark) - fixed some issues with special characters in markdown - added crc32 builtin function (used for help indexing) - updated changelogs - help_browser module removed - theme support for html/md help (light/dark) - added images generation for examples TODO: - add more tests - update documentation - refactor some code

- french translation added

- Updated XSLT files to apply templates for parameter descriptions in HTML output, improving the rendering of complex descriptions. - Introduced a new template for rendering inline links in both HTML and Markdown formats, enhancing navigation within documentation. - Added emoji icons to various text labels in the Markdown output for better visual appeal and clarity. - Improved test scripts to skip tests if XML documentation is missing, ensuring robustness in test execution. - Created a new script to check XML documentation integrity across modules, enhancing documentation quality assurance. - Refactored existing XML documentation files for consistency and clarity, including translations and formatting adjustments.

…r contrast for better accessibility

… remove XmlDocMakeSummary.cpp

Nelson-numerical-software requested a review from Copilot October 20, 2025 18:50

Copilot AI reviewed Oct 20, 2025

View reviewed changes

Nelson-numerical-software changed the title ~~rework - improve help of Nelson~~ feat(help): rework help system and add French translations Oct 20, 2025

github-advanced-security bot found potential problems Oct 20, 2025

View reviewed changes

Nelson-numerical-software requested a review from Copilot October 20, 2025 19:16

Copilot AI reviewed Oct 20, 2025

View reviewed changes

Nelson-numerical-software force-pushed the help_v2 branch 4 times, most recently from 53451a5 to dcc1ad6 Compare October 21, 2025 16:54

Nelson-numerical-software requested a review from Copilot October 21, 2025 16:55

Copilot AI reviewed Oct 21, 2025

View reviewed changes

modules/control_system/help/fr_FR/xml/isstatic.xml Outdated Show resolved Hide resolved

Nelson-numerical-software force-pushed the help_v2 branch from dcc1ad6 to 96548ad Compare October 21, 2025 17:00

Nelson-numerical-software requested a review from Copilot October 21, 2025 17:00

Copilot AI reviewed Oct 21, 2025

View reviewed changes

Nelson-numerical-software requested a review from Copilot October 21, 2025 17:35

Copilot AI reviewed Oct 21, 2025

View reviewed changes

github-advanced-security bot found potential problems Oct 21, 2025

View reviewed changes

github-advanced-security bot found potential problems Oct 22, 2025

View reviewed changes

modules/help_tools/src/c/cmark/man.c Dismissed Show dismissed Hide dismissed

modules/help_tools/src/c/cmark/node.c Dismissed Show dismissed Hide dismissed

modules/help_tools/src/c/cmark/node.c Dismissed Show dismissed Hide dismissed

github-advanced-security bot found potential problems Oct 22, 2025

View reviewed changes

Nelson-numerical-software force-pushed the help_v2 branch from 8510d70 to 2c96eef Compare October 22, 2025 18:14

github-advanced-security bot found potential problems Oct 22, 2025

View reviewed changes

Nelson-numerical-software added 7 commits October 23, 2025 21:54

chore: regenerate all images (windows x64 , release) (#1461)

7271c82

- french translation added

doc: missing french translation

030828a

doc: missing images

5006c9d

doc: missing images

5a25b62

add latex support in help files

f116de2

add button edit on github

f325d9f

Nelson-numerical-software added 14 commits October 23, 2025 21:57

chore: remove qhelpgenerator no more required

3b84835

chore: fix typo

f0731d9

chore: embed xml files

c3e3101

update translations

8580051

embed mathjax

02a405b

fix syntax colorization examples

8dde3b2

fix duplicate files

a1608c1

colorize syntax block

da657c7

fix CodeQL warnings

909887a

fix dark theme support (syntax, examples)

c4ce98c

Enhance dark theme support across various components and improve colo…

32f6363

…r contrast for better accessibility

CodeQL Warnings export functions for PDF, SVG, TIFF, and GIF formats;…

85b4773

… remove XmlDocMakeSummary.cpp

doc: update changelog

b669437

Nelson-numerical-software force-pushed the help_v2 branch from 2c96eef to b669437 Compare October 23, 2025 20:10

Nelson-numerical-software added 2 commits October 24, 2025 19:47

feat(doc): 'help' for functions in Command Window

8317e6f

chore: renaming

14b4c40

Nelson-numerical-software force-pushed the help_v2 branch 7 times, most recently from 13f8715 to f3ec522 Compare October 26, 2025 16:32

chore: xml module

9fbc810

Nelson-numerical-software force-pushed the help_v2 branch from f3ec522 to 9fbc810 Compare October 26, 2025 19:18

Nelson-numerical-software merged commit 91e296a into master Oct 26, 2025
24 checks passed

Nelson-numerical-software deleted the help_v2 branch October 26, 2025 20:31

@@ -226,22 +226,6 @@
             }
             //=============================================================================
-            static void
-            addRawXml(xmlNodePtr parent, const std::string& rawxml)
-            {
-                xmlNodePtr list = nullptr;
-                int ret = xmlParseInNodeContext(parent, rawxml.c_str(), (int)rawxml.size(), 0, &list);
-                if (ret == 0 && list) {
-                    for (xmlNodePtr cur = list; cur; cur = cur->next) {
-                        xmlAddChild(parent, xmlCopyNode(cur, 1));
-                    }
-                    xmlFreeNodeList(list);
-                }
-            }
-            //=============================================================================
             static bool
             CreateMergedXmlDocument(const std::vector<SectionInfo>& sections, const std::string& mainPage,
                 const std::filesystem::path& outputPath, std::wstring& errorMessage)

Uh oh!

Uh oh!

feat(help): rework help system and add French translations #1469

feat(help): rework help system and add French translations #1469

Uh oh!

Conversation

Nelson-numerical-software commented Oct 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Check notice

Copilot Autofix

Uh oh!

Reviewers

Nelson-numerical-software commented Oct 20, 2025 •

edited

Loading