From eea4d307ecbd8500bc429be7b0c05cf4097a5686 Mon Sep 17 00:00:00 2001
From: Alain Romedenne <pyoffice.romedenne@sfr.fr>
Date: Thu, 13 Dec 2018 15:06:45 -0200
Subject: More pages on Python scripts

Change-Id: I5d8db28da384f52ee835195d3eb889fde0fe33b3
Signed-off-by: Olivier Hallot <olivier.hallot@libreoffice.org>
Reviewed-on: https://gerrit.libreoffice.org/65117
Tested-by: Jenkins
---
 AllLangHelp_sbasic.mk                          |   3 +-
 Package_html_media.mk                          |   1 +
 source/media/helpimg/python/python_shell.png   | Bin 0 -> 34644 bytes
 source/text/sbasic/python/main0000.xhp         |   9 ++--
 source/text/sbasic/python/python_ide.xhp       |  13 ++++--
 source/text/sbasic/python/python_locations.xhp |  15 ++++---
 source/text/sbasic/python/python_shell.xhp     |  59 +++++++++++++++++++++++++
 7 files changed, 86 insertions(+), 14 deletions(-)
 create mode 100644 source/media/helpimg/python/python_shell.png
 create mode 100644 source/text/sbasic/python/python_shell.xhp

diff --git a/AllLangHelp_sbasic.mk b/AllLangHelp_sbasic.mk
index ec22b518ee..303228599f 100644
--- a/AllLangHelp_sbasic.mk
+++ b/AllLangHelp_sbasic.mk
@@ -364,8 +364,7 @@ $(eval $(call gb_AllLangHelp_add_helpfiles,sbasic,\
     helpcontent2/source/text/sbasic/python/main0000 \
     helpcontent2/source/text/sbasic/python/python_ide \
     helpcontent2/source/text/sbasic/python/python_locations \
-    helpcontent2/source/text/sbasic/shared/stardesktop \
-    helpcontent2/source/text/sbasic/shared/uno_objects \
+    helpcontent2/source/text/sbasic/python/python_shell \
 ))
 
 # vim: set noet sw=4 ts=4:
