ScriptForge - (SF_Exception) error messages give access to help page

When ScriptForge detects an error in a user script,
a message box is displayed with a summary of the
syntax and validation rules the invoked method
should respect, and/or any other reason the library
has identified.

Now the error message is completed with
- the sentence "Do you want to receive more information
about the '%1' method ?"
- 2 buttons Yes/No (No being the default)

When the Yes button is pressed the local browser opens
the help page/anchor of the invoked service/method.

The pot template and the english po files are modified.

There is no difference between Basic and Python in this
matter.

Change-Id: Ie6210b9d108c9a1e98a46173504680e3985125b0
Reviewed-on: https://gerrit.libreoffice.org/c/core/+/129232
Tested-by: Jenkins
Tested-by: Jean-Pierre Ledure <jp@ledure.be>
Reviewed-by: Jean-Pierre Ledure <jp@ledure.be>

4 files changed, 69 insertions, 15 deletions

diff --git a/wizards/source/scriptforge/SF_Exception.xba b/wizards/source/scriptforge/SF_Exception.xba
index 57ac5090d6a9..a7fde7b69ea4 100644
--- a/wizards/source/scriptforge/SF_Exception.xba
+++ b/wizards/source/scriptforge/SF_Exception.xba
@@ -739,10 +739,15 @@ Public Sub RaiseFatal(Optional ByVal ErrorCode As Variant _
 '''		pvArgs: the arguments to insert in the error message
 
 Dim sLocation As String		'	Common header in error messages: location of error
+Dim sService As String		'	Service name having detected the error
+Dim sMethod As String		'	Method name having detected the error
 Dim vLocation As Variant	'	Split array (library, module, method)
 Dim sMessage As String		'	Message to log and display
 Dim L10N As Object			'	Alias of Interface
 Dim sAlt As String			'	Alternative error messages
+Dim iButtons As Integer		'	MB_OK or MB_YESNO
+Dim iMsgBox As Integer		'	Return value of the message box
+
 Const cstTabSize = 4
 Const cstThisSub = "Exception.RaiseFatal"
 Const cstSubArgs = "ErrorCode, [Arg0[, Arg1 ...]]"
@@ -762,9 +767,13 @@ Try:
 	If Len(_SF_.MainFunction) > 0 Then	'	MainFunction = [Library.]Module.Method
 		vLocation = Split(_SF_.MainFunction, ".")
 		If UBound(vLocation) < 2 Then vLocation = SF_Array.Prepend(vLocation, "ScriptForge")
-		sLocation = L10N.GetText("VALIDATESOURCE", vLocation(0), vLocation(1), vLocation(2)) _
+		sService = vLocation(1)
+		sMethod = vLocation(2)
+		sLocation = L10N.GetText("VALIDATESOURCE", vLocation(0), sService, sMethod) _
 					& "\n" & L10N.GetText("VALIDATEARGS", _RightCaseArgs(_SF_.MainFunctionArgs))
 	Else
+		sService = ""
+		sMethod = ""
 		sLocation = ""
 	End If
 
@@ -1025,9 +1034,19 @@ Try:
 	'	Display fatal event, if relevant (default)
 	If _SF_.DisplayEnabled Then
 		If _SF_.StopWhenError Then sMessage = sMessage & "\n" & "\n" & "\n" & L10N.GetText("STOPEXECUTION")
-		MsgBox SF_String.ExpandTabs(SF_String.Unescape(sMessage), cstTabSize) _
-				, MB_OK + MB_ICONEXCLAMATION _
-				, L10N.GetText("ERRORNUMBER", ErrorCode)
+		'	Do you need more help ?
+		If Len(sMethod) > 0 Then
+			sMessage = sMessage & "\n" & "\n" & L10N.GetText("NEEDMOREHELP", sMethod)
+			iButtons = MB_YESNO + MB_DEFBUTTON2
+		Else
+			iButtons = MB_OK
+		End If
+		iMsgBox = MsgBox(SF_String.ExpandTabs(SF_String.Unescape(sMessage), cstTabSize) _
+					, iButtons + MB_ICONEXCLAMATION _
+					, L10N.GetText("ERRORNUMBER", ErrorCode) _
+					)
+		'	If more help needed ...
+		If iMsgBox = IDYES Then _OpenHelpInBrowser(sService, sMethod)
 	End If
 	
 Finally:
@@ -1186,6 +1205,22 @@ Finally:
 End Sub			'	ScriptForge.SF_Exception._ConsoleRefresh
 
 REM -----------------------------------------------------------------------------
+Private Sub _OpenHelpInBrowser(ByVal psService As String, ByVal psMethod As String)
+'''	Open the help page and help anchor related to the given ScriptForge service and method
+
+Dim sUrl As String			'	URL to open
+Const cstURL = "https://help.libreoffice.org/latest/en-US/text/sbasic/shared/03/sf_%1.html?&DbPAR=BASIC#%2"
+
+	On Local Error GoTo Finally		'	No reason to risk abort here
+Try:
+	sUrl = SF_String.ReplaceStr(cstURL, Array("%1", "%2"), Array(LCase(psService), psMethod))
+	SF_Session.OpenUrlInBrowser(sUrl)
+
+Finally:
+	Exit Sub
+End Sub			'	ScriptForge.SF_Exception._OpenHelpInBrowser
+
+REM -----------------------------------------------------------------------------
 Private Function _PropertyGet(Optional ByVal psProperty As String) As Variant
 '''	Return the value of the named property
 '''	Args:
diff --git a/wizards/source/scriptforge/SF_Root.xba b/wizards/source/scriptforge/SF_Root.xba
index 3ec4c2936908..9d03fcd6f160 100644
--- a/wizards/source/scriptforge/SF_Root.xba
+++ b/wizards/source/scriptforge/SF_Root.xba
@@ -300,25 +300,30 @@ Try:
 	'	SF_Exception.Raise
 			.AddText(	Context := "CLOSEBUTTON" _
 						, MsgId := "Close" _
-						, Comment := "Text in close buttons of progress and console dialog boxes" _
+						, Comment :=	"Text in close buttons of progress and console dialog boxes" _
 					)
 			.AddText(	Context := "ERRORNUMBER" _
 						, MsgId := "Error %1" _
-						, Comment := "Title in error message box\n" _
-									& "%1: an error number" _
+						, Comment :=	"Title in error message box\n" _
+									&	"%1: an error number" _
 					)
 			.AddText(	Context := "ERRORLOCATION" _
 						, MsgId := "Location : %1" _
-						, Comment := "Error message box\n" _
-									& "%1: a line number" _
+						, Comment :=	"Error message box\n" _
+									&	"%1: a line number" _
 					)
 			.AddText(	Context := "LONGERRORDESC" _
 						, MsgId := "Error %1 - Location = %2 - Description = %3" _
-						, Comment := "Logfile record" _
+						, Comment :=	"Logfile record" _
 					)
 			.AddText(	Context := "STOPEXECUTION" _
 						, MsgId := "THE EXECUTION IS CANCELLED." _
-						, Comment :=	"SF_Utils._Validate error message" _
+						, Comment :=	"Any blocking error message" _
+					)
+			.AddText(	Context := "NEEDMOREHELP" _
+						, MsgId := "Do you want to receive more information about the '%1' method ?" _
+						, Comment :=	"Any blocking error message\n" _
+									&	"%1: a method name" _
 					)
 	'	SF_Exception.RaiseAbort
 			.AddText(	Context := "INTERNALERROR" _
diff --git a/wizards/source/scriptforge/po/ScriptForge.pot b/wizards/source/scriptforge/po/ScriptForge.pot
index cd5abaf03367..9976fb866a25 100644
--- a/wizards/source/scriptforge/po/ScriptForge.pot
+++ b/wizards/source/scriptforge/po/ScriptForge.pot
@@ -14,7 +14,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PACKAGE VERSION\n"
 "Report-Msgid-Bugs-To: https://bugs.libreoffice.org/enter_bug.cgi?product=LibreOffice&bug_status=UNCONFIRMED&component=UI\n"
-"POT-Creation-Date: 2021-07-30 13:10:57\n"
+"POT-Creation-Date: 2022-01-31 16:58:10\n"
 "PO-Revision-Date: YYYY-MM-DD HH:MM:SS\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <EMAIL@ADDRESS>\n"
@@ -51,11 +51,18 @@ msgctxt "LONGERRORDESC"
 msgid  "Error %1 - Location = %2 - Description = %3"
 msgstr ""
 
-#. SF_Utils._Validate error message
+#. Any blocking error message
 msgctxt "STOPEXECUTION"
 msgid  "THE EXECUTION IS CANCELLED."
 msgstr ""
 
+#. Any blocking error message
+#. %1: a method name
+#, kde-format
+msgctxt "NEEDMOREHELP"
+msgid  "Do you want to receive more information about the '%1' method ?"
+msgstr ""
+
 #. SF_Exception.RaiseAbort error message
 msgctxt "INTERNALERROR"
 msgid  ""
diff --git a/wizards/source/scriptforge/po/en.po b/wizards/source/scriptforge/po/en.po
index cd5abaf03367..9976fb866a25 100644
--- a/wizards/source/scriptforge/po/en.po
+++ b/wizards/source/scriptforge/po/en.po
@@ -14,7 +14,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PACKAGE VERSION\n"
 "Report-Msgid-Bugs-To: https://bugs.libreoffice.org/enter_bug.cgi?product=LibreOffice&bug_status=UNCONFIRMED&component=UI\n"
-"POT-Creation-Date: 2021-07-30 13:10:57\n"
+"POT-Creation-Date: 2022-01-31 16:58:10\n"
 "PO-Revision-Date: YYYY-MM-DD HH:MM:SS\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <EMAIL@ADDRESS>\n"
@@ -51,11 +51,18 @@ msgctxt "LONGERRORDESC"
 msgid  "Error %1 - Location = %2 - Description = %3"
 msgstr ""
 
-#. SF_Utils._Validate error message
+#. Any blocking error message
 msgctxt "STOPEXECUTION"
 msgid  "THE EXECUTION IS CANCELLED."
 msgstr ""
 
+#. Any blocking error message
+#. %1: a method name
+#, kde-format
+msgctxt "NEEDMOREHELP"
+msgid  "Do you want to receive more information about the '%1' method ?"
+msgstr ""
+
 #. SF_Exception.RaiseAbort error message
 msgctxt "INTERNALERROR"
 msgid  ""