doc: add URL transfer in scripting guide

5 files changed, 260 insertions, 40 deletions

diff --git a/doc/de/weechat_scripting.de.txt b/doc/de/weechat_scripting.de.txt
index 835dc1cb1..146eae71f 100644
--- a/doc/de/weechat_scripting.de.txt
+++ b/doc/de/weechat_scripting.de.txt
@@ -618,23 +618,67 @@ Beispiele:
 
 [source,python]
 ----------------------------------------
+process_output = ""
+
+def my_process_cb(data, command, rc, out, err):
+    global process_output
+    if out != "":
+        process_output += out
+    if int(rc) >= 0:
+        weechat.prnt("", process_output)
+    return weechat.WEECHAT_RC_OK
+
+weechat.hook_process("/bin/ls -l /etc", 10 * 1000, "my_process_cb", "")
+----------------------------------------
+
+// TRANSLATION MISSING
+[[url_transfer]]
+URL transfer
+^^^^^^^^^^^^
+
+_New in version 0.3.7._
+
+To download URL (or post to URL), you have to use function `hook_process`, or
+`hook_process_hashtable` if you need to set options for URL transfer.
+
+Example of URL transfer without option: the HTML page will be received as "out"
+in callback (standard output of process):
+
+[source,python]
+----------------------------------------
 # Zeigt die Versionen der Linux-Kerne.
 kernel_txt = ""
 
-def kernel_process_cb(data, command, rc, stdout, stderr):
-    """ Callback reading command output. """
+def kernel_process_cb(data, command, rc, out, err):
     global kernel_txt
-    if stdout != "":
-        kernel_txt += stdout
+    if out != "":
+        kernel_txt += out
     if int(rc) >= 0:
         weechat.prnt("", kernel_txt)
     return weechat.WEECHAT_RC_OK
 
-weechat.hook_process("python -c \"import urllib; " \
-                     "print urllib.urlopen('http://www.kernel.org/kdist/finger_banner').read()\"",
-                     10 * 1000, "kernel_process_cb", "")
+weechat.hook_process("url:http://www.kernel.org/kdist/finger_banner",
+                     30 * 1000, "kernel_process_cb", "")
+----------------------------------------
+
+Example of URL transfer with an option: download latest WeeChat development
+package in file '/tmp/weechat-devel.tar.gz':
+
+[source,python]
+----------------------------------------
+def my_process_cb(data, command, rc, out, err):
+    if int(rc) >= 0:
+        weechat.prnt("", "End of transfer (rc=%s)" % rc)
+    return weechat.WEECHAT_RC_OK
+
+weechat.hook_process_hashtable("url:http://weechat.org/files/src/weechat-devel.tar.gz",
+                               { "file_out": "/tmp/weechat-devel.tar.gz" },
+                               30 * 1000, "my_process_cb", "")
 ----------------------------------------
 
+For more information about URL transfer and available options, see functions
+`hook_process` and `hook_process_hashtable` in 'WeeChat Plugin API Reference'.
+
 [[config_options]]
 Konfiguration / Optionen
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -676,7 +720,7 @@ SKRIPT_NAME = "meinskript"
 # ...
 
 def config_cb(data, option, value):
-    """ Callback welcher genutzt wird wenn eine Option verändert wurde. """
+    """Callback welcher genutzt wird wenn eine Option verändert wurde."""
     # zum Beispiel werden hier alle Optionen des Skripts in die entsprechenden Variablen geschrieben...
     # ...
     return weechat.WEECHAT_RC_OK
diff --git a/doc/en/weechat_scripting.en.txt b/doc/en/weechat_scripting.en.txt
index dc9ce0129..880732b8d 100644
--- a/doc/en/weechat_scripting.en.txt
+++ b/doc/en/weechat_scripting.en.txt
@@ -605,23 +605,66 @@ Example:
 
 [source,python]
 ----------------------------------------