diff --git a/Package_html_media.mk b/Package_html_media.mk
index 798d9be1ac..1c31f353ef 100644
--- a/Package_html_media.mk
+++ b/Package_html_media.mk
@@ -284,6 +284,7 @@ $(eval $(call gb_Package_add_files_with_dir,helpcontent2_html_media,$(LIBO_SHARE
     helpimg/starmath/un21214.png \
     helpimg/starmath/un21215.png \
     helpimg/starmath/un21221.png \
+    helpimg/python/python_shell.png \
     helpimg/sw_paste_range.png \
     helpimg/sw_signatureline01.png \
     helpimg/sw_signatureline02.png \
diff --git a/source/media/helpimg/python/python_shell.png b/source/media/helpimg/python/python_shell.png
new file mode 100644
index 0000000000..afb1738a0f
Binary files /dev/null and b/source/media/helpimg/python/python_shell.png differ
diff --git a/source/text/sbasic/python/main0000.xhp b/source/text/sbasic/python/main0000.xhp
index 989ea22d0e..f83d1b72c6 100644
--- a/source/text/sbasic/python/main0000.xhp
+++ b/source/text/sbasic/python/main0000.xhp
@@ -8,7 +8,6 @@
     * file, You can obtain one at http://mozilla.org/MPL/2.0/.
     *
     -->
-
     <meta>
         <topic id="pythonmain0000" indexer="include" status="PUBLISH">
             <title id="tit" xml-lang="en-US">Python Scripts</title>
@@ -19,17 +18,21 @@
     <bookmark xml-lang="en-US" branch="index" id="bm_id491543348147708">
         <bookmark_value>macros;Python scripts</bookmark_value>
         <bookmark_value>Python;macros</bookmark_value>
+        <bookmark_value>APSO</bookmark_value>
+        <bookmark_value>Alternative Python Scripts Organizer</bookmark_value>
     </bookmark>
-    <paragraph id="hd_id3154232" role="heading" level="1" xml-lang="en-US"><link href="text/sbasic/python/main0000.xhp" name="$[officename] Python Scripts">%PRODUCTNAME Python Scripts Help</link></paragraph>
+    <h1 id="hd_id3154232"><variable id="pythonscriptshelp"><link href="text/sbasic/python/main0000.xhp" name="$[officename] Python Scripts">%PRODUCTNAME Python Scripts Help</link></variable></h1>
 
     <section id="pythonalt">
         <paragraph id="par_id3153894" role="paragraph" xml-lang="en-US">%PRODUCTNAME provides an Application Programming Interface (API) that allows controlling the $[officename] components with different programming languages by using the $[officename] Software Development Kit (SDK). For more information about the $[officename] API and the Software Development Kit, visit <link href="https://api.libreoffice.org/" name="api.libreoffice.org">https://api.libreoffice.org</link></paragraph>
         <paragraph id="par_id3147226" role="paragraph" xml-lang="en-US">This help section explains the most common Python script functions for %PRODUCTNAME. For more in-depth information please refer to the <link href="https://wiki.documentfoundation.org/Macros/Python_Design_Guide" name="wiki.documentfoundation.org PYTHON Guide">Designing &amp; Developing Python Applications</link> on the Wiki.</paragraph>
     </section>
     <embed href="text/shared/need_help.xhp#needhelp"/>
-    <paragraph id="hd_id3146957" role="heading" level="3" xml-lang="en-US">Working with Python Scripts in %PRODUCTNAME.</paragraph>
+    <h2 id="hd_id3146957">Working with Python Scripts in %PRODUCTNAME.</h2>
+    <paragraph role="paragraph" id="N0102">You can execute Python scripts choosing <menuitem>Tools - Macros – Run macro...</menuitem>. Editing scripts can be done with your preferred text editor. Python scripts are present in various locations detailed hereafter. You can refer to Programming examples for macros illustrating how to run Python interactive console from %PRODUCTNAME .</paragraph>
     <embed href="text/sbasic/python/python_ide.xhp#pythonideh1"/>
     <embed href="text/sbasic/python/python_locations.xhp#pythonlocations1"/>
+    <embed href="text/sbasic/python/python_shell.xhp#pythonshell1"/>
     <paragraph role="paragraph" id="par_id551543347858350" xml-lang="en-US">Programming with Python Scripts
     </paragraph>
     <paragraph role="paragraph" id="par_id861543347870798" xml-lang="en-US">Creating a dialog</paragraph>
diff --git a/source/text/sbasic/python/python_ide.xhp b/source/text/sbasic/python/python_ide.xhp
index 05645cc501..aa81a574c0 100644
--- a/source/text/sbasic/python/python_ide.xhp
+++ b/source/text/sbasic/python/python_ide.xhp
@@ -22,11 +22,18 @@
             <bookmark_value>python;IDE - integrated development environment</bookmark_value>
             <bookmark_value>python;editor</bookmark_value>
         </bookmark>
-        <paragraph id="hd_id151543348965464" role="heading" level="1" xml-lang="en-US"><variable id="pythonideh1"><link href="text/sbasic/python/python_ide.xhp" name="Python IDE Setup">Setting up an Integrated Development Environment (IDE) for Python</link></variable></paragraph>
+        <h1 id="hd_id151543348965464"><variable id="pythonideh1"><link href="text/sbasic/python/python_ide.xhp" name="Python IDE Setup">Setting up an Integrated Development Environment (IDE) for Python</link></variable></h1>
         <paragraph id="par_id541543348965465" role="paragraph" xml-lang="en-US">Writing Python macros requires extra configuration steps in order set an IDE of choice.</paragraph>
-
     </section>
     <embed href="text/shared/need_help.xhp#needhelp"/>
-    <paragraph role="paragraph" id="par_id341543353455014" xml-lang="en-US">Unlike Basic language macros development in %PRODUCTNAME, writing Python macros requires extra configuration steps in order to build your IDE of choice. In return you are provided with flexible design experience built upon your Python developing preferences or habits. Hereafter are IDE setup guidelines that range from beginner to advanced user.</paragraph>
+
+    <paragraph role="paragraph" id="N0106">Unlike Basic language macros development in %PRODUCTNAME, developing Python scripts for %PRODUCTNAME requires to configure an external Integrated Development Environment (IDE). Multiple IDEs are available that range from beginners to advanced Python coders. While using a Python IDE programmers benefit from numerous features such as syntax highlighting, code folding, class browsing, code completion, coding standard enforcement, test driven development, debugging, version control and many more. You can refer to <link href="https://wiki.documentfoundation.org/Macros/Python_Design_Guide" name ="external">Designing &amp; Developing Python Applications</link> on the Wiki for more in-depth information about the setup of a bridge between your IDE and a running instance %PRODUCTNAME.</paragraph>
+
+    <h2 id="hd_id761544698669786">The APSO Extension</h2>
+    <paragraph role="paragraph" id="N0104">The <link href="https://extensions.libreoffice.org/extensions/apso-alternative-script-organizer-for-python" name ="external">Alternative Python Script Organizer (APSO)</link> extension eases the edition of Python scripts, in particular when embedded in a document. Using APSO you can configure your preferred source code editor and start the integrated Python shell. Extensions exist that help inspect arbitrary UNO objects, refer to <link href="https://wiki.documentfoundation.org/Macros/Python_Design_Guide" name ="external">Designing &amp; Developing Python Applications</link> for additional details on such extensions.</paragraph>
+    <section id="relatedtopics">
+        <embed href="text/sbasic/python/main0000.xhp#pythonscriptshelp"/>
+    </section>
+
 </body>
 </helpdocument>
diff --git a/source/text/sbasic/python/python_locations.xhp b/source/text/sbasic/python/python_locations.xhp
index 24462b698e..eec6a0e852 100644
--- a/source/text/sbasic/python/python_locations.xhp
+++ b/source/text/sbasic/python/python_locations.xhp
@@ -17,7 +17,7 @@
     </meta>
     <body>
     <section id="pythonlocation">
-        <paragraph id="hd_id391543358231021" role="heading" level="1" xml-lang="en-US"><variable id="pythonlocations1"><link href="text/sbasic/python/python_locations.xhp" name="command_name">Python scripts Organization and Location</link></variable></paragraph>
+        <paragraph id="hd_id391543358231021" role="heading" level="1" xml-lang="en-US"><variable id="pythonlocations1"><link href="text/sbasic/python/python_locations.xhp" name="command_name">Python Scripts Organization and Location</link></variable></paragraph>
         <paragraph id="par_id771543358231022" role="paragraph" xml-lang="en-US">The Python script files are stored in the file system, in folders controlled by %PRODUCTNAME. The macros can be stared at installation, user or file level.</paragraph>
     </section>
     <embed href="text/shared/need_help.xhp#needhelp"/>
@@ -25,13 +25,13 @@
     <h3 id="hd_id591544049572647">%PRODUCTNAME Macros container</h3>
     <paragraph role="paragraph" id="par_id261544049064421">Existing macros in this location (container) were copied by the installation program and are available to every computer user, and any open document can access macros stored the container. You need administrative rights to store or edit macros here.</paragraph>
 
-    <paragraph role="paragraph" id="par_id861544210028670">The LibreOfficeDev Macros container location in the file system depends on the operating system:</paragraph>
+    <paragraph role="paragraph" id="par_id861544210028670">The %PRODUCTNAME  Macros container location in the file system depends on the operating system:</paragraph>
     <list type="unordered">
         <listitem>
-            <paragraph id="par_id191544210072242"  role="listitem">For Windows, <literal>C:\Program Files (x86)\LibreOffice\Basis\share\Scripts\python</literal>.</paragraph>
+            <paragraph id="par_id191544210072242"  role="listitem">For Windows,<br/><literal>C:\Program Files (x86)\LibreOffice\Basis\share\Scripts\python</literal>.</paragraph>
         </listitem>
         <listitem>
-            <paragraph id="par_id61544210078654"  role="listitem">For Linux and macOS, in <literal>$(Installation)/share/Scripts/python</literal>.</paragraph>
+            <paragraph id="par_id61544210078654"  role="listitem">For Linux and macOS,<br/><literal>$(Installation)/share/Scripts/python</literal>.</paragraph>
         </listitem>
     </list>
     <h3 id="hd_id861544049692222">My Macros</h3>
@@ -39,10 +39,10 @@
     <paragraph role="paragraph" id="par_id341544210187846">The My Macros container location is in the user space and depends on the operating system:</paragraph>
     <list type="unordered">
         <listitem>
-            <paragraph id="par_id381544210213190"  role="listitem">For <emph>Windows</emph>, in <literal>C:\Users\current-user\AppData\Roaming\libreoffice\4\user\Scripts\python</literal>.</paragraph>
+            <paragraph id="par_id381544210213190"  role="listitem">For <emph>Windows</emph>,<br/><literal>C:\Users\current-user\AppData\Roaming\libreoffice\4\user\Scripts\python</literal>.</paragraph>
         </listitem>
         <listitem>
-            <paragraph id="par_id691544210219850"  role="listitem">For <emph>Linux</emph> and <emph>macOS</emph>, in <literal>$(HOME)/.config/libreoffice/4/user/Scripts/python</literal>.</paragraph>
+            <paragraph id="par_id691544210219850"  role="listitem">For <emph>Linux</emph> and <emph>macOS</emph>,<br/><literal>$(HOME)/.config/libreoffice/4/user/Scripts/python</literal>.</paragraph>
         </listitem>
     </list>
     <h3 id="hd_id101544049707712">Document macros</h3>
@@ -55,5 +55,8 @@
     <paragraph role="paragraph" id="par_id161544209936743">A module is a python file in the library or the container. Create a module adding a file in the container.</paragraph>
     <h3 id="hd_id151544209895574">Python macros</h3>
     <paragraph role="paragraph" id="par_id61544209944591">A macro is a python object in the module.</paragraph>
+    <section id="relatedtopics">
+        <embed href="text/sbasic/python/main0000.xhp#pythonscriptshelp"/>
+    </section>
 </body>
 </helpdocument>
diff --git a/source/text/sbasic/python/python_shell.xhp b/source/text/sbasic/python/python_shell.xhp
new file mode 100644
index 0000000000..38e4a72c12
--- /dev/null
+++ b/source/text/sbasic/python/python_shell.xhp
@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<helpdocument version="1.0">
+    <!--
+    * This file is part of the LibreOffice project.
+    *
+    * This Source Code Form is subject to the terms of the Mozilla Public
+    * License, v. 2.0. If a copy of the MPL was not distributed with this
+    * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+    *
+    -->
+    <meta>
+        <topic id="python_shell" indexer="include" status="PUBLISH">
+            <title id="tit" xml-lang="en-US">Python Interactive Shell</title>
+            <filename>/text/sbasic/python/python_shell.xhp</filename>
+        </topic>
+    </meta>
+    <body>
+    <bookmark branch="index" id="N0117">
+        <bookmark_value>Python console</bookmark_value>
+        <bookmark_value>Python Interactive Shell</bookmark_value>
+    </bookmark>
+    <section id="pythonshell">
+        <paragraph role="heading" level="1" id="N0118"><variable id="pythonshell1"><link href="text/sbasic/python/python_shell.xhp" name="python shell">Running Python Interactive Console</link></variable></paragraph>
+    </section>
+    <paragraph role="paragraph" id="N0119">The Python interactive console, also known as Python interpreter or Python shell, provide programmers with a quick way to execute commands and try out and test code without creating a file. %PRODUCTNAME Python modules documentation can obtained from the terminal.</paragraph>
+    <paragraph role="paragraph" id="N0120"></paragraph>
+    <paragraph role="heading" level="2" id="N0121">Using a Basic macro:</paragraph>
+    <bascode>
+        <paragraph role="bascode" id="N0122">Sub interpreter_console</paragraph>
+        <paragraph role="bascode" id="N0123">    ps = CreateUnoService(&quot;com.sun.star.util.PathSettings&quot;)</paragraph>
+        <paragraph role="bascode" id="N0124">    install_path = ConvertFromURL(ps.Module)</paragraph>
+        <paragraph role="bascode" id="N0125">    Shell( install_path + GetPathSeparator() + &quot;python&quot; )</paragraph>
+        <paragraph role="bascode" id="N0126">End Sub</paragraph>
+    </bascode>
+    <paragraph role="heading" level="2" id="N0127">Using a Python macro:</paragraph>
+    <pycode>
+        <paragraph role="pycode" id="N0128"># -*- coding: utf-8 -*-</paragraph>
+        <paragraph role="pycode" id="N0129">from __future__ import unicode_literals</paragraph>
+        <paragraph role="pycode" id="N0130"></paragraph>
+        <paragraph role="pycode" id="N0131">import uno, os, subprocess</paragraph>
+        <paragraph role="pycode" id="N0132"></paragraph>
+        <paragraph role="pycode" id="N0133">def interpreter_console():</paragraph>
+        <paragraph role="pycode" id="N0134">    ctx = XSCRIPTCONTEXT.getComponentContext()</paragraph>
+        <paragraph role="pycode" id="N0135">    smgr = ctx.getServiceManager()</paragraph>
+        <paragraph role="pycode" id="N0136">    ps = smgr.createInstanceWithContext(&quot;com.sun.star.util.PathSettings&quot;, ctx)</paragraph>
+        <paragraph role="pycode" id="N0137">    install_path = uno.fileUrlToSystemPath(ps.Module)</paragraph>
+        <paragraph role="pycode" id="N0138">    pgm = install_path + os.sep + &quot;python&quot;  # Python shell/console path</paragraph>
+        <paragraph role="pycode" id="N0139">    subprocess.Popen(pgm)  # Start Python interactive Shell</paragraph>
+        <paragraph role="pycode" id="N0140"></paragraph>
+    </pycode>
+    <paragraph role="heading" level="2" id="N0141">Usage:</paragraph>
+    <paragraph role="paragraph" id="N0142">
+        <image src="media/helpimg/python/python_shell.png" id="N0143"><alt id="N0144">Python Interactive Console</alt></image>
+    </paragraph>
+    <section id="relatedtopics">
+        <embed href="text/sbasic/python/main0000.xhp#pythonscriptshelp"/>
+    </section>
+</body>
+</helpdocument>
-- 
cgit