Precisions about OS recognition in scripts

plus a few invitations to go Python
Change-Id: I0c58b9f35638c0d609727e6ef4affffac8fce971
Reviewed-on: https://gerrit.libreoffice.org/c/help/+/183441
Reviewed-by: Alain Romedenne <alain.romedenne@libreoffice.org>
Tested-by: Jenkins

4 files changed, 64 insertions, 51 deletions

diff --git a/source/text/sbasic/shared/03/sf_basic.xhp b/source/text/sbasic/shared/03/sf_basic.xhp
index 67c2fcc94a..81536f5fd6 100644
--- a/source/text/sbasic/shared/03/sf_basic.xhp
+++ b/source/text/sbasic/shared/03/sf_basic.xhp
@@ -9,7 +9,7 @@
  *
 -->
 <meta>
-  <topic id="SF_Document" indexer="include" status="PUBLISH">
+  <topic id="SF_Basic" indexer="include" status="PUBLISH">
     <title id="tit" xml-lang="en-US">ScriptForge.Basic service</title>
     <filename>/text/sbasic/shared/03/sf_basic.xhp</filename>
   </topic>
@@ -158,10 +158,10 @@
              <link href="text/sbasic/shared/03/sf_basic.xhp#CDate">CDate</link><br/>
              <link href="text/sbasic/shared/03/sf_basic.xhp#CDateFromUnoDateTime">CDateFromUnoDateTime</link><br/>
              <link href="text/sbasic/shared/03/sf_basic.xhp#CDateToUnoDateTime">CDateToUnoDateTime</link><br/>
-             <link href="text/sbasic/shared/03/sf_basic.xhp#ConvertFromUrl">ConvertFromUrl</link><br/>
-             <link href="text/sbasic/shared/03/sf_basic.xhp#ConvertToUrl">ConvertToUrl</link><br/>
+             <link href="text/sbasic/shared/03/sf_basic.xhp#ConvertFromUrl">ConvertFromUrl</link> (*)<br/>
+             <link href="text/sbasic/shared/03/sf_basic.xhp#ConvertToUrl">ConvertToUrl</link> (*)<br/>
              <link href="text/sbasic/shared/03/sf_basic.xhp#CreateUnoService">CreateUnoService</link><br/>
-             <link href="text/sbasic/shared/03/sf_basic.xhp#CreateUnoStruct">CreateUnoStruct</link><br/>
+             <link href="text/sbasic/shared/03/sf_basic.xhp#CreateUnoStruct">CreateUnoStruct</link> (*)<br/>
              <link href="text/sbasic/shared/03/sf_basic.xhp#DateAdd">DateAdd</link><br/>
            </paragraph>
        </tablecell>
@@ -172,8 +172,8 @@
              <link href="text/sbasic/shared/03/sf_basic.xhp#DateValue">DateValue</link><br/>
              <link href="text/sbasic/shared/03/sf_basic.xhp#Format">Format</link><br/>
              <link href="text/sbasic/shared/03/sf_basic.xhp#GetDefaultContext">GetDefaultContext</link><br/>
-             <link href="text/sbasic/shared/03/sf_basic.xhp#GetGuiType">GetGuiType</link><br/>
-             <link href="text/sbasic/shared/03/sf_basic.xhp#GetPathSeparator">GetPathSeparator</link><br/>
+             <link href="text/sbasic/shared/03/sf_basic.xhp#GetGuiType">GetGuiType</link> (*)<br/>
+             <link href="text/sbasic/shared/03/sf_basic.xhp#GetPathSeparator">GetPathSeparator</link> (*)<br/>
              <link href="text/sbasic/shared/03/sf_basic.xhp#GetSystemTicks">GetSystemTicks</link><br/>
            </paragraph>
        </tablecell>
@@ -181,8 +181,8 @@
            <paragraph id="par_id761611086279903" role="tablecontent" localize="false">
              <link href="text/sbasic/shared/03/sf_basic.xhp#BasicLibraries">GlobalScope.BasicLibraries</link><br/>
              <link href="text/sbasic/shared/03/sf_basic.xhp#DialogLibraries">GlobalScope.DialogLibraries</link><br/>
-             <link href="text/sbasic/shared/03/sf_basic.xhp#InputBox">InputBox</link><br/>
-             <link href="text/sbasic/shared/03/sf_basic.xhp#MsgBox">MsgBox</link><br/>
+             <link href="text/sbasic/shared/03/sf_basic.xhp#InputBox">InputBox</link> (*)<br/>
+             <link href="text/sbasic/shared/03/sf_basic.xhp#MsgBox">MsgBox</link> (*)<br/>
              <link href="text/sbasic/shared/03/sf_basic.xhp#Now">Now</link><br/>
              <link href="text/sbasic/shared/03/sf_basic.xhp#RGB">RGB</link><br/>
              <link href="text/sbasic/shared/03/sf_basic.xhp#Xray">Xray</link><br/><br/>