+process_output = ""
+
+def my_process_cb(data, command, rc, out, err):
+    global process_output
+    if out != "":
+        process_output += out
+    if int(rc) >= 0:
+        weechat.prnt("", process_output)
+    return weechat.WEECHAT_RC_OK
+
+weechat.hook_process("/bin/ls -l /etc", 10 * 1000, "my_process_cb", "")
+----------------------------------------
+
+[[url_transfer]]
+URL transfer
+^^^^^^^^^^^^
+
+_New in version 0.3.7._
+
+To download URL (or post to URL), you have to use function `hook_process`, or
+`hook_process_hashtable` if you need to set options for URL transfer.
+
+Example of URL transfer without option: the HTML page will be received as "out"
+in callback (standard output of process):
+
+[source,python]
+----------------------------------------
 # Display versions of Linux kernels.
 kernel_txt = ""
 
-def kernel_process_cb(data, command, rc, stdout, stderr):
-    """ Callback reading command output. """
+def kernel_process_cb(data, command, rc, out, err):
     global kernel_txt
-    if stdout != "":
-        kernel_txt += stdout
+    if out != "":
+        kernel_txt += out
     if int(rc) >= 0:
         weechat.prnt("", kernel_txt)
     return weechat.WEECHAT_RC_OK
 
-weechat.hook_process("python -c \"import urllib; "
-                     "print urllib.urlopen('http://www.kernel.org/kdist/finger_banner').read()\"",
-                     10 * 1000, "kernel_process_cb", "")
+weechat.hook_process("url:http://www.kernel.org/kdist/finger_banner",
+                     30 * 1000, "kernel_process_cb", "")
+----------------------------------------
+
+Example of URL transfer with an option: download latest WeeChat development
+package in file '/tmp/weechat-devel.tar.gz':
+
+[source,python]
+----------------------------------------
+def my_process_cb(data, command, rc, out, err):
+    if int(rc) >= 0:
+        weechat.prnt("", "End of transfer (rc=%s)" % rc)
+    return weechat.WEECHAT_RC_OK
+
+weechat.hook_process_hashtable("url:http://weechat.org/files/src/weechat-devel.tar.gz",
+                               { "file_out": "/tmp/weechat-devel.tar.gz" },
+                               30 * 1000, "my_process_cb", "")
 ----------------------------------------
 
+For more information about URL transfer and available options, see functions
+`hook_process` and `hook_process_hashtable` in 'WeeChat Plugin API Reference'.
+
 [[config_options]]
 Config / options
 ~~~~~~~~~~~~~~~~
@@ -662,7 +705,7 @@ SCRIPT_NAME = "myscript"
 # ...
 
 def config_cb(data, option, value):
-    """ Callback called when a script option is changed. """
+    """Callback called when a script option is changed."""
     # for example, read all script options to script variables...
     # ...
     return weechat.WEECHAT_RC_OK
diff --git a/doc/fr/weechat_scripting.fr.txt b/doc/fr/weechat_scripting.fr.txt
index acbe2043e..7936090c0 100644
--- a/doc/fr/weechat_scripting.fr.txt
+++ b/doc/fr/weechat_scripting.fr.txt
@@ -621,22 +621,67 @@ Exemple :
 
 [source,python]
 ----------------------------------------
+process_output = ""
+
+def my_process_cb(data, command, rc, out, err):
+    global process_output
+    if out != "":
+        process_output += out
+    if int(rc) >= 0:
+        weechat.prnt("", process_output)
+    return weechat.WEECHAT_RC_OK
+
+weechat.hook_process("/bin/ls -l /etc", 10 * 1000, "my_process_cb", "")
+----------------------------------------
+
+[[url_transfer]]
+Transfert d'URL
+^^^^^^^^^^^^^^^
+
+_Nouveau dans la version 0.3.7._
+
+Pour télécharger une URL (ou poster vers une URL), vous devez utiliser la
+fonction `hook_process`, ou `hook_process_hashtable` si vous avez besoin
+d'options pour le transfert d'URL.
+
+Exemple de transfert d'URL sans option : la page HTML sera reçue comme "out"
+dans le "callback" (sortie standard du processus) :
+
+[source,python]
+----------------------------------------
 # Afficher la version des noyaux Linux.
 kernel_txt = ""
 
-def kernel_process_cb(data, command, rc, stdout, stderr):
-    """ Callback qui lit la sortie de la commande. """
+def kernel_process_cb(data, command, rc, out, err):
     global kernel_txt
