more readable bash

setup/owncloud.sh

@@ -5,6 +5,8 @@
 source setup/functions.sh # load our functions
 source /etc/mailinabox.conf # load global vars
 
+# ### Installing ownCloud
+
 apt_install \
 	dbconfig-common \
 	php5-cli php5-sqlite php5-gd php5-imap php5-curl php-pear php-apc curl libapr1 libtool libcurl4-openssl-dev php-xml-parser \
@@ -12,7 +14,7 @@ apt_install \
 
 apt-get purge -qq -y owncloud*
 
-# Install ownCloud from source
+# Install ownCloud from source of this version:
 owncloud_ver=7.0.2
 
 # Check if ownCloud dir exist, and check if version matches owncloud_ver (if either doesn't - install/upgrade)
@@ -27,13 +29,15 @@ if [ ! -d /usr/local/lib/owncloud/ ] \
 	rm -f /tmp/owncloud.zip
 fi
 
+# ### Configuring ownCloud
+
 # Setup ownCloud if the ownCloud database does not yet exist. Running setup when
 # the database does exist wipes the database and user data.
 if [ ! -f $STORAGE_ROOT/owncloud/owncloud.db ]; then
 	# Create a configuration file.
-	TIMEZONE=`cat /etc/timezone`
+	TIMEZONE=$(cat /etc/timezone)
 	instanceid=oc$(echo $PRIMARY_HOSTNAME | sha1sum | fold -w 10 | head -n 1)
