documentation update

Author: ddmitov

CREDITS.md

@@ -74,23 +74,18 @@ https://wiki.qt.io/Open_Web_Page_in_QWebView
 
 https://forum.qt.io/topic/18879/relative-path-on-qmake-pro-file  
 https://forum.qt.io/topic/551/get-filename-without-extension  
-https://forum.qt.io/topic/45982/solved-is-there-a-problem-with-the-following-non-blocking-sleep-function  
 https://forum.qt.io/topic/3314/qwebelement-set-and-get-attribute  
 
-http://www.qtcentre.org/threads/25880-QWebView-prints-PDF-file-OK-with-QPrintDialog-only  
 http://www.qtcentre.org/threads/46016-Place-QMessageBox-on-middle-of-screen  
 http://www.qtcentre.org/threads/18146-String-operations-printing-to-stdout  
 http://www.qtcentre.org/threads/29363-Problem-with-QDir-cdUp()  
 http://www.qtcentre.org/threads/10661-QByteArray-to-QString  
-http://www.qtcentre.org/threads/28302-Passing-Command-line-arguments-to-a-Qt-application-in-linux  
-http://www.qtcentre.org/threads/22298-QMessageBox-Controlling-the-width  
 http://www.qtcentre.org/threads/29104-QMake-DEFINES  
 http://www.qtcentre.org/threads/48238-Call-a-JavaScript-function-from-C-using-QtWebkit  
 
 https://stackoverflow.com/questions/10666998/qwebkit-display-local-webpage  
 https://stackoverflow.com/questions/7402576/how-to-get-current-working-directory-in-a-qt-application  
 https://stackoverflow.com/questions/8026101/correct-way-to-quit-a-qt-program  
-https://stackoverflow.com/questions/8122094/qtwebkit-printing-issue-no-images-on-printed-page  
 https://stackoverflow.com/questions/12571895/save-open-dialog-localization-in-qt  
 https://stackoverflow.com/questions/6955281/how-to-stop-qhttp-qtwebkit-from-caching-pages  
 https://stackoverflow.com/questions/3211771/how-to-convert-int-to-qstring  
@@ -104,7 +99,6 @@ https://stackoverflow.com/questions/7228826/how-can-i-convert-qvariant-to-qstrin
 https://stackoverflow.com/questions/2580934/how-to-specify-different-debug-release-output-directories-in-qmake-pro-file  
 https://stackoverflow.com/questions/3348711/add-a-define-to-qmake-with-a-value  
 https://stackoverflow.com/questions/4515602/how-to-get-executable-name-in-qt  
-https://stackoverflow.com/questions/2781119/how-to-get-the-current-timestamp-in-qt  
 https://stackoverflow.com/questions/19505063/qt-javascript-execution-slow-unless-i-log-to-the-console  
 https://stackoverflow.com/questions/15864689/qmake-pre-build-step-before-any-compilation  
 https://stackoverflow.com/questions/17480984/qt-how-do-i-handle-the-event-of-the-user-pressing-the-x-close-button  
@@ -142,7 +136,6 @@ https://www.perlmonks.org/bare/?node_id=768448 "Permanently sort a hash"
 https://www.perlmonks.org/?node_id=27443 "Checking to see if a particular Module is installed"  
 https://www.perlmonks.org/?node_id=982572 "ScanDeps usage"  
 
-https://stackoverflow.com/questions/1725097/how-can-i-disable-terminal-polling-for-cpan-used-from-crontab  
 https://stackoverflow.com/questions/4510550/using-perl-how-do-i-decode-or-create-those-encodings-on-the-web  
 https://stackoverflow.com/questions/5741101/easy-way-to-print-perl-array-with-a-little-formatting  
 https://stackoverflow.com/questions/15210532/use-utf8-gives-me-wide-character-in-print  
@@ -151,7 +144,6 @@ https://stackoverflow.com/questions/229357/what-is-the-best-way-in-perl-to-copy-
 
 https://perlmaven.com/manipulating-perl-arrays  
 https://perlmaven.com/how-to-sort-a-hash-in-perl  
