From ce31d8623c225c4436e71c6750dd3b7ac8a32e24 Mon Sep 17 00:00:00 2001
From: Julian Noble <julian@precisium.com.au>
Date: Sat, 11 Jul 2026 12:59:44 +1000
Subject: [PATCH] update punk::sshrun with wiki documentation

---
 src/modules/punk/sshrun-999999.0a1.0.tm | 86 +++++++++++++++++++++++++
 1 file changed, 86 insertions(+)

diff --git a/src/modules/punk/sshrun-999999.0a1.0.tm b/src/modules/punk/sshrun-999999.0a1.0.tm
index 00d00923..2a388f6a 100644
--- a/src/modules/punk/sshrun-999999.0a1.0.tm
+++ b/src/modules/punk/sshrun-999999.0a1.0.tm
@@ -55,6 +55,92 @@
 #[subsection Concepts]
 #[para] -
 
+####### original wiki documentation
+##  Overview
+##  Tclssh is a package of pure Tcl functions for executing Tcl scripts in a remote host. It is used by Nbsp and the WRFPak to offload some long-time running jobs in parallel to other computers.
+##
+##  The remote host must be accessible via ssh keys without a password; that is, for example, the contents of your ./ssh/id_rsa.pub must be added to the .ssh/authorized_keys file in the remote host.
+##
+##  The directory
+##
+##  <prefix>/share/doc/examples
+##  has several examples that can be used for testing and documentation.
+##
+##  Example
+##  The best way to explain how to use is by looking at one of them, ex-1.tcl.
+##
+##  #!/usr/bin/tclsh
+##
+##  package require ssh
+##
+##  #
+##  # Collect in the string "script" the script that will be sent to the
+##  # remote (slave) host.
+##  #
+##  set script {
+##  puts "I am a remote host named [info hostname] executing a script
+##  that my master sent me. I am going to sent him back the results of some
+##  commands. Here they are:
+##
+##      The date is: [exec date]
+##      My info is: [exec uname -a]
+##
+##  Now I need to inform my master that I have finished.
+##
+##  DONE 0"
+##  };
+##
+##  set slave "is.1-loop.net";     # This is the remote host
+##
+##  #
+##  # If the tcl shell in the remote host is just "tclsh" (e.g. a linux system)
+##  # the -t option (and its argment) can be omitted; otherwise it can be
+##  # used to specify the name of the remote tcl shell.
+##  #
+##  ::ssh::connect -t tclsh8.6 -- $slave
+##  ::ssh::push $slave $script
+##  ::ssh::send $slave;
+##  while {[::ssh::pop_line $slave line] >= 0} {
+##      if {[regexp {^DONE\s+(\d+)} $line match code]} {
+##  	break;
+##      }
+##      puts $line;
+##  }
+##  ::ssh::disconnect $slave;
+##
+##  puts "Slave finished with code: $code";
+##  Below is the output of executing ex-1.tcl from a machine named elite:
+##
+##  [nieves@elite examples]$ ./ex-1.tcl
+##  I am a remote host named is.1-loop.net executing a script
+##  that my master sent me. I am going to sent him back the results of some
+##  commands. Here they are:
+##
+##      The date is: Sun Dec  9 17:35:43 AST 2012
+##      My info is: Linux is 2.6.32-308.8.2.el5.028stab101.1 #1 SMP Sun Jun 24 20:25:35 MSD 2012 i686 GNU/Linux
+##
+##  Now I need to inform my master that I have finished.
+
+##  Slave finished with code: 0
+##  [nieves@elite examples]$
+##  Several other examples in the
+##
+##  <prefix>/share/doc/examples
+##  directory illustrate more capabilities of this package.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
 # ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
 ##  Requirements