tdf#131368, tdf#141474 Document WeekDay Basic function

This patch updates the WeekDay documentation to explain the use of the second (optional) argument, that refers to which day of the week should be considered to be the first day of the week.

This patch also refactors the Now function help page and adds a variable for x-ref.

Change-Id: I4bfc9070fc93593217c3c9086935dfc728adee3c
Reviewed-on: https://gerrit.libreoffice.org/c/help/+/114868
Tested-by: Jenkins
Reviewed-by: Olivier Hallot <olivier.hallot@libreoffice.org>

4 files changed, 177 insertions, 59 deletions

diff --git a/source/text/sbasic/shared/03030101.xhp b/source/text/sbasic/shared/03030101.xhp
index a313f67316..2ee2203c35 100644
--- a/source/text/sbasic/shared/03030101.xhp
+++ b/source/text/sbasic/shared/03030101.xhp
@@ -32,16 +32,16 @@
 <section id="dateserial">
 <bookmark xml-lang="en-US" branch="index" id="bm_id3157896"><bookmark_value>DateSerial function</bookmark_value>
 </bookmark>
-<paragraph role="heading" id="hd_id3157896" xml-lang="en-US" level="1"><link href="text/sbasic/shared/03030101.xhp" name="DateSerial Function">DateSerial Function</link></paragraph>
+<h1 id="hd_id381619878817271"><variable id="DateSerial_H1"><link href="text/sbasic/shared/03030101.xhp" name="DateSerial Function">DateSerial Function</link></variable></h1>
 <paragraph role="paragraph" id="par_id3143267" xml-lang="en-US">Returns a <emph>Date</emph> value for a specified year, month, or day.</paragraph>
 </section>
-<paragraph role="heading" id="hd_id3147264" xml-lang="en-US" level="2">Syntax:</paragraph>
+<embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
 <bascode>
 <paragraph role="bascode" id="par_id3149670" xml-lang="en-US">DateSerial (year, month, day)</paragraph>
 </bascode>
-<paragraph role="heading" id="hd_id3150792" xml-lang="en-US" level="2">Return value:</paragraph>
+<embed href="text/sbasic/shared/00000003.xhp#functvalue"/>
 <paragraph role="paragraph" id="par_id3150398" xml-lang="en-US">Date</paragraph>
-<paragraph role="heading" id="hd_id3154141" xml-lang="en-US" level="2">Parameters:</paragraph>
+<embed href="text/sbasic/shared/00000003.xhp#functparameters"/>
 <paragraph role="paragraph" id="par_id3147229" xml-lang="en-US">
 <emph>Year:</emph> Integer expression that indicates a year. All values between 0 and 99 are interpreted as the years 1900-1999. For years that fall outside this range, you must enter all four digits.</paragraph>
 <paragraph role="paragraph" id="par_id3156280" xml-lang="en-US">
@@ -54,17 +54,16 @@
 <paragraph role="paragraph" id="par_id3149481" xml-lang="en-US">Whereas you define the <emph>DateValue function</emph> as a string that contains the date, the <emph>DateSerial function</emph> evaluates each of the parameters (year, month, day) as separate numeric expressions.</paragraph>
 <embed href="text/sbasic/shared/00000003.xhp#errorcode"/>
 <embed href="text/sbasic/shared/00000003.xhp#err5"/>
-<paragraph role="heading" id="hd_id3155411" xml-lang="en-US" level="2">Example:</paragraph>
+<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
 <bascode>