-    if stdout != "":
-        kernel_txt += stdout
+    if out != "":
+        kernel_txt += out
     if int(rc) >= 0:
         weechat.prnt("", kernel_txt)
     return weechat.WEECHAT_RC_OK
 
-weechat.hook_process("python -c \"import urllib; "
-                     "print urllib.urlopen('http://www.kernel.org/kdist/finger_banner').read()\"",
-                     10 * 1000, "kernel_process_cb", "")
+weechat.hook_process("url:http://www.kernel.org/kdist/finger_banner",
+                     30 * 1000, "kernel_process_cb", "")
+----------------------------------------
+
+Exemple de transfert d'URL avec une option : télécharger le dernier paquet de
+développement WeeChat dans le fichier '/tmp/weechat-devel.tar.gz' :
+
+[source,python]
 ----------------------------------------
+def my_process_cb(data, command, rc, out, err):
+    if int(rc) >= 0:
+        weechat.prnt("", "Fin du transfert (rc=%s)" % rc)
+    return weechat.WEECHAT_RC_OK
+
+weechat.hook_process_hashtable("url:http://weechat.org/files/src/weechat-devel.tar.gz",
+                               { "file_out": "/tmp/weechat-devel.tar.gz" },
+                               30 * 1000, "my_process_cb", "")
+----------------------------------------
+
+Pour plus d'information sur le transfert d'URL et les options disponibles, voir
+les fonctions `hook_process` et `hook_process_hashtable` dans la
+'Référence API Extension WeeChat'.
 
 [[config_options]]
 Config / options
@@ -679,7 +724,7 @@ SCRIPT_NAME = "monscript"
 # ...
 
 def config_cb(data, option, value):
-    """ Callback appelé lorsqu'une option du script est modifiée. """
+    """Callback appelé lorsqu'une option du script est modifiée."""
     # par exemple, relire toutes les options du script dans des variables du script...
     # ...
     return weechat.WEECHAT_RC_OK
diff --git a/doc/it/weechat_scripting.it.txt b/doc/it/weechat_scripting.it.txt
index 3f79c9bf1..7f382a0a8 100644
--- a/doc/it/weechat_scripting.it.txt
+++ b/doc/it/weechat_scripting.it.txt
@@ -619,23 +619,67 @@ Esempio:
 
 [source,python]
 ----------------------------------------
+process_output = ""
+
+def my_process_cb(data, command, rc, out, err):
+    global process_output
+    if out != "":
+        process_output += out
+    if int(rc) >= 0:
+        weechat.prnt("", process_output)
+    return weechat.WEECHAT_RC_OK
+
+weechat.hook_process("/bin/ls -l /etc", 10 * 1000, "my_process_cb", "")
+----------------------------------------
+
+// TRANSLATION MISSING
+[[url_transfer]]
+URL transfer
+^^^^^^^^^^^^
+
+_Novità nella versione 0.3.7._
+
+To download URL (or post to URL), you have to use function `hook_process`, or
+`hook_process_hashtable` if you need to set options for URL transfer.
+
+Example of URL transfer without option: the HTML page will be received as "out"
+in callback (standard output of process):
+
+[source,python]
+----------------------------------------
 # Visualizza le versioni dei kernel di Linux.
 kernel_txt = ""
 
-def kernel_process_cb(data, command, rc, stdout, stderr):
-    """ Callback reading command output. """
+def kernel_process_cb(data, command, rc, out, err):
     global kernel_txt
-    if stdout != "":
-        kernel_txt += stdout
+    if out != "":
+        kernel_txt += out
     if int(rc) >= 0:
         weechat.prnt("", kernel_txt)
     return weechat.WEECHAT_RC_OK
 
-weechat.hook_process("python -c \"import urllib; "
-                     "print urllib.urlopen('http://www.kernel.org/kdist/finger_banner').read()\"",
-                     10 * 1000, "kernel_process_cb", "")
+weechat.hook_process("url:http://www.kernel.org/kdist/finger_banner",
+                     30 * 1000, "kernel_process_cb", "")
+----------------------------------------
+
+Example of URL transfer with an option: download latest WeeChat development
+package in file '/tmp/weechat-devel.tar.gz':
+
+[source,python]
+----------------------------------------
+def my_process_cb(data, command, rc, out, err):
+    if int(rc) >= 0:
+        weechat.prnt("", "End of transfer (rc=%s)" % rc)
+    return weechat.WEECHAT_RC_OK
+
+weechat.hook_process_hashtable("url:http://weechat.org/files/src/weechat-devel.tar.gz",
+                               { "file_out": "/tmp/weechat-devel.tar.gz" },
+                               30 * 1000, "my_process_cb", "")
 ----------------------------------------
 
