tdf#141474 tdf#124066 Basic keyword arguments explanations

Change-Id: I9f05990a9c3513d171b7ae94e8d60e5d0d1ced2f
Reviewed-on: https://gerrit.libreoffice.org/c/help/+/116468
Tested-by: Jenkins
Reviewed-by: Rafael Lima <rafael.palma.lima@gmail.com>

2 files changed, 29 insertions, 19 deletions

diff --git a/source/text/sbasic/shared/01020300.xhp b/source/text/sbasic/shared/01020300.xhp
index 067746a1dd..1238f01090 100644
--- a/source/text/sbasic/shared/01020300.xhp
+++ b/source/text/sbasic/shared/01020300.xhp
@@ -55,7 +55,7 @@
 </bascode>
 <paragraph id="par_id3152577" role="paragraph" xml-lang="en-US">The <literal>Sub</literal> is called using the following syntax:</paragraph>
 <bascode>
-  <paragraph id="par_idm1341029952" role="bascode" localize="false" xml-lang="en-US">SubName(Value1, Value2,...)</paragraph>
+  <paragraph id="par_idm1341029952" role="bascode" localize="false" xml-lang="en-US">[Call] SubName( [Parameter1:=]Value1, [Parameter2:=]Value2, ...)</paragraph>
 </bascode>
 <paragraph id="par_id3147124" role="paragraph" xml-lang="en-US">The parameters passed to a <literal>Sub</literal> must fit to those specified in the <literal>Sub</literal> declaration.</paragraph>
 <paragraph id="par_id3147397" role="paragraph" xml-lang="en-US">The same process applies to a <literal>Function</literal>. In addition, functions always return a function result. The result of a function is defined by assigning the return value to the function name:</paragraph>
@@ -67,9 +67,9 @@
 </bascode>
 <paragraph id="par_id3153839" role="paragraph" xml-lang="en-US">The <literal>Function</literal> is called using the following syntax:</paragraph>
 <bascode>
-  <paragraph id="par_id3146914" role="bascode" xml-lang="en-US" localize="false">Variable=FunctionName(Parameter1, Parameter2,...)</paragraph>
+  <paragraph id="par_id3146914" role="bascode" xml-lang="en-US" localize="false">Variable = FunctionName( [Parameter1:=]Value1, [Parameter2:=]Value2, ...)</paragraph>
 </bascode>
-<paragraph role="paragraph" id="par_id981584288549909">Properties combine the syntax of procedures and functions. A property usually requires up to one parameter.</paragraph>
+<paragraph role="paragraph" id="par_id981584288549909">Properties combine the syntax of procedures and functions. A <literal>Property</literal> usually requires up to one parameter.</paragraph>
 <bascode>
   <paragraph role="bascode" id="bas_id521585039888250" localize="false">Private _IsApproved As TYPENAME</paragraph>
   <paragraph role="bascode" id="bas_id471584288905523" localize="false">Property Get IsApproved As TYPENAME</paragraph>
@@ -86,7 +86,7 @@
   <paragraph role="bascode" id="bas_id511584289696025" localize="false">var = IsApproved</paragraph>
   <paragraph role="bascode" id="bas_id551584289696697" localize="false">IsApproved = some_value</paragraph>
 </bascode>
-<tip id="par_idN107B3">You can also use the fully qualified name to call a procedure, function or property:<br/> <literal>Library.Module.Macro()</literal> <br/> For example, to call the Autotext macro from the Gimmicks library, use the following command:<br/> <item type="literal">Gimmicks.AutoText.Main()</item> </tip>
+<tip id="par_idN107B3">You can also use the fully qualified name to call a procedure, function or property:<br/> <literal>[Call] Library.Module.Macro()</literal>, where <literal>Call</literal> is optional.<br/> For example, to call the Autotext macro from the Gimmicks library, use the following command:<br/> <literal>Gimmicks.AutoText.Main()</literal></tip>
 <h2 id="hd_id3156276">Passing Variables by Value or Reference</h2>
 <paragraph id="par_id3155765" role="paragraph" xml-lang="en-US">Parameters can be passed to a procedure, a function or a property either by reference or by value. Unless otherwise specified, a parameter is always passed by reference. That means that a <literal>Sub</literal>, a <literal>Function</literal> or a <literal>Property</literal> gets the parameter and can read and modify its value.</paragraph>
 <paragraph id="par_id3145640" role="paragraph" xml-lang="en-US">If you want to pass a parameter by value insert the key word <literal>ByVal</literal> in front of the parameter when you call a <literal>Sub</literal>, a <literal>Function</literal> or a <literal>Property</literal>, for example:</paragraph>