-<paragraph role="bascode" id="par_id3148646" xml-lang="en-US" localize="false">Sub ExampleDateSerial</paragraph>
-<paragraph role="bascode" id="par_id3156441" xml-lang="en-US" localize="false">Dim lDate As Long</paragraph>
-<paragraph role="bascode" id="par_id3154791" xml-lang="en-US" localize="false">Dim sDate As String</paragraph>
-<paragraph role="bascode" id="par_id3155415" xml-lang="en-US" localize="false">    lDate = DateSerial(1964, 4, 9)</paragraph>
-<paragraph role="bascode" id="par_id3147125" xml-lang="en-US" localize="false">    sDate = DateSerial(1964, 4, 9)</paragraph>
-<paragraph role="bascode" id="par_id3154942" xml-lang="en-US">    MsgBox lDate ' returns 23476</paragraph>
-<paragraph role="bascode" id="par_id3151074" xml-lang="en-US">    MsgBox sDate ' returns 04/09/1964</paragraph>
-<paragraph role="bascode" id="par_id3153878" xml-lang="en-US" localize="false">End Sub</paragraph>
+  <paragraph role="bascode" id="par_id3148646" localize="false">Sub ExampleDateSerial</paragraph>
+  <paragraph role="bascode" id="par_id3156441" localize="false">Dim lDate As Long</paragraph>
+  <paragraph role="bascode" id="par_id3154791" localize="false">Dim sDate As String</paragraph>
+  <paragraph role="bascode" id="par_id3155415" localize="false">    lDate = DateSerial(1964, 4, 9)</paragraph>
+  <paragraph role="bascode" id="par_id3147125" localize="false">    sDate = DateSerial(1964, 4, 9)</paragraph>
+  <paragraph role="bascode" id="par_id3154942">    MsgBox lDate ' returns 23476</paragraph>
+  <paragraph role="bascode" id="par_id3151074">    MsgBox sDate ' returns 04/09/1964</paragraph>
+  <paragraph role="bascode" id="par_id3153878" localize="false">End Sub</paragraph>
 </bascode>
 </body>
 </helpdocument>
-
diff --git a/source/text/sbasic/shared/03030102.xhp b/source/text/sbasic/shared/03030102.xhp
index 664e122cf2..f2801d80cf 100644
--- a/source/text/sbasic/shared/03030102.xhp
+++ b/source/text/sbasic/shared/03030102.xhp
@@ -33,7 +33,7 @@
 <section id="datevalue">
   <bookmark xml-lang="en-US" branch="index" id="bm_id3156344"><bookmark_value>DateValue function</bookmark_value>
   </bookmark>
-  <h1 id="hd_id3156344"><link href="text/sbasic/shared/03030102.xhp" name="DateValue Function">DateValue Function</link></h1>
+  <h1 id="hd_id3156344"><variable id="DateValue_H1"><link href="text/sbasic/shared/03030102.xhp" name="DateValue Function">DateValue Function</link></variable></h1>
   <paragraph role="paragraph" id="par_id3150542" xml-lang="en-US">Returns a date value from a date string. The date string is a complete date in a single numeric value. You can also use this serial number to determine the difference between two dates.</paragraph>
 </section>
 
diff --git a/source/text/sbasic/shared/03030105.xhp b/source/text/sbasic/shared/03030105.xhp
index 874ee751ab..c8c5cca159 100644
--- a/source/text/sbasic/shared/03030105.xhp
+++ b/source/text/sbasic/shared/03030105.xhp
@@ -18,56 +18,175 @@
  -->
 <helpdocument version="1.0">
 <meta>
-<topic id="textsbasicshared03030105xml" indexer="include" status="PUBLISH">
-<title id="tit" xml-lang="en-US">WeekDay Function</title>
-<filename>/text/sbasic/shared/03030105.xhp</filename>
-</topic>
-<history>
-<created date="2003-10-31T00:00:00">Sun Microsystems, Inc.</created>
-</history>
+  <topic id="textsbasicshared03030105xml" indexer="include" status="PUBLISH">
+  <title id="tit" xml-lang="en-US">WeekDay Function</title>
+  <filename>/text/sbasic/shared/03030105.xhp</filename>
+  </topic>
+  <history>
+    <created date="2003-10-31T00:00:00">Sun Microsystems, Inc.</created>
+  </history>
 </meta>
 <body>
 <section id="weekday">
-<bookmark xml-lang="en-US" branch="index" id="bm_id3153127"><bookmark_value>WeekDay function</bookmark_value>
+<bookmark xml-lang="en-US" branch="index" id="bm_id3153127">
+  <bookmark_value>WeekDay function</bookmark_value>
 </bookmark>
