From 8240f410c70c830849c10505a7526dae5018a12b Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Sun, 14 Feb 2021 17:42:09 +0200 Subject: Initial commit --- .gitignore | 4 ++ Makefile | 20 +++++++++ index.org | 142 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ org2html.el | 7 +++ style.css | 85 ++++++++++++++++++++++++++++++++++++ 5 files changed, 258 insertions(+) create mode 100644 .gitignore create mode 100644 Makefile create mode 100644 index.org create mode 100644 org2html.el create mode 100644 style.css 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: +#+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; +} + -- cgit v1.2.1