@@ -191,6 +191,7 @@
    </tablerow>
   </table>
   </section>
+  <note id="par_id891743424581473">Python alternatives exist for methods marked with <emph>(*)</emph>.</note>
 
 <section id="CDate">
   <comment> CDate ------------------------------------------------------------------------- </comment>
@@ -261,7 +262,6 @@
     <paragraph role="pycode" localize="false" id="pyc_id191621952701458">bas.MsgBox(str(uno_date.Year) + "-" + str(uno_date.Month) + "-" + str(uno_date.Day))</paragraph>
   </pycode>
 </section>
-
 <section id="ConvertFromUrl">
   <comment> ConvertFromUrl ------------------------------------------------------------------------- </comment>
   <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919969883">
@@ -277,9 +277,15 @@
   <paragraph role="paragraph" id="par_id81618502493505">A system path file name.</paragraph>
   <embed href="text/sbasic/shared/00000003.xhp#functexample"/>
   <pycode>
-    <paragraph role="pycode" localize="false" id="pyc_id41158919969836">filename = bas.ConvertFromUrl( "file:///C:/Program%20Files%20(x86)/LibreOffice/News.txt")</paragraph>
+    <paragraph role="pycode" localize="false" id="pyc_id41158919969836">filename = bas.ConvertFromUrl( "file:///C:/Program%20Files%20(x86)/LibreOffice/News.txt" )</paragraph>
     <paragraph role="pycode" localize="false" id="pyc_id881611147617212">bas.MsgBox(filename)</paragraph>
   </pycode>
+  <tip id="par_id51743414232819"><link href="text/sbasic/python/python_programming.xhp">uno module</link> fileUrlToSystemPath() method returns a system path using an identical syntax.</tip>
+  <pycode>
+    <paragraph role="pycode" id="pyc_id731743414363054">import uno</paragraph>
+    <paragraph role="pycode" id="pyc_id541743414376664">filename = uno.fileUrlToSystemPath( "file:///C:/Program%20Files%20(x86)/LibreOffice/News.txt" )</paragraph>
+    <paragraph role="pycode" localize="false" id="pyc_id882721147617212">bas.MsgBox(filename)</paragraph>
+  </pycode>
 </section>
 
 <section id="ConvertToUrl">
@@ -297,9 +303,15 @@
   <paragraph role="paragraph" id="par_id61658101307414">A <literal>file:</literal> URL as a string.</paragraph>
   <embed href="text/sbasic/shared/00000003.xhp#functexample"/>
   <pycode>
-    <paragraph role="pycode" localize="false" id="pyc_id891985200121516">url = bas.ConvertToUrl( 'C:\Program Files(x86)\LibreOffice\News.txt')</paragraph>
+    <paragraph role="pycode" localize="false" id="pyc_id891985200121516">url = bas.ConvertToUrl( 'C:\Program Files(x86)\LibreOffice\News.txt' )</paragraph>
     <paragraph role="pycode" localize="false" id="pyc_id51589200605125">bas.MsgBox(url)</paragraph>
   </pycode>
+  <tip id="par_id51744524232819"><link href="text/sbasic/python/python_programming.xhp">uno module</link> systemPathToFileUrl() method returns a file URL for the given system path.</tip>
+  <pycode>
+    <paragraph role="pycode" id="pyc_id742843414363054">from uno import systemPathToFileUrl as ConvertToUrl</paragraph>
+    <paragraph role="pycode" id="pyc_id552843414376664">filename = ConvertToUrl( 'C:\Program Files(x86)\LibreOffice\News.txt' )</paragraph>
+    <paragraph role="pycode" localize="false" id="pyc_id992611147617212">bas.MsgBox(filename)</paragraph>
+  </pycode>
 </section>
 
 <section id="CreateUnoService">
@@ -334,6 +346,12 @@
   <pycode>
     <paragraph role="pycode" localize="false" id="pyc_id891589200121516">date_struct = CreateUnoStruct('com.sun.star.util.DateTime')</paragraph>
   </pycode>
+  <tip id="par_id51743424332819"><link href="text/sbasic/python/python_programming.xhp">uno module</link> createUnoStruct() method creates an instance of a Uno structure type.</tip>
+  <pycode>
+    <paragraph role="pycode" id="pyc_id731754514363054">import uno</paragraph>
+    <paragraph role="pycode" id="pyc_id541754514376664">p = uno.createUnoStruct( 'com.sun.star.beans.Property' )</paragraph>
+    <paragraph role="pycode" localize="false" id="pyc_id882722257617212">bas.MsgBox(p)</paragraph>
+  </pycode>
 </section>
 
 <section id="DateAdd">