-<h1 id="hd_id3153127"><link href="text/sbasic/shared/03030105.xhp" name="WeekDay Function">WeekDay Function (BASIC)</link></h1>
-<paragraph role="paragraph" id="par_id3146795" xml-lang="en-US">Returns the number corresponding to the weekday represented by a serial date number that is generated by the DateSerial or the DateValue function.</paragraph>
+
+<h1 id="hd_id3153127"><variable id="WeekDay_H1"><link href="text/sbasic/shared/03030105.xhp" name="WeekDay Function">WeekDay Function</link></variable></h1>
+<paragraph role="paragraph" id="par_id3146795" xml-lang="en-US">This function returns the number corresponding to the weekday represented by a serial date number that is generated by the <literal>DateSerial</literal> or the <literal>DateValue</literal> functions.</paragraph>
 </section>
+<note id="par_id91620239579003">This help page describes the <literal>WeekDay</literal> function used in Basic scripts. If you are interested in the <literal>WeekDay</literal> function used in %PRODUCTNAME Calc, refer to <link href="text/scalc/01/func_weekday.xhp" name="WeekDay_Calc Function">this help page</link>.</note>
 <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
 <bascode>
-<paragraph role="bascode" id="par_id3149655" xml-lang="en-US">WeekDay (Number)</paragraph>
+  <paragraph role="bascode" id="par_id3149655" xml-lang="en-US">WeekDay (SerialDate, [FirstDayOfWeek])</paragraph>
 </bascode>
-<embed href="text/sbasic/shared/00000003.xhp#functvalue"/>
-<paragraph role="paragraph" id="par_id3154125" xml-lang="en-US">Integer</paragraph>
 <embed href="text/sbasic/shared/00000003.xhp#functparameters"/>
 <paragraph role="paragraph" id="par_id3151042" xml-lang="en-US">
