update documentation

1 files changed, 45 insertions, 86 deletions

diff --git a/wordpress/export-json.bash b/wordpress/export-json.bash
index d2ab8f3..7f5c5d3 100644
--- a/wordpress/export-json.bash
+++ b/wordpress/export-json.bash
@@ -1,59 +1,51 @@
 #!/bin/bash
-
-# This script allows bash to export environment
-# variables as JSON.  A list of environment
-# variables and their values is exported as a
-# single JSON object containing key-value mappings
-# of JSON strings. It uses the external tool "jq"
-# to parse string values # placed in jq's argument
-# list by bash and then encode them as JSON string
-# values. This is no accidental dependency. The jq
-# program is the foundation of the trustworthiness
-# of this code. If we were encoding JSON strings
-# in bash (and not just encoding the JSON objects
-# containing the strings) we would have to be a
-# lot more careful.
-
-# This is the simple code I wanted to replace:
 #
-# jq --arg SITE "$SITE" "$json"
-# jq -n \
-#       --arg h "$db_host" \
-#       --arg u "$db_user" \
-#       --arg p "$db_password" \
-#       --arg n "$db_name" \
-#       --arg t "$table_prefix" \
-#       '{ db_host: $h
-#        , db_user: $u
-#        , db_password: $p
-#        , db_name: $n
-#        , table_prefix: $t
-#        }'
+# export_JSON <variables>
+# 
+# Synopsis:
+#
+#       $ (
+#               source export-json.bash
+#               export_JSON SSH_TTY \
+#                           SSH_CONNECTION \
+#                           SSH_CLIENT \
+#                           SSH_AUTH_SOCK
+#         )
+#       {
+#         "SSH_TTY": "/dev/pts/0",
+#         "SSH_CONNECTION": "192.0.2.140 41564 198.51.100.25 22",
+#         "SSH_CLIENT": "192.0.2.140 41564 22",
+#         "SSH_AUTH_SOCK": "/tmp/ssh-XXXXcePKJl/agent.36326"
+#       }
+#
+# This bash function exports shell variables as
+# JSON ("javascript object notation") strings.
+#
+# The string is printed to stdout.
+#
+# JSON is a format that represents data as
+# Javascript source code so modern programmers
+# can read it unlike bash source code.  
+#
+# Variable names are given to the function as its
+# argument list:
+#
+#       $ (source export-json.bash; export_JSON PATH)
 #
-# The problem with the above is that the names are
-# repeated.
-# This creates the possibility that the names not
-# match, creating a bug.
-# This code allows the names to be specified only
-# one time.
-# It allows the bug where the names do not match
-# to be fixed only one time by one person.
-# IF ... the fix can be distributed back to the
-# extant copies.
-# How to get the beneficial mutations
-# back into the living organisms?
-# Life tries not to answer this question
-# until very late in its development
-# since after all
-# the extant copies are the past
-# and life looks into the future
-# But because consciousness
-# is the mirror of time
-# the question is asked
-# eventually
-# when that level
-# of life
-# consciousness is reached.
+# The output is a single JSON object containing
+# key-value mappings between JSON strings:
+#
+#       {
+#         "PATH": "/usr/local/sbin:[...]"
+#       }
+#
+# It uses the external tool "jq" to parse string
+# values placed in jq's argument list by bash and
+# then encode them as JSON string values. This
+# is no accidental dependency. The jq program is
+# the foundation of the trustworthiness of this
+# code. If we were encoding JSON strings in bash
+# we would have to be a lot more careful.
 
 arg1_to_env0()
 {
@@ -136,36 +128,3 @@ runtest()
         try export_JSON ''
         try export_JSON '' SSH_TTY
 }
-
-# Cryptography and routing needs to and does work like the benefits
-# office where there is a fixed supply to hand out so there is a line
-# of recipients waiting and in order to save resources there is a
-# limit to its size and a residue of turnaways. So it is with tcp
-# connections and in order for a service to minimize disruption to other
-# tcp connections it need only limit the number of open connections it
-# allows; understanding that the residue of turnaways will increase but
-# the fixed supply will be delivered and the turnaways will re-enter the
-# queue to receive belatedly.
-#
-# The connections in which we are interested are not TCP connections,
-# they are VPN connections over UDP, but not really, they are social
-# connections sustained through a software<->computer interface
-# intermediary.
-#
-# The social program of Samizdat involves tending to the computers by
-# interfacing with their USB ports and network ports, not their screens!
-# The screen is used to seek user confirmation WITH DEfAULT TIMEOUT
-# that makes Samizdat human-interaction-optional. Furthermore, Samizdat
-# attempts to use the network to make human-interaction require no
-# physical presence, but rather the human can interact from any one of
-# their nodes that is live at the time! These identity-holding nodes
-# hold SSH servers open on the internet AND thereby hold the personal
-# cryptographic identity that YOU can most easily export and use on YOUR
-# OWN servers.
-#
-# Anyway, we allow connectivity onto these machines in various ways,
-# for example, the local network can take over the display if the user
-# has never logged in, allowing to authorize the first install to disk
-# on the machine without needing the machine to have a working display
-# or input device.
-