@@ -480,6 +498,7 @@
   <pycode>
     <paragraph role="pycode" localize="false" id="pyc_id154389205147164">n = bas.GetGuiType()</paragraph>
   </pycode>
+  <embed href="text/sbasic/shared/GetPathSeparator.xhp#PlatformID"/>
 </section>
 
 <section id="GetPathSeparator">
diff --git a/source/text/sbasic/shared/03/sf_platform.xhp b/source/text/sbasic/shared/03/sf_platform.xhp
index e488d21322..387d92a90d 100644
--- a/source/text/sbasic/shared/03/sf_platform.xhp
+++ b/source/text/sbasic/shared/03/sf_platform.xhp
@@ -413,7 +413,7 @@
         </tablerow>
       </table>
     </section>
-
+    <note id="par_id951743155374013">Extensive operating system name identification is available from <link href="text/scalc/01/04060104.xhp#bm_id3691824">INFO("system")</link> Calc formula.</note>
   <embed href="text/sbasic/shared/00000003.xhp#functexample"/>
   <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/>
   <paragraph role="paragraph" id="par_id311633022159446">The following examples in Basic and Python illustrate how to use the <literal>Fonts</literal> property to write the names of all available fonts to the current Calc sheet starting at cell "A1":</paragraph>
diff --git a/source/text/sbasic/shared/03132100.xhp b/source/text/sbasic/shared/03132100.xhp
index b41e818827..ea7d6e3e05 100644
--- a/source/text/sbasic/shared/03132100.xhp
+++ b/source/text/sbasic/shared/03132100.xhp
@@ -20,37 +20,33 @@
  -->
 
 <meta>
-      <topic id="textsbasicshared03132100xml" indexer="include" status="PUBLISH">
-         <title xml-lang="en-US" id="tit">GetGuiType Function</title>
-         <filename>/text/sbasic/shared/03132100.xhp</filename>
-      </topic>
-   </meta>
+  <topic id="textsbasicshared03132100xml" indexer="include" status="PUBLISH">
+    <title xml-lang="en-US" id="tit">GetGuiType Function</title>
+    <filename>/text/sbasic/shared/03132100.xhp</filename>
+  </topic>
+</meta>
    <body>
-      <section id="getguitype">
-<bookmark xml-lang="en-US" branch="index" id="bm_id3147143"><bookmark_value>GetGuiType function</bookmark_value>
-</bookmark>
-<h1 id="hd_id3155310"><variable id="getguitype2"><link href="text/sbasic/shared/03132100.xhp">GetGuiType Function</link></variable></h1>
-         <paragraph xml-lang="en-US" id="par_id3152459" role="paragraph">Returns a numerical value that specifies the graphical user interface.</paragraph>
-      </section>
-      <paragraph xml-lang="en-US" id="par_id3153323" role="paragraph">This function is only provided for downward compatibility to previous versions. The return value is not defined in client-server environments.</paragraph>
+<section id="getguitype">
+   <bookmark branch="index" id="bm_id3147143"><bookmark_value>GetGuiType function</bookmark_value></bookmark>
+   <h1 id="hd_id3155310"><variable id="getguitype2"><link href="text/sbasic/shared/03132100.xhp">GetGuiType Function</link></variable></h1>
+   <paragraph id="par_id3152459" role="paragraph">Returns a numerical value that specifies the graphical user interface.</paragraph>
+</section>
+      <paragraph id="par_id3153323" role="paragraph">This function is only provided for downward compatibility to previous versions. The return value is not defined in client-server environments.</paragraph>
+      <embed href="text/sbasic/shared/GetPathSeparator.xhp#PlatformID"/>
       <h2 id="hd_id3154894">Syntax:</h2>
       <bascode>
-<paragraph xml-lang="en-US" id="par_id3147143" role="bascode" localize="false">GetGUIType()</paragraph>
-</bascode>
+         <paragraph id="par_id3147143" role="bascode" localize="false">GetGUIType()</paragraph>
+      </bascode>
       <h2 id="hd_id3149346">Return value:</h2>
       <paragraph xml-lang="en-US" id="par_id3153748" role="paragraph">Integer</paragraph>
       <h2 id="hd_id3149177">Return values:</h2>