-<emph>Number:</emph> Integer expression that contains the serial date number that is used to calculate the day of the week (1-7).</paragraph>
-<paragraph role="paragraph" id="par_id3159254" xml-lang="en-US">The following example determines the day of the week using the WeekDay function when you enter a date.</paragraph>
+<emph>SerialDate:</emph> Integer expression that contains the serial date number that is used to calculate the day of the week.</paragraph>
+<paragraph role="paragraph" id="par_id351619718411921">
+<emph>FirstDayOfWeek:</emph> Integer value indicating which weekday should be considered as the first day of the week. The default value is <emph>0</emph>, meaning that the system locale settings are used to determine the first day of the week.</paragraph>
+<paragraph role="paragraph" id="par_id411619718769819">The parameter <emph>FirstDayOfWeek</emph> accepts values ranging from 0 to 7. The table below describes the meaning of each possible value:</paragraph>
+<table id="tab_id191619718816238">
+   <tablerow>
+       <tablecell>
+           <paragraph id="par_id651619719561092" role="tablehead">Value</paragraph>
+       </tablecell>
+       <tablecell>
+           <paragraph id="par_id251619718816238" role="tablehead">VBA Constant</paragraph>
+       </tablecell>
+       <tablecell>
+           <paragraph id="par_id711619718816238" role="tablehead">Description</paragraph>
+       </tablecell>
+   </tablerow>
+   <tablerow>
+       <tablecell>
+           <paragraph id="par_id731619718847838" role="tablecontent" localize="false">0</paragraph>
+       </tablecell>
+       <tablecell>
+           <paragraph id="par_id731619718847702" role="tablecontent" localize="false">vbUseSystemDayOfWeek</paragraph>
+       </tablecell>
+       <tablecell>
+           <paragraph id="par_id521619718818972" role="tablecontent">Use system locale settings</paragraph>
+       </tablecell>
+   </tablerow>
+   <tablerow>
+       <tablecell>
+           <paragraph id="par_id821619719164117" role="tablecontent" localize="false">1</paragraph>
+       </tablecell>
+       <tablecell>
+           <paragraph id="par_id731619718847885" role="tablecontent" localize="false">vbSunday</paragraph>
+       </tablecell>
+       <tablecell>
+           <paragraph id="par_id581619719174897" role="tablecontent">Sunday (default)</paragraph>
+       </tablecell>
+   </tablerow>
+   <tablerow>
+       <tablecell>
+           <paragraph id="par_id821619719164241" role="tablecontent" localize="false">2</paragraph>
+       </tablecell>
+       <tablecell>
+           <paragraph id="par_id731619718844633" role="tablecontent" localize="false">vbMonday</paragraph>
+       </tablecell>
+       <tablecell>
+           <paragraph id="par_id581619719173258" role="tablecontent">Monday</paragraph>
+       </tablecell>
+   </tablerow>
+   <tablerow>
+       <tablecell>
+           <paragraph id="par_id821619719168871" role="tablecontent" localize="false">3</paragraph>
+       </tablecell>
+       <tablecell>
+           <paragraph id="par_id731619718840122" role="tablecontent" localize="false">vbTuesday</paragraph>
+       </tablecell>
+       <tablecell>
+           <paragraph id="par_id581619719174633" role="tablecontent">Tuesday</paragraph>
+       </tablecell>
+   </tablerow>
+   <tablerow>
+       <tablecell>
+           <paragraph id="par_id821619719162897" role="tablecontent" localize="false">4</paragraph>
+       </tablecell>
+       <tablecell>
+           <paragraph id="par_id731619718843362" role="tablecontent" localize="false">vbWednesday</paragraph>
+       </tablecell>
+       <tablecell>
+           <paragraph id="par_id581619719173641" role="tablecontent">Wednesday</paragraph>
+       </tablecell>
+   </tablerow>
+   <tablerow>
+       <tablecell>
+           <paragraph id="par_id821619719168022" role="tablecontent" localize="false">5</paragraph>
+       </tablecell>
+       <tablecell>
+           <paragraph id="par_id731619718849336" role="tablecontent" localize="false">vbThursday</paragraph>
+       </tablecell>
+       <tablecell>
+           <paragraph id="par_id581619719170014" role="tablecontent">Thursday</paragraph>
+       </tablecell>
+   </tablerow>
+   <tablerow>
+       <tablecell>
+           <paragraph id="par_id821619719164776" role="tablecontent" localize="false">6</paragraph>
+       </tablecell>
+       <tablecell>
+           <paragraph id="par_id731619718849699" role="tablecontent" localize="false">vbFriday</paragraph>
+       </tablecell>
+       <tablecell>
+           <paragraph id="par_id581619719174271" role="tablecontent">Friday</paragraph>
+       </tablecell>
+   </tablerow>
+   <tablerow>
+       <tablecell>
+           <paragraph id="par_id821619719169044" role="tablecontent" localize="false">7</paragraph>
+       </tablecell>
+       <tablecell>
+           <paragraph id="par_id731619718849001" role="tablecontent" localize="false">vbSaturday</paragraph>
+       </tablecell>
+       <tablecell>
+           <paragraph id="par_id581619719176055" role="tablecontent">Saturday</paragraph>
+       </tablecell>
+   </tablerow>
+</table>
+<note id="par_id451619720094202">The VBA constants listed above are only available if VBA support has been enabled. For more information, read the <link href="text/sbasic/shared/03103350.xhp" name="VBASupport_Statement">VBASupport Statement</link> help page.</note>
+
+<embed href="text/sbasic/shared/00000003.xhp#functvalue"/>
+<paragraph role="paragraph" id="par_id3154125" xml-lang="en-US">Integer</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"/>
+<paragraph role="paragraph" id="par_id3159254" xml-lang="en-US">The following example uses the function <literal>Now()</literal> to determine the current weekday.</paragraph>
 <bascode>