-	cat - > /usr/local/lib/owncloud/config/config.php <<EOF;
+	cat > /usr/local/lib/owncloud/config/config.php <<EOF;
 <?php
 \$CONFIG = array (
   'datadirectory' => '$STORAGE_ROOT/owncloud',
@@ -75,7 +79,7 @@ EOF
 	# when the install script is run. Make an administrator account
 	# here or else the install can't finish.
 	adminpassword=$(dd if=/dev/random bs=1 count=40 2>/dev/null | sha1sum | fold -w 30 | head -n 1)
-	cat - > /usr/local/lib/owncloud/config/autoconfig.php <<EOF;
+	cat > /usr/local/lib/owncloud/config/autoconfig.php <<EOF;
 <?php
 \$AUTOCONFIG = array (
   # storage/database
@@ -123,13 +127,15 @@ sudo -u www-data php -f /usr/local/lib/owncloud/cron.php
 EOF
 chmod +x /etc/cron.hourly/mailinabox-owncloud
 
-## Ensure all system admins are ownCloud admins.
-## Actually we don't do this. There's nothing much of interest that the user could
-## change from the ownCloud admin, and there's a lot they could mess up.
-#for user in $(tools/mail.py user admins); do
-#	sqlite3 $STORAGE_ROOT/owncloud/owncloud.db "INSERT OR IGNORE INTO oc_group_user VALUES ('admin', '$user')"
-#done
+# There's nothing much of interest that a user could do as an admin for ownCloud,
+# and there's a lot they could mess up, so we don't make any users admins of ownCloud.
+# But if we wanted to, we would do this:
+# ```
+# for user in $(tools/mail.py user admins); do
+#	 sqlite3 $STORAGE_ROOT/owncloud/owncloud.db "INSERT OR IGNORE INTO oc_group_user VALUES ('admin', '$user')"
+# done
+# ```
 
-# Finished.
+# Enable PHP modules and restart PHP.
 php5enmod imap
 restart_service php5-fpm

setup/webmail.sh

-# Webmail: Using roundcube
-##########################
+# Webmail with Roundcube
+# ----------------------
 
 source setup/functions.sh # load our functions
 source /etc/mailinabox.conf # load global vars
 
-# Ubuntu's roundcube-core has dependencies on Apache & MySQL, which we don't want, so we can't
-# install roundcube directly via apt-get install.
+# ### Installing Roundcube
+
+# We install Roundcube from sources, rather than from Ubuntu, because:
+#
+# 1. Ubuntu's `roundcube-core` package has dependencies on Apache & MySQL, which we don't want.
 #
-# Additionally, the Roundcube shipped with Ubuntu is consistently out of date.
+# 2. The Roundcube shipped with Ubuntu is consistently out of date.
 #
-# And it's packaged incorrectly --- it seems to be missing a directory of files.
+# 3. It's packaged incorrectly --- it seems to be missing a directory of files.
 #
 # So we'll use apt-get to manually install the dependencies of roundcube that we know we need,
 # and then we'll manually install roundcube from source.
 
-# These dependencies are from 'apt-cache showpkg roundcube-core'.
+# These dependencies are from `apt-cache showpkg roundcube-core`.
 apt_install \
 	dbconfig-common \
 	php5 php5-sqlite php5-mcrypt php5-intl php5-json php5-common php-auth php-net-smtp php-net-socket php-net-sieve php-mail-mime php-crypt-gpg php5-gd php5-pspell \
@@ -35,6 +38,8 @@ if [ ! -d /usr/local/lib/roundcubemail ]; then
 	rm -f /tmp/roundcube.tgz
 fi
 
+# ### Configuring Roundcube
+
 # Generate a safe 24-character secret key of safe characters.
 SECRET_KEY=$(dd if=/dev/random bs=1 count=18 2>/dev/null | base64 | fold -w 24 | head -n 1)
 
@@ -43,7 +48,7 @@ SECRET_KEY=$(dd if=/dev/random bs=1 count=18 2>/dev/null | base64 | fold -w 24 |
 # For security, temp and log files are not stored in the default locations
 # which are inside the roundcube sources directory. We put them instead
 # in normal places.
-cat - > /usr/local/lib/roundcubemail/config/config.inc.php <<EOF;
+cat > /usr/local/lib/roundcubemail/config/config.inc.php <<EOF;
 <?php
 /*
  * Do not edit. Written by Mail-in-a-Box. Regenerated on updates.

setup/zpush.sh

 #!/bin/bash
 #
-# Z-Push: The Microsoft Exchange protocol server.
+# Z-Push: The Microsoft Exchange protocol server
+# ----------------------------------------------
+#
 # Mostly for use on iOS which doesn't support IMAP.
 #
 # Although Ubuntu ships Z-Push (as d-push) it has a dependency on Apache
@@ -19,12 +21,12 @@ apt_install \
 php5enmod imap
 
 # Copy Z-Push into place.
-needs_update=0
+needs_update=0 #NODOC
 if [ ! -f /usr/local/lib/z-push/version ]; then
-	needs_update=1
+	needs_update=1 #NODOC
 elif [[ `curl -s https://api.github.com/repos/fmbiete/Z-Push-contrib/git/refs/heads/master` != `cat /usr/local/lib/z-push/version` ]]; then
 	# checks if the version 
-	needs_update=1
+	needs_update=1 #NODOC
 fi
 if [ $needs_update == 1 ]; then
 	rm -rf /usr/local/lib/z-push

tools/readable_bash.py

@@ -58,6 +58,11 @@ def generate_documentation():
 	    		padding: .5em;
 	    		margin: 0;
 	    	}
+
+	    	pre.shell > div:before {
+	    		content: "$ ";
+	    		color: #666;
+	    	}
         </style>
     </head>
     <body>
@@ -123,7 +128,9 @@ class Source(Grammar):
 class CatEOF(Grammar):
 	grammar = (ZERO_OR_MORE(SPACE), L('cat > '), ANY_EXCEPT(WHITESPACE), L(" <<"), OPTIONAL(SPACE), L("EOF;"), EOL, REPEAT(ANY, greedy=False), EOL, L("EOF"), EOL)
 	def value(self):
-		return "<div class='write-to'><div class='filename'>" + self[2].string + "</div><pre>" + cgi.escape(self[7].string) + "</pre></div>\n"
+		content = self[7].string
+		content = re.sub(r"\\([$])", r"\1", content) # un-escape bash-escaped characters
+		return "<div class='write-to'><div class='filename'>overwrite<br>" + self[2].string + "</div><pre>" + cgi.escape(content) + "</pre></div>\n"
 
 class HideOutput(Grammar):
 	grammar = (L("hide_output "), REF("BashElement"))
@@ -134,7 +141,7 @@ class SuppressedLine(Grammar):
 	grammar = (OPTIONAL(SPACE), L("echo "), REST_OF_LINE, EOL)
 	def value(self):
 		if "|" in self.string  or ">" in self.string:
-			return "<pre>" + cgi.escape(self.string) + "</pre>\n"
+			return "<pre class='shell'><div>" + cgi.escape(self.string.strip()) + "</div></pre>\n"
 		return ""
 
 class EditConf(Grammar):
@@ -143,7 +150,7 @@ class EditConf(Grammar):
 		FILENAME,
 		SPACE,
 		OPTIONAL((LIST_OF(
-			L("-w") | L("-s"),
+			L("-w") | L("-s") | L("-c ';'"),
 			sep=SPACE,
 		), SPACE)),
 		REST_OF_LINE,
@@ -172,7 +179,7 @@ class EditConf(Grammar):
 			else:
 				options[-1] += c
 		if options[-1] == "": options.pop(-1)
-		return "<div class='write-to'><div class='filename'>" + self[1].string + "</div><pre>" + "\n".join(cgi.escape(s) for s in options) + "</pre></div>\n"
+		return "<div class='write-to'><div class='filename'>additional settings for<br>" + self[1].string + "</div><pre>" + "\n".join(cgi.escape(s) for s in options) + "</pre></div>\n"
 
 class CaptureOutput(Grammar):
 	grammar = OPTIONAL(SPACE), WORD("A-Za-z_"), L('=$('), REST_OF_LINE, L(")"), OPTIONAL(L(';')), EOL
@@ -184,25 +191,32 @@ class CaptureOutput(Grammar):
 class SedReplace(Grammar):
 	grammar = OPTIONAL(SPACE), L('sed -i "s/'), OPTIONAL(L('^')), ONE_OR_MORE(WORD("-A-Za-z0-9 #=\\{};.*$_!()")), L('/'), ONE_OR_MORE(WORD("-A-Za-z0-9 #=\\{};.*$_!()")), L('/"'), SPACE, FILENAME, EOL
 	def value(self):
-		return "<div class='write-to'><div class='filename'>" + self[8].string + "</div><p>replace</p><pre>" + cgi.escape(self[3].string.replace(".*", ". . .")) + "</pre><p>with</p><pre>" + cgi.escape(self[5].string.replace("\\n", "\n").replace("\\t", "\t")) + "</pre></div>\n"
+		return "<div class='write-to'><div class='filename'>edit<br>" + self[8].string + "</div><p>replace</p><pre>" + cgi.escape(self[3].string.replace(".*", ". . .")) + "</pre><p>with</p><pre>" + cgi.escape(self[5].string.replace("\\n", "\n").replace("\\t", "\t")) + "</pre></div>\n"
+
+def shell_line(bash):
+	return "<pre class='shell'><div>" + cgi.escape(wrap_lines(bash.strip())) + "</div></pre>\n"
 
 class AptGet(Grammar):
 	grammar = (ZERO_OR_MORE(SPACE), L("apt_install "), REST_OF_LINE, EOL)
 	def value(self):
-		return "<pre>" + self[0].string + "apt-get install -y " + cgi.escape(re.sub(r"\s+", " ", self[2].string)) + "</pre>\n"
+		return shell_line("apt-get install -y " + re.sub(r"\s+", " ", self[2].string))
 class UfwAllow(Grammar):
 	grammar = (ZERO_OR_MORE(SPACE), L("ufw_allow "), REST_OF_LINE, EOL)
 	def value(self):
-		return "<pre>" + self[0].string + "ufw allow " + cgi.escape(self[2].string) + "</pre>\n"
+		return shell_line("ufw allow " + self[2].string)
+class RestartService(Grammar):
+	grammar = (ZERO_OR_MORE(SPACE), L("restart_service "), REST_OF_LINE, EOL)
+	def value(self):
+		return shell_line("service " + self[2].string + " restart")
 
 class OtherLine(Grammar):
 	grammar = (REST_OF_LINE, EOL)
 	def value(self):
 		if self.string.strip() == "": return ""
-		return "<pre>" + cgi.escape(self.string.rstrip()) + "</pre>\n"
+		return "<pre class='shell'><div>" + cgi.escape(self.string.rstrip()) + "</div></pre>\n"
 
 class BashElement(Grammar):
-	grammar = Comment | Source | CatEOF | SuppressedLine | HideOutput | EditConf | CaptureOutput | SedReplace | AptGet | UfwAllow | OtherLine
+	grammar = Comment | Source | CatEOF | SuppressedLine | HideOutput | EditConf | CaptureOutput | SedReplace | AptGet | UfwAllow | RestartService | OtherLine
 	def value(self):
 		return self[0].value()
 
@@ -218,14 +232,14 @@ class BashScript(Grammar):
 		string = open(fn).read()
 		string = re.sub(r"\s*\\\n\s*", " ", string)
 		string = re.sub(".* #NODOC\n", "", string)
-		string = re.sub("\n\s*if .*|\n\s*fi|\n\s*else", "", string)
+		string = re.sub("\n\s*if .*|\n\s*fi|\n\s*else|\n\s*elif .*", "", string)
 		string = re.sub("hide_output ", "", string)
 		result = parser.parse_string(string)
 	
 		v = "<div class='sourcefile'><a href=\"%s\">%s</a></div>\n" % ("https://github.com/mail-in-a-box/mailinabox/tree/master/" + fn, fn)
 		v += "".join(result.value())
 
-		v = v.replace("</pre>\n<pre>", "\n")
+		v = v.replace("</pre>\n<pre class='shell'>", "")
 		v = re.sub("<pre>([\w\W]*?)</pre>", lambda m : "<pre>" + strip_indent(m.group(1)) + "</pre>", v)
 
 		v = re.sub(r"\$?PRIMARY_HOSTNAME", "<b>box.yourdomain.com</b>", v)
@@ -234,5 +248,19 @@ class BashScript(Grammar):
 
 		return v
 
+def wrap_lines(text, cols=60):
+	ret = ""
+	words = re.split("(\s+)", text)
+	linelen = 0
+	for w in words:
+		if linelen + len(w) > cols-1:
+			ret += " \\\n"
+			ret += "   "
+			linelen = 0
+		if linelen == 0 and w.strip() == "": continue
+		ret += w
+		linelen += len(w)
+	return ret
+
 if __name__ == '__main__':
 	generate_documentation()