@@ -104,6 +104,11 @@
   <paragraph role="bascode" id="bas_id111584366809406">    &apos; your code goes here</paragraph>
   <paragraph role="bascode" id="bas_id251584366745722" localize="false">End Sub</paragraph>
 </bascode>
+<h2 id="hd_id951622730099178">Positional or Keyword Arguments</h2>
+<paragraph role="paragraph" id="par_id591622730131786">When you call a function or a subroutine, you may pass its arguments by position or by name. Passing by position means just listing the arguments in the order in which the parameters are defined in the function or subroutine. Passing by name requires you to prefix the argument with the name of the corresponding parameter followed by a colon and an equal sign (<literal>:=</literal>). Keyword arguments may appear in any order. Refer to Basic Replace() function for such examples.</paragraph>
+<section id="kwargs">
+<paragraph role="paragraph" id="par_id591622730284162">When needing to pass less parameters, use keywords arguments. Passing values for fewer parameters by position requires to supply values for all parameters before them, optional or not. This ensures that the values are in the correct positions. If you pass the parameters by name - using keyword arguments - you may omit all other intermediate arguments.</paragraph>
+</section>
 <h2 id="hd_id3150982">Scope of Variables</h2>
 <paragraph id="par_id3149814" role="paragraph" xml-lang="en-US">A variable defined within a <literal>Sub</literal>, a <literal>Function</literal> or a <literal>Property</literal>, only remains valid until the procedure is exited. This is known as a "local" variable. In many cases, you need a variable to be valid in all procedures, in every module of all libraries, or after a <literal>Sub</literal>, a <literal>Function</literal> or a <literal>Property</literal> is exited.</paragraph>
 <h3 id="hd_id3154186">Declaring Variables Outside a <literal>Sub</literal> a <literal>Function</literal> or a <literal>Property</literal></h3>
@@ -124,7 +129,7 @@
 </bascode>
 <paragraph id="par_id3150368" role="paragraph" xml-lang="en-US">The variable is only valid in this module.</paragraph>
 <h3 id="hd_id5097506">Example for private variables</h3>
-  <paragraph id="par_id8738975" role="paragraph" xml-lang="en-US">Enforce private variables to be private across modules by setting <literal>CompatibilityMode(True)</literal>.</paragraph><comment>from i17948, see i54894</comment>
+<paragraph id="par_id8738975" role="paragraph" xml-lang="en-US">Enforce private variables to be private across modules by setting <literal>CompatibilityMode(True)</literal>.</paragraph><comment>from i17948, see i54894</comment>
 <bascode>
   <paragraph id="par_idm1340976400" role="bascode" localize="false">' ***** Module1 *****</paragraph>
   <paragraph id="par_idm1340975168" role="bascode" localize="false">Private myText As String</paragraph>
@@ -161,4 +166,4 @@
   <paragraph role="paragraph" id="N0239"><link href="text/sbasic/shared/03103500.xhp" name ="Static Statement">Static Statement</link></paragraph>
 </section>
 </body>
-</helpdocument>
+</helpdocument>
\ No newline at end of file
diff --git a/source/text/sbasic/shared/replace.xhp b/source/text/sbasic/shared/replace.xhp
index 7b8d819d98..091a2f0826 100644
--- a/source/text/sbasic/shared/replace.xhp
+++ b/source/text/sbasic/shared/replace.xhp
@@ -25,33 +25,38 @@
     </section>
 
     <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