-<paragraph role="bascode" id="par_id3145749" xml-lang="en-US" localize="false">Sub ExampleWeekDay</paragraph>
-<paragraph role="bascode" id="par_id3147426" xml-lang="en-US" localize="false">Dim sDay As String</paragraph>
-<paragraph role="bascode" id="par_id3148576" xml-lang="en-US">' Return And display the day of the week</paragraph>
-<paragraph role="bascode" id="par_id3155412" xml-lang="en-US" localize="false">    Select Case WeekDay( Now )</paragraph>
-<paragraph role="bascode" id="par_id3155306" xml-lang="en-US" localize="false">        Case 1</paragraph>
-<paragraph role="bascode" id="par_id3151117" xml-lang="en-US">            sDay="Sunday"</paragraph>
-<paragraph role="bascode" id="par_id3152460" xml-lang="en-US" localize="false">        Case 2</paragraph>
-<paragraph role="bascode" id="par_id3153952" xml-lang="en-US">            sDay="Monday"</paragraph>
-<paragraph role="bascode" id="par_id3149666" xml-lang="en-US" localize="false">        Case 3</paragraph>
-<paragraph role="bascode" id="par_id3153157" xml-lang="en-US">            sDay="Tuesday"</paragraph>
-<paragraph role="bascode" id="par_id3154730" xml-lang="en-US" localize="false">        Case 4</paragraph>
-<paragraph role="bascode" id="par_id3154942" xml-lang="en-US">            sDay="Wednesday"</paragraph>
-<paragraph role="bascode" id="par_id3145799" xml-lang="en-US" localize="false">        Case 5</paragraph>
-<paragraph role="bascode" id="par_id3155416" xml-lang="en-US">            sDay="Thursday"</paragraph>
-<paragraph role="bascode" id="par_id3150716" xml-lang="en-US" localize="false">        Case 6</paragraph>
-<paragraph role="bascode" id="par_id3154015" xml-lang="en-US">            sDay="Friday"</paragraph>
-<paragraph role="bascode" id="par_id3146971" xml-lang="en-US" localize="false">        Case 7</paragraph>
-<paragraph role="bascode" id="par_id3153707" xml-lang="en-US">            sDay="Saturday"</paragraph>
-<paragraph role="bascode" id="par_id3155065" xml-lang="en-US" localize="false">    End Select</paragraph>
-<paragraph role="bascode" id="par_id3148993" xml-lang="en-US">    MsgBox "" + sDay,64,"Today Is"</paragraph>
-<paragraph role="bascode" id="par_id3149019" xml-lang="en-US" localize="false">End Sub</paragraph>
+<paragraph role="bascode" id="par_id3145749" localize="false">Sub ExampleWeekDay</paragraph>
+<paragraph role="bascode" id="par_id3147426" localize="false">    Dim sDay As String</paragraph>
+<paragraph role="bascode" id="par_id3148576">    ' Return And display the day of the week</paragraph>
+<paragraph role="bascode" id="par_id3155412" localize="false">    Select Case WeekDay( Now )</paragraph>
+<paragraph role="bascode" id="par_id3151117">            Case 1: sDay="Sunday"</paragraph>
+<paragraph role="bascode" id="par_id3153952">            Case 2: sDay="Monday"</paragraph>
+<paragraph role="bascode" id="par_id3153157">            Case 3: sDay="Tuesday"</paragraph>
+<paragraph role="bascode" id="par_id3154942">            Case 4: sDay="Wednesday"</paragraph>
+<paragraph role="bascode" id="par_id3155416">            Case 5: sDay="Thursday"</paragraph>
+<paragraph role="bascode" id="par_id3154015">            Case 6: sDay="Friday"</paragraph>
+<paragraph role="bascode" id="par_id3153707">            Case 7: sDay="Saturday"</paragraph>
+<paragraph role="bascode" id="par_id3155065" localize="false">    End Select</paragraph>
+<paragraph role="bascode" id="par_id3148993">    MsgBox "" + sDay,64,"Today Is"</paragraph>
+<paragraph role="bascode" id="par_id3149019" localize="false">End Sub</paragraph>
 </bascode>