+For more information about URL transfer and available options, see functions
+`hook_process` and `hook_process_hashtable` in 'WeeChat Plugin API Reference'.
+
 [[config_options]]
 Configurazione / opzioni
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -677,7 +721,7 @@ SCRIPT_NAME = "myscript"
 # ...
 
 def config_cb(data, option, value):
-    """ Callback called when a script option is changed. """
+    """Callback called when a script option is changed."""
     # for example, read all script options to script variables...
     # ...
     return weechat.WEECHAT_RC_OK
diff --git a/doc/pl/weechat_scripting.pl.txt b/doc/pl/weechat_scripting.pl.txt
index 5ffd29588..6a83f6ed2 100644
--- a/doc/pl/weechat_scripting.pl.txt
+++ b/doc/pl/weechat_scripting.pl.txt
@@ -607,22 +607,66 @@ Przykład:
 
 [source,python]
 ----------------------------------------
+process_output = ""
+
+def my_process_cb(data, command, rc, out, err):
+    global process_output
+    if out != "":
+        process_output += out
+    if int(rc) >= 0:
+        weechat.prnt("", process_output)
+    return weechat.WEECHAT_RC_OK
+
+weechat.hook_process("/bin/ls -l /etc", 10 * 1000, "my_process_cb", "")
+----------------------------------------
+
+// TRANSLATION MISSING
+[[url_transfer]]
+URL transfer
+^^^^^^^^^^^^
+
+_Nowe w wersji 0.3.7._
+
+To download URL (or post to URL), you have to use function `hook_process`, or
+`hook_process_hashtable` if you need to set options for URL transfer.
+
+Example of URL transfer without option: the HTML page will be received as "out"
+in callback (standard output of process):
+
+[source,python]
+----------------------------------------
 # Wyświetla wersje Linuksowych kerneli.
 kernel_txt = ""
 
-def kernel_process_cb(data, command, rc, stdout, stderr):
-    """ Callback reading command output. """
+def kernel_process_cb(data, command, rc, out, err):
     global kernel_txt
-    if stdout != "":
-        kernel_txt += stdout
+    if out != "":
+        kernel_txt += out
     if int(rc) >= 0:
         weechat.prnt("", kernel_txt)
     return weechat.WEECHAT_RC_OK
 
-weechat.hook_process("python -c \"import urllib; "
-                     "print urllib.urlopen('http://www.kernel.org/kdist/finger_banner').read()\"",
-                     10 * 1000, "kernel_process_cb", "")
+weechat.hook_process("url:http://www.kernel.org/kdist/finger_banner",
+                     30 * 1000, "kernel_process_cb", "")
+----------------------------------------
+
+Example of URL transfer with an option: download latest WeeChat development
+package in file '/tmp/weechat-devel.tar.gz':
+
+[source,python]
 ----------------------------------------
+def my_process_cb(data, command, rc, out, err):
+    if int(rc) >= 0:
+        weechat.prnt("", "End of transfer (rc=%s)" % rc)
+    return weechat.WEECHAT_RC_OK
+
+weechat.hook_process_hashtable("url:http://weechat.org/files/src/weechat-devel.tar.gz",
+                               { "file_out": "/tmp/weechat-devel.tar.gz" },
+                               30 * 1000, "my_process_cb", "")
+----------------------------------------
+
+For more information about URL transfer and available options, see functions
+`hook_process` and `hook_process_hashtable` in 'WeeChat Plugin API Reference'.
 
 [[config_options]]
 Konfiguracja / opcje
@@ -664,7 +708,7 @@ SCRIPT_NAME = "myscript"
 # ...
 
 def config_cb(data, option, value):
-    """ Callback called when a script option is changed. """
+    """Callback called when a script option is changed."""
     # na przykład, odczyt wszystkich opcji skryptu...
     # ...
     return weechat.WEECHAT_RC_OK