-    <paragraph role="code" id="par_id931552552227310">Replace (Text As String, SearchStr As String, ReplStr As String [, Start As Long [, Count as Long [, Compare As Boolean]]]</paragraph>
-
+    <bascode>
+       <paragraph role="bascode" localize="false" id="bas_id51623159758550">Replace (Expression As String, Find As String, Replace As String [, Start = 1 [, Count = -1 [, Compare = True]]]) As String</paragraph>
+    </bascode>
+    <embed href="text/sbasic/shared/01020300.xhp#kwargs"/>
     <embed href="text/sbasic/shared/00000003.xhp#functvalue"/>
     <paragraph role="paragraph" id="par_id911552552252024">String</paragraph>
 
     <embed href="text/sbasic/shared/00000003.xhp#functparameters"/>
-    <paragraph role="paragraph" id="par_id721552552263062"><emph>Text:</emph> Any string expression that you want to modify.</paragraph>
-    <paragraph role="paragraph" id="par_id901552552269836"><emph>SearchStr:</emph> Any string expression that shall be searched for.</paragraph>
-    <paragraph role="paragraph" id="par_id791552552275383"><emph>ReplStr:</emph> Any string expression that shall replace the found search string.</paragraph>
-    <paragraph role="paragraph" id="par_id111552552283060"><emph>Start:</emph> Numeric expression that indicates the character position where the search starts and also the start of the substring to be returned.</paragraph>
-    <paragraph role="paragraph" id="par_id921552552289833"><emph>Count:</emph> The maximal number of times the replace shall be performed.</paragraph>
-    <paragraph role="paragraph" id="par_id891552552302894"><emph>Compare:</emph> Optional boolean expression that defines the type of comparison. The value of this parameter can be TRUE or FALSE. The default value of TRUE specifies a text comparison that is not case-sensitive. The value of FALSE specifies a binary comparison that is case-sensitive. You can as well use 0 instead of FALSE or 1 instead of TRUE.</paragraph>
+    <paragraph role="paragraph" id="par_id721552552263062"><emph>Expression:</emph> Any string expression that you want to modify.</paragraph>
+    <paragraph role="paragraph" id="par_id901552552269836"><emph>Find:</emph> Any string expression that shall be searched for.</paragraph>
+    <paragraph role="paragraph" id="par_id791552552275383"><emph>Replace:</emph> Any string expression that shall replace the found search string.</paragraph>
+    <paragraph role="paragraph" id="par_id111552552283060"><emph>Start:</emph> Optional numeric expression that indicates the character position where the search starts and also the start of the substring to be returned.</paragraph>
+    <paragraph role="paragraph" id="par_id921552552289833"><emph>Count:</emph> Optional maximum number of times the replace shall be performed. When set to -1, all possible replacements are performed.</paragraph>
+    <paragraph role="paragraph" id="par_id891552552302894"><emph>Compare:</emph> Optional boolean expression that defines the type of comparison. The value of this parameter can be <literal>True</literal> or <literal>False</literal>. The default value of <literal>True</literal> specifies a text comparison that is not case-sensitive. The value of <literal>False</literal> specifies a binary comparison that is case-sensitive. You can as well use 0 instead of <literal>False</literal> or 1 instead of <literal>True</literal>.</paragraph>
 
     <embed href="text/sbasic/shared/00000003.xhp#errorcode"/>
     <embed href="text/sbasic/shared/00000003.xhp#err5"/>
     <embed href="text/sbasic/shared/00000003.xhp#functexample"/>
 
     <bascode>
-        <paragraph role="bascode" id="par_id991552552420717">msgbox replace ("aBbcnnbnn", "b", "$", 1, 1, FALSE)	'returns "aB$cnnbnn"</paragraph>
-        <paragraph role="bascode" id="par_id321552552440672" >REM meaning: "b" should be replaced, but</paragraph>
-        <paragraph role="bascode" id="par_id571552552467647">REM * only when lowercase (parameter 6), hence second occurrence of "b"</paragraph>
-        <paragraph role="bascode" id="par_id71552552474769">REM * only first (respecting case) occurrence (parameter 5)</paragraph>
-        <paragraph role="bascode" id="par_id501587778372566" xml-lang="en-US" localize="false">msgbox replace ("ABCDEFGHI", "E", "*", 4)</paragraph>
+        <paragraph role="bascode" id="par_id991552552420717">MsgBox Replace ("aBbcnnbnn", "b", "$", 1, 1, False)  'returns "aB$cnnbnn"</paragraph>
+        <paragraph role="bascode" id="par_id321552552440672" xml-lang="en-US">REM meaning: "b" should be replaced, but</paragraph>
+        <paragraph role="bascode" id="par_id571552552467647" xml-lang="en-US">REM * only when lowercase (compare=False), hence second occurrence of "b"</paragraph>
+        <paragraph role="bascode" id="par_id71552552474769" xml-lang="en-US">REM * only first (respecting case) occurrence (count=1)</paragraph>
+        <paragraph role="bascode" id="par_id501587778372566" localize="false">MsgBox Replace ("ABCDEFGHI", "E", "*", 4)</paragraph>
         <paragraph role="bascode" id="par_id861587778446685" xml-lang="en-US">REM returns D*FGHI because the search starts at position 4, which is also the start of the returned string.</paragraph>
+        <paragraph role="bascode" id="bas_id491622734884707" xml-lang="en-US">MsgBox Replace("aBbcnnbnn", "b", "$£", compare:=False)  'returns "aB$£cnn$£nn"</paragraph>
+        <paragraph role="bascode" id="bas_id341622734993202" xml-lang="en-US">REM Replace all (count = -1) "b" with "$£" respecting casing (compare=False) starting from first letter (start=1) </paragraph>
     </bascode>
     <section id="relatedtopics">
         <paragraph role="paragraph" id="par_id161599082457466" localize="false"><embedvar href="text/sbasic/shared/00000003.xhp#stringfunctions"/></paragraph>
+        <paragraph role="paragraph" id="par_id361623159933508" localize="false"><embedvar href="text/sbasic/shared/03/sf_string.xhp#StringService"/></paragraph>
     </section>
 </body>
 </helpdocument>