+<paragraph role="paragraph" id="par_id891619721286262">The following example illustrates the use <emph>FirstDayOfWeek</emph> parameter, assuming that Tuesday is the first day of the week.</paragraph>
+<bascode>
+  <paragraph role="bascode" localize="false" id="bas_id71619721723893">Dim someDay As Long</paragraph>
+  <paragraph role="bascode" id="bas_id791619721724107">' The date January 1st 2021 was a Friday</paragraph>
+  <paragraph role="bascode" localize="false" id="bas_id441619721724360">someDay = DateSerial(2021, 01, 01)</paragraph>
+  <paragraph role="bascode" id="bas_id991619721724568">' Prints "6" assuming Sunday is the first day of the week</paragraph>
+  <paragraph role="bascode" localize="false" id="bas_id291619721724784">MsgBox WeekDay(someDay)</paragraph>
+  <paragraph role="bascode" id="bas_id31619721725024">' Prints "4" assuming Tuesday is the first day of the week</paragraph>
+  <paragraph role="bascode" localize="false" id="bas_id301619721725289">MsgBox WeekDay(someDay, 3)</paragraph>
+</bascode>
+
+<section id="relatedtopics">
+  <embed href="text/sbasic/shared/03030101.xhp#DateSerial_H1"/>
+  <embed href="text/sbasic/shared/03030102.xhp#DateValue_H1"/>
+  <embed href="text/sbasic/shared/03030203.xhp#Now_H1"/>
+  <embed href="text/scalc/01/func_weekday.xhp#weekday"/>
+</section>
 </body>
 </helpdocument>
diff --git a/source/text/sbasic/shared/03030203.xhp b/source/text/sbasic/shared/03030203.xhp
index 4d8a83ce5e..4a9d7c6323 100644
--- a/source/text/sbasic/shared/03030203.xhp
+++ b/source/text/sbasic/shared/03030203.xhp
@@ -32,27 +32,27 @@
   <bookmark_value>Now function</bookmark_value>
 </bookmark>
 
-<paragraph id="hd_id3149416" role="heading" level="1" xml-lang="en-US"><link href="text/sbasic/shared/03030203.xhp" name="Now Function">Now Function</link></paragraph>
+<h1 id="hd_id641619720735711"><variable id="Now_H1"><link href="text/sbasic/shared/03030203.xhp" name="Now Function">Now Function</link></variable></h1>
 <paragraph id="par_id3149670" role="paragraph" xml-lang="en-US">Returns the current system date and time as a <emph>Date</emph> value.</paragraph>
 </section>
 
-<paragraph id="hd_id3149456" role="heading" level="2" xml-lang="en-US">Syntax:</paragraph>
+<embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
 <bascode>
 <paragraph id="par_id3149655" role="bascode" localize="false" xml-lang="en-US">Now</paragraph>
 </bascode>
 
-<paragraph id="hd_id3154366" role="heading" level="2" xml-lang="en-US">Return value:</paragraph>
+<embed href="text/sbasic/shared/00000003.xhp#functvalue"/>
 <paragraph id="par_id3154909" role="paragraph" xml-lang="en-US">Date</paragraph>
 
-<paragraph id="hd_id3147229" role="heading" level="2" xml-lang="en-US">Example:</paragraph>
+<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
 <bascode>
-<paragraph id="par_idm1341594784" role="bascode" localize="false" xml-lang="en-US">Sub ExampleNow</paragraph>
-<paragraph id="par_id3150870" role="bascode" xml-lang="en-US">    MsgBox "It is now " &amp; Now</paragraph>
-<paragraph id="par_idm1341591760" role="bascode" localize="false" xml-lang="en-US">End Sub</paragraph>
+  <paragraph id="par_idm1341594784" role="bascode" localize="false" xml-lang="en-US">Sub ExampleNow</paragraph>
+  <paragraph id="par_id3150870" role="bascode" xml-lang="en-US">    MsgBox "It is now " &amp; Now</paragraph>
+  <paragraph id="par_idm1341591760" role="bascode" localize="false" xml-lang="en-US">End Sub</paragraph>
 </bascode>
 
 <note id="par_id491610993401822">The <literal>Now</literal> function measures time in seconds. To measure time in milliseconds use the <link href="text/sbasic/shared/03/sf_timer.xhp" name="ScriptForge.Timer service"><literal>Timer</literal> service</link>.</note>
-  
+
 <section id="relatedtopics">
   <paragraph role="paragraph" id="par_id531610970649205"><embedvar href="text/sbasic/shared/03/sf_timer.xhp#TimerService"/></paragraph>
 </section>