-      <paragraph xml-lang="en-US" id="par_id3147242" role="paragraph">1: Windows</paragraph><comment>removed 3: Mac OS, see i95717</comment>
-<paragraph xml-lang="en-US" id="par_id3156152" role="paragraph">4: UNIX</paragraph>
+      <paragraph id="par_id3147242" role="paragraph">1: Windows</paragraph><comment>removed 3: Mac OS, see i95717</comment>
+      <paragraph id="par_id3156152" role="paragraph">4: UNIX</paragraph>
       <h2 id="hd_id3148685">Example:</h2>
-<bascode>
-      <paragraph xml-lang="en-US" id="par_id3149233" role="bascode" localize="false">Sub ExampleEnvironment</paragraph>
-      <paragraph xml-lang="en-US" id="par_id3145609" role="bascode" localize="false">    MsgBox GetGUIType</paragraph>
-      <paragraph xml-lang="en-US" id="par_id3145069" role="bascode" localize="false">End Sub</paragraph>
-</bascode>
-      <section id="relatedtopics">
-         <embed href="text/sbasic/python/python_platform.xhp#pythonplatform"/>
-      </section>
+      <bascode>
+         <paragraph id="par_id3149233" role="bascode" localize="false">Sub ExampleEnvironment</paragraph>
+         <paragraph id="par_id3145609" role="bascode" localize="false">    MsgBox GetGUIType</paragraph>
+         <paragraph id="par_id3145069" role="bascode" localize="false">End Sub</paragraph>
+      </bascode>
    </body>
 </helpdocument>
-
diff --git a/source/text/sbasic/shared/GetPathSeparator.xhp b/source/text/sbasic/shared/GetPathSeparator.xhp
index f807730adb..170576cce1 100644
--- a/source/text/sbasic/shared/GetPathSeparator.xhp
+++ b/source/text/sbasic/shared/GetPathSeparator.xhp
@@ -25,7 +25,7 @@
     <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
     <paragraph role="code"  id="N0005" localize="false">GetPathSeparator()</paragraph>
     <embed href="text/sbasic/shared/00000003.xhp#functvalue"/>
-    <paragraph role="paragraph" id="par_id481542894937950" xml-lang="en-US" localize="false">String</paragraph>
+    <paragraph role="paragraph" id="par_id481542894937950" localize="false">String</paragraph>
     <list type="unordered">
         <listitem>
             <paragraph role="paragraph"  id="N0007" localize="false">&quot;\&quot; Windows</paragraph>
@@ -46,19 +46,17 @@
         <paragraph role="bascode" localize="false" id="N0015">    MsgBox GetPathSeparator()</paragraph>
         <paragraph role="bascode" localize="false" id="N0016">End Sub</paragraph>
     </bascode>
-    <section id="relatedtopics" >
-        <paragraph role="paragraph"  id="N0017">
-            It is recommended to use:
-        </paragraph>
-        <paragraph role="paragraph"  id="N0018">
-            <link href="text/sbasic/shared/03120313.xhp">ConvertFromURL</link> function to convert a file URL to a system file name.
-        </paragraph>
-        <paragraph role="paragraph"  id="N0019">
-            <link href="text/sbasic/shared/03120312.xhp">ConvertToURL</link> function to convert a system file name to a file URL.
-        </paragraph>
-        <paragraph role="paragraph"  id="N0020">
-            See also <link href="text/sbasic/shared/00000002.xhp">URL Notation</link>
-        </paragraph>
+    <section id="PlatformID">
+        <note id="par_id71743155051328">Wiser script instructions are available from <link href="text/sbasic/python/python_platform.xhp">Identifying the operating system</link> help page.</note>
+        <section id="SF_Calc">
+            <tip id="par_id951743155374013"><link href="text/sbasic/shared/03/sf_platform.xhp">&#8226; ScriptForge.Platform</link> service provides a collection of properties about the current execution environment and context, that include platform detection.<br/><br/>&#8226; Extensive operating system name identification is available from <link href="text/scalc/01/04060104.xhp#bm_id3691824">INFO("system")</link> Calc formula.</tip>
+        </section>
     </section>
+    <section id="relatedtopics" >
+        <paragraph role="paragraph" id="N0017">It is recommended to use:</paragraph>
+        <paragraph role="paragraph" id="N0018"><link href="text/sbasic/shared/03120313.xhp">ConvertFromURL</link> function to convert a file URL to a system file name.</paragraph>
+        <paragraph role="paragraph" id="N0019"><link href="text/sbasic/shared/03120312.xhp">ConvertToURL</link> function to convert a system file name to a file URL.</paragraph>
+        <paragraph role="paragraph"  id="N0020">See also <link href="text/sbasic/shared/00000002.xhp">URL Notation</link></paragraph>
+     </section>
 </body>
 </helpdocument>