-https://perlmaven.com/recursive-subroutines  
 
 http://lauraliparulo.altervista.org/first-steps-in-sqlite-and-perl/  
 

README.md

@@ -21,16 +21,21 @@ Perl Executing Browser (PEB) is an HTML5 user interface for [Perl 5](https://www
   * [Runtime Requirements](./doc/REQUIREMENTS.md#runtime-requirements)
 * [CONSTANTS](./doc/CONSTANTS.md)
   * [Files and Folders](./doc/CONSTANTS.md#files-and-folders)
-  * [Functional Pseudo Filename](./doc/CONSTANTS.md#functional-pseudo-filename)
+  * [About URL](./doc/CONSTANTS.md#about-url)
 * [SETTINGS](./doc/SETTINGS.md)
   * [Application Filename](./doc/SETTINGS.md#application-filename)
-  * [HTML Page API](./doc/SETTINGS.md#html-page-api)
+  * [Global Settings API](./doc/SETTINGS.md#global-settings-api)
   * [Perl Scripts API](./doc/SETTINGS.md#perl-scripts-api)
-  * [Interactive Perl Scripts](./doc/SETTINGS.md#interactive-perl-scripts)
-  * [Selecting Files and Folders](./doc/SETTINGS.md#selecting-files-and-folders)
-* [LOGGING](./doc/LOGGING.md)
-* [PACKAGING](./doc/PACKAGING.md)
-  * [AppImage Support](./doc/PACKAGING.md#appimage-support)
+  * [Files and Folders Dialogs API](./doc/SETTINGS.md#files-and-folders-dialogs-api)
+* [INTERACTIVE PERL SCRIPTS](./doc/INTERACTIVE.md)
+  * [Requirements for Interactive Perl Scripts](./doc/INTERACTIVE.md#requirements-for-interactive-perl-scripts)
+  * [Examples of Interactive Perl Scripts](./doc/INTERACTIVE.md#examples-of-interactive-perl-scripts)
+* [APPIMAGE SUPPORT](./doc/APPIMAGE.md)
+  * [PEB AppImage Maker](./doc/APPIMAGE.md#peb-appimage-maker)
+  * [PEB AppImage Configuration Files](./doc/APPIMAGE.md#peb-appimage-configuration-files)
+  * [PEB AppImage Builder Docker Container](./doc/APPIMAGE.md#peb-appimage-builder-docker-container)
+  * [AppImageHub](./doc/APPIMAGE.md#appimagehub)
+* [Logging](./doc/LOGGING.md)
 * [History](#history)
 * [License](./LICENSE.md)
 * [Thanks and Credits](./CREDITS.md)

doc/APPIMAGE.md

@@ -0,0 +1,84 @@
+# Perl Executing Browser - AppImage Support
+
+## PEB AppImage Maker
+
+PEB or any PEB-based application can be easily packed as a 64-bit single-file Linux [AppImage](https://appimage.org/) executable by the [PEB AppImage Maker](https://github.com/ddmitov/perl-executing-browser/blob/master/sdk/appimage-maker.sh) script, which has two modes of operation:  
+
+* packing a Perl application together with a PEB executable, Qt libraries and a relocatable Perl distribution:  
+
+  ```bash
+  ./appimage-maker.sh --include-resources
+  ```
+
+  In this case, the PEB AppImage Maker invokes the [Perl Distribution Compactor](https://github.com/ddmitov/perl-executing-browser/blob/master/sdk/compactor.pl), which finds all dependencies of all Perl scripts in the ``{PEB_executable_directory}/resources/app`` directory and copies only the necessary Perl modules.
+
+  Perl Distribution Compactor depends on [Module::ScanDeps](https://metacpan.org/pod/Module::ScanDeps) and [File::Copy::Recursive](https://metacpan.org/pod/File::Copy::Recursive) CPAN modules, which are included in the ``{PEB_executable_directory}/sdk/lib`` directory.
+
+* packing only a PEB executable and its Qt libraries:  
+
+  ```bash
+  ./appimage-maker.sh --no-resources
+  ```
+
+  In this case, a PEB executable from an AppImage will try to find its application files and folders in the directory of the AppImage.  
+
+In both modes of operation, the PEB AppImage uses the [linuxdeployqt](https://github.com/probonopd/linuxdeployqt/releases/) tool to detect all Qt dependencies of PEB and build the final image.  
+
+The PEB AppImage Maker script must be started from the ``{PEB_executable_directory}/sdk`` directory.  
+
+## PEB AppImage Configuration Files
+
+``{PEB_executable_directory}/resources/app/appimage/{application_name}.desktop``  
+``{PEB_executable_directory}/resources/app/appimage/{application_name}.appdata.xml``  
+
+``{PEB_executable_directory}/resources/app/{application_name}.desktop``  
+is mandatory for any PEB-based application which will be packed by the PEB AppImage Maker.  
+A minimal example of а ``.desktop`` file is available [here](https://github.com/ddmitov/perl-executing-browser/blob/master/resources/app/peb-demo.desktop).  
+``Icon=app`` in the ``.desktop`` file must not be changed for the proper display of the application icon.  
+All registered categories in a ``.desktop`` file are available [here](https://standards.freedesktop.org/menu-spec/latest/apa.html).  
+Any ``.desktop`` file can be validated using the ``desktop-file-validate`` tool from the  ``desktop-file-utils`` package in all major Linux distributions.  
+
+The [AppStream Generator](http://output.jsbin.com/qoqukof) of [probonopd](https://github.com/probonopd) is the recommended tool for generating AppStream ``.appdata.xml`` files for PEB-based applications. An example AppStream file is available [here](https://github.com/ddmitov/perl-executing-browser/blob/master/resources/app/peb-demo.appdata.xml). An AppStream file is not mandatory, but is highly recommended.  
+
+Both PEB AppImage configuration files are put on their places in the AppImage directory tree structure by the [PEB AppImage Maker](https://github.com/ddmitov/perl-executing-browser/blob/master/sdk/appimage-maker.sh) script.  
+
+## PEB AppImage Builder Docker Container
+
+An easy building environment for PEB AppImage executables is the [PEB AppImage Builder Docker Container](https://github.com/ddmitov/perl-executing-browser/blob/master/sdk/Dockerfile).  
+To build it, type the following command in the PEB project root directory (the directory of the README.md):  
+
+```bash
+sudo docker build -t peb-appimage-builder .
+```
+
+To start the PEB AppImage Builder Docker Container, type the following command in the PEB project root directory:  
+
+```bash
+sudo docker container run --rm -it -v $(pwd):/opt --user $(id -u):$(id -g) peb-appimage-builder
+```
+
+When PEB AppImage Builder Docker Container is running, type:
+
+```bash
+cd /opt/sdk
+```
+
+To start the PEB AppImage Maker, type either:
+
+```bash
+./appimage-maker.sh --no-resources
+```
+
+or
+
+```bash
+./appimage-maker.sh --include-resources
+```
+
+To stop the PEB AppImage Builder Docker Container when AppImage building is complete:  
+<kbd>Ctrl</kbd> + <kbd>D</kbd>
+
+## AppImageHub
+
+Perl Executing Browser is also listed at the [AppImageHub](https://appimage.github.io/perl-executing-browser/).  
+Any authors of PEB-based Linux applications are encouraged to list their AppImage executables in the same manner.

doc/CONSTANTS.md

@@ -48,6 +48,6 @@ A typical ``{PEB_executable_directory}`` looks like this:
     If this file is found during application startup, it is used as the icon of the application and all dialog boxes.  
     If this file is not found, the default icon embedded in the resources of the browser binary is used.
 
-## Functional Pseudo Filename
+## About URL
 
 * **About dialog:** ``about.function``

doc/INTERACTIVE.md

@@ -0,0 +1,79 @@
+# Perl Executing Browser - Interactive Perl Scripts
+
+PEB interactive Perl scripts are able to receive user input multiple times after the script is already started thus forming a bidirectional connection with PEB. Many interactive scripts can be started simultaneously in one PEB instance. One script may be started in many instances, provided that each of them has a JavaScript settings object with an unique name.  
+
+## Requirements for Interactive Perl Scripts
+
+* **Event Loop**
+  Each PEB interactive Perl script must have its own event loop waiting constantly for new data on STDIN or in a temporary file for a bidirectional connection with PEB. ``AnyEvent`` is a popular Perl framework for building different types of event loops.
+
+* **No Buffering**  
+  PEB interactive scripts should run with no output buffering, which preventing output before the script has ended.
+  Output buffering could be disabled using the following code:
+
+  ```perl
+  use English;
+
+  $OUTPUT_AUTOFLUSH = 1;
+  ```
+
+* **Failsafe Print**  
+  Failsafe print is necessary to shut down PEB Perl scripts when PEB unexpectedly crashes.
+  Failsafe print could be implemented using the following code:
+
+  ```perl
+  print "output string" or shutdown_procedure();
+
+  sub shutdown_procedure {
+    # your shutdown code goes here...
+    exit();
+  }
+  ```
+
+## Examples of Interactive Perl Scripts
+
+The following code shows how to start a PEB interactive Perl script right after the PEB index page is loaded:
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Interactive Script Demo</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta charset="utf-8">
+
+    <script>
+      var pebSettings = {};
+      pebSettings.autoStartScripts = ['interactive_script'];
+
+      var interactive_script = {};
+      interactive_script.scriptRelativePath = 'perl/interactive.pl';
+      interactive_script.inputData = function() {
+        return document.getElementById('interactive-script-input').value;
+      }
+
+      interactive_script.stdoutFunction = function (stdout) {
+        var container = document.getElementById('interactive-script-output');
+        container.innerText = stdout;
+      }
+    </script>
+  </head>
+
+  <body>
+    <form action="interactive_script.script">
+      <input type="text" name="input" id="interactive-script-input">
+      <input type="submit" value="Submit">
+    </form>
+
+    <div id="interactive-script-output"></div>
+  </body>
+</html>
+```
+
+The [index.htm of the demo package](https://github.com/ddmitov/perl-executing-browser/blob/master/resources/app/index.html) demonstrates how to start automatically one Perl interactive script based on STDIN input in two instances.  
+
+The [interactive.pl script of the demo package](https://github.com/ddmitov/perl-executing-browser/blob/master/resources/app/perl/interactive.pl) is an example of a Perl interactive script based on STDIN input.
+
+The [index-windows.htm of the demo package](https://github.com/ddmitov/perl-executing-browser/blob/master/resources/app/index-windows.html) demonstrates how to start automatically one Perl interactive script based on temporary files in two instances.  
+
+The [interactive-windows.pl script of the demo package](https://github.com/ddmitov/perl-executing-browser/blob/master/resources/app/perl/interactive-windows.pl) is an example of a Perl interactive script based on temporary files.

doc/LOGGING.md

@@ -3,20 +3,19 @@
 PEB has unified logging of Perl and JavaScript errors in the JavaScript console.  
 All you need to read Perl errors is to open the JavaScript console.  
 
-## Using the JavaScript Console on QtWebkit Builds
+* To view the JavaScript console on QtWebkit builds  
+  use the keyboard shortcut <kbd>Ctrl</kbd> + <kbd>I</kbd>  
+  to open the ``QWebInspector`` and go to the ``Console`` tab.
 
-Start the ``QWebInspector`` using the keyboard shortcut <kbd>Ctrl</kbd> + <kbd>I</kbd> and go to the ``Console`` tab.  
+* To view the JavaScript console on QtWebEngine builds  
+  start PEB with the following command-line argument supplying an arbitrary private port:
 
-## Using the JavaScript Console on QtWebEngine Builds
+  ```bash
+  peb --remote-debugging-port=8080
+  ```
 
-Start PEB with the following command-line argument supplying an arbitrary private port:
+  and open the local URL with the supplied port using another browser  
 
-```bash
-peb --remote-debugging-port=8080
-```
+  ``http://localhost:8080``
 
-and open the following URL using another browser:
-
-``http://localhost:8080``
-
-to access the ``QtWebEngine Developer Tools``, then go to the ``Console`` tab.  
+  to access the ``QtWebEngine Developer Tools``, then go to the ``Console`` tab.