aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--.gitignore4
-rw-r--r--Makefile20
-rw-r--r--index.org142
-rw-r--r--org2html.el7
-rw-r--r--style.css85
5 files changed, 258 insertions, 0 deletions
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..2a519db
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,4 @@
+index.html
+*~
+.emacs*
+.cache
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..94093e5
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,20 @@
+CVSREPO=:ext:gray@puszcza.gnu.org.ua:/webcvs/xenv
+SOURCES=index.html style.css
+
+index.html: index.org
+ emacs --batch -l org2html.el index.org
+
+clean: index.html
+
+.PHONY: .cache
+.cache:
+ @if test -d .cache ; then \
+ cd .cache && cvs update ; \
+ else \
+ mkdir .cache && \
+ cvs -z3 -d $(CVSREPO) co -d .cache xenv; \
+ fi
+
+update: .cache index.html
+ rsync -az $(SOURCES) .cache
+ cd .cache && cvs commit -m 'Update'
diff --git a/index.org b/index.org
new file mode 100644
index 0000000..9c35b07
--- /dev/null
+++ b/index.org
@@ -0,0 +1,142 @@
+* Overview
+
+*Xenv* is a text preprocessor that expands references to environment
+variables in the input text to their actual values. Environment
+variables are referenced using POSIX-compatible shell syntax.
+Text is read from the standard input and expanded text goes to the
+standard output.
+
+* Rationale
+
+It became a de-facto practice to configure docker containers using
+environment variables. The method is obvious when configuration
+is consumed by some programming language (*php*, *python* or the
+like). However, sometimes the need arises to expand environment
+variables in configuration files of the utilities that provide no
+mechanism for this (such as *mysqld* or *ldap*, for instance).
+
+I often use [[http://puszcza.gnu.org.ua/software/pies/][GNU pies]] as entrypoint for images I produce. It uses
+[[https://www.gnu.org/software/m4][m4]] for preprocessing its configuration. Several mechanisms have
+been proposed for expanding environment variables in it: implementing
+special
+[[http://puszcza.gnu.org.ua/software/pies/manual/Docker-Entrypoint.html][macros]] or a [[http://git.gnu.org.ua/cgit/gsc/m4env.git/][wrapper program]]. However, the shortcomings of both
+became apparent and the need of something more convenient motivated
+the inception of this utility.
+
+* Variable references
+
+The input text can reference the environment variables using the
+following constructs:
+
+- $ _variable_
+
+ The value of _variable_ is substituted.
+
+- ${ _variable_ }
+
+ The value of _variable_ is substituted.
+
+- ${ _variable_ :- _word_ }
+
+ If _variable_ is unset or null, the expansion of _word_ is substituted.
+ Otherwise, the value of _variable_ is substituted.
+
+- ${ _variable_ := _word_ }
+
+ If _variable_ is unset or null, the expansion of _word_ is
+ assigned to _variable_. The value of _variable_ is then substituted.
+
+- ${ _variable_ :? _word_ }
+
+ If _variable_ is null or unset, the expansion of _word_ (or a
+ message to that effect if word is not present) is output to standard error.
+ Otherwise, the value of _variable_ is substituted.
+
+- ${ _variable_ :+ _word_ }
+
+ If _variable_ is null or unset, nothing is substituted, otherwise the
+ expansion of _word_ is substituted.
+
+- ${ _variable_ :| _word1_ | _word2_ }
+
+ Unless _variable_ is null or unset, substitues the expansion of
+ _word1_, otherwise the expansion of _word2_.
+
+In the constructs above the colon can be omitted, resulting in a test
+only for a variable that is unset.
+
+The _indirection operator_ *$* can be changed to another symbol using
+the command line option *-S*.
+
+* Documentation
+
+The documentaion for *xenv* is [[http://man.gnu.org.ua/manpage/?1+xenv][available online]].
+
+* Downloads
+
+Download the [[https://download.gnu.org.ua/release/xenv/xenv-1.1.tar.gz][latest version]] of *xenv*.
+
+The tarball is signed using the author's GPG key. To verify it,
+import the author's key using the following command:
+
+#+BEGIN_SRC shell-script
+gpg --keyserver keys.gnupg.net --recv-keys 3602B07F55D0C732
+#+END_SRC
+
+Then, download the [[https://download.gnu.org.ua/release/xenv/xenv-1.1.tar.gz.sig][signature]] file and run
+
+#+BEGIN_SRC shell-script
+gpg --verify xenv-1.1.tar.gz
+#+END_SRC
+
+Checksums for this tarball are [[https://puszcza.gnu.org.ua/forum/forum.php?forum_id=1270][listed here]].
+
+This and other versions of the utility can be downloaded from
+https://download.gnu.org.ua/release/xenv (the *ftp* protocol
+is also supported).
+
+** Other references:
+
+- [[https://puszcza.gnu.org.ua/projects/xenv][Project development page]]
+
+- [[http://git.gnu.org.ua/cgit/xenv.git][Git repository]]
+
+* Bug reports
+
+If you think you found a bug in *xenv* or in its documentation, please
+send a mail to [[mailto:gray@gnu.org][Sergey Poznyakoff]] or use the web [[https://puszcza.gnu.org.ua/bugs/?group=xenv][bug tracker]].
+
+* Copyright
+
+Copyright (C) 2021 Sergey Poznyakoff
+
+Permission is granted to anyone to make or distribute verbatim copies
+of this document as received, in any medium, provided that the
+copyright notice and this permission notice are preserved,
+thus giving the recipient permission to redistribute in turn.
+
+Permission is granted to distribute modified versions
+of this document, or of portions of it,
+under the above conditions, provided also that they
+carry prominent notices stating who last changed them.
+
+* Document settings :noexport:
+
+Please ignore this section. It supplies the variables necessary for
+proper rendering of this document.
+
+:PROPERTIES:
+:VISIBILITY: folded
+:END:
+
+#+TITLE: xenv
+#+STARTUP: showall
+#+EXCLUDE_TAGS: noexport
+#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style.css" />
+#+OPTIONS: ^:nil
+
+# Local Variables:
+# mode: org
+# paragraph-separate: "[ ^L]*$"
+# version-control: never
+# End:
diff --git a/org2html.el b/org2html.el
new file mode 100644
index 0000000..8556e3f
--- /dev/null
+++ b/org2html.el
@@ -0,0 +1,7 @@
+(let ((bufname (car command-line-args-left))
+ (target (car (cdr command-line-args-left))))
+ (set-buffer (find-file bufname))
+ (let ((name (org-html-export-to-html)))
+ (if target
+ (rename-file name target t))
+ (kill-buffer (current-buffer))))
diff --git a/style.css b/style.css
new file mode 100644
index 0000000..2304fb5
--- /dev/null
+++ b/style.css
@@ -0,0 +1,85 @@
+/* Basic settings */
+body {
+ margin-left: auto;
+ margin-right: auto;
+ max-width: 80em;
+ background-color: silver;
+ padding: 4px;
+}
+html {}
+div {
+ background-color: white;
+}
+
+div#content {
+ margin-top: 2em;
+ margin-left: 5%;
+ margin-right: 5%;
+ padding: 1em;
+ border: 1px solid black;
+}
+
+div#postamble {
+ margin-bottom: 2em;
+ margin-left: 5%;
+ margin-right: 5%;
+ border: 1px solid black;
+ font-size: 80%;
+ padding: 4px;
+}
+
+.title { text-align: center; }
+.todo { color: red; }
+.done { color: green; }
+.tag { background-color: #add8e6; font-weight:normal }
+.target { }
+.timestamp { color: #bebebe; }
+.timestamp-kwd { color: #5f9ea0; }
+.right {margin-left:auto; margin-right:0px; text-align:right;}
+.left {margin-left:0px; margin-right:auto; text-align:left;}
+.center {margin-left:auto; margin-right:auto; text-align:center;}
+p.verse { margin-left: 3% }
+pre {
+ border: 1pt solid #AEBDCC;
+ background-color: #F3F5F7;
+ padding: 5pt;
+ font-family: courier, monospace;
+ font-size: 90%;
+ overflow:auto;
+}
+table { border-collapse: collapse; }
+td, th { vertical-align: top; }
+th.right { text-align:center; }
+th.left { text-align:center; }
+th.center { text-align:center; }
+td.right { text-align:right; }
+td.left { text-align:left; }
+td.center { text-align:center; }
+dt { font-weight: bold; }
+div.figure { padding: 0.5em; }
+div.figure p { text-align: center; }
+div.inlinetask {
+ padding:10px;
+ border:2px solid gray;
+ margin:10px;
+ background: #ffffcc;
+}
+textarea { overflow-x: auto; }
+.linenr { font-size:smaller }
+.code-highlighted {
+ background-color:#ffff00;
+}
+.org-info-js_info-navigation {
+ border-style:none;
+}
+#org-info-js_console-label {
+ font-size:10px;
+ font-weight:bold;
+ white-space:nowrap;
+}
+.org-info-js_search-highlight {
+ background-color:#ffff00;
+ color:#000000;
+ font-weight:bold;
+}
+

Return to:

Send suggestions and report system problems to the System administrator.