Change programs' interfaces

README.adoc

@@ -1,4 +1,4 @@
-A set of build scripts for Gnu Privacy Guard.
+A set of build scripts for GNU Privacy Guard.
 
 image:https://img.shields.io/travis/riboseinc/gpg-build-scripts/master.svg["Build Status", link="https://travis-ci.org/riboseinc/gpg-build-scripts"]
 
@@ -12,8 +12,8 @@ https://gist.github.com/mattrude/3883a3801613b048d45b#gistcomment-2378027).
 
 When building from Git, additional software is needed, in particular Git,
 Automake, and more recent version of Gettext.  Note that Gettext available in
-Ubuntu Trusty is too old for this purpose, and that makes building from Git
-in Travis CI environment bit more difficult.
+Ubuntu Trusty is too old for this purpose--this fact must be taken into account
+when building from Git in Travis CI environment.
 
 == Scripts
 
@@ -23,48 +23,55 @@ the `examples` subdirectory.
 
 === `install_gpg_component.sh`
 
-Builds and installs a specific component of GPG.
+Builds and installs a specific component of GnuPG.  The source code is obtained
+either from released tarballs, or from Git repository.
 
-Two options are mandatory:
+When building stable releases from tarballs, two options are mandatory:
 
-* `--component`, which specifies a component name
-* `--version`, which specifies component version (can be `latest`)
+* `--component-name`, which specifies a component name
+* `--component-version`, which specifies component version (can be `latest`)
 
-For example, following snippet will build and install the most recent release
-of Pinentry:
+.Example: building the most recent release of Pinentry.
+[source,bash]
+----
+./install_gpg_component.sh \
+  --component-name pinentry \
+  --component-version latest
+----
 
+.Example: building Pinentry version 1.1.0.
 [source,bash]
 ----
 ./install_gpg_component.sh \
-  --component pinentry \
-  --version latest
+  --component-name pinentry \
+  --component-version 1.1.0
 ----
 
-Furthermore, script is capable of fetching source from Git repository (instead
-of downloading tarballs with stable releases).  In such case, a `--git` option
-should be supplied, and `--version` should specify the desired Git ref. For
-example, following will build the current master of Pinentry component:
+When building from Git repository, two options are mandatory:
+
+* `--component-name`, which specifies a component name
+* `--component-git-ref`, which specifies a Git branch or tag (commonly `master`)
 
+.Example: building Pinentry from Git as of current master.
 [source,bash]
 ----
 ./install_gpg_component.sh \
-  --component pinentry \
-  --version master \
-  --git
+  --component-name pinentry \
+  --component-git-ref master
 ----
 
-Run script with `--help` option in order to display a more detailed
-documentation:
+Run script with `--help` option in order to list all available options:
 
+.Example: printing script help.
 [source,bash]
 ----
 ./install_gpg_component.sh --help
 ----
 
 === `install_gpg_all.sh`
 
-Builds and installs all components of GPG.  The first parameter describes
-the desired version of GPG.  Supported values are: `2.1`, `2.2`, `latest`, and
+Builds and installs all components of GnuPG.  The first parameter describes
+the desired version of GnuPG.  Supported values are: `2.1`, `2.2`, `latest`, and
 `master`.  Other components are installed in best-matching versions, which is
 defined as follows:
 
@@ -77,14 +84,13 @@ Prefer `latest` over `2.2`.
 
 Any other parameters supplied will be passed to `install_gpg_component.sh`.
 
-For example, following snippet will install the freshest GPG, and its components
-without documentation:
+For example, following snippet will install the freshest GnuPG, and its
+components without documentation:
 
 [source,bash]
 ----
 ./install_gpg_all.sh \
   latest \
-  --build-dir ~/build-gpg \
   --configure-opts "--disable-doc"
 ----
 
@@ -96,9 +102,8 @@ example:
 [source,bash]
 ----
 ./install_gpg_component.sh \
-  --component pinentry \
-  --version latest \
-  --build-dir ~/build-gpg \
+  --component-name pinentry \
+  --component-version latest \
   --configure-opts "--enable-pinentry-qt --enable-pinentry-curses"
 ----
 
@@ -110,7 +115,6 @@ The `./configure` script assumes that all the dependencies are installed in
 ----
 ./install_gpg_all.sh \
   latest \
-  --build-dir ~/build-gpg \
   --configure-opts "\
     --prefix=/opt/gpg \
     --with-libgpg-error-prefix=/opt/gpg \

examples/all_2.1.sh

@@ -13,7 +13,7 @@ set -v # Print executed lines
 # Note that `sudo ./install_gpg_all …` is not the same—it would compile as
 # root (not recommended), and won't trigger post-install steps (including
 # ldconfig).
-./install_gpg_all.sh 2.1 --sudo
+./install_gpg_all.sh --suite-version 2.1 --sudo
 
 ###############
 #    TESTS    #

examples/all_2.2.sh

@@ -13,7 +13,7 @@ set -v # Print executed lines
 # Note that `sudo ./install_gpg_all …` is not the same—it would compile as
 # root (not recommended), and won't trigger post-install steps (including
 # ldconfig).
-./install_gpg_all.sh 2.2 --sudo
+./install_gpg_all.sh --suite-version 2.2 --sudo
 
 ###############
 #    TESTS    #

examples/all_head.sh

@@ -14,7 +14,7 @@ set -v # Print executed lines
 # Note that `sudo ./install_gpg_all …` is not the same—it would compile as
 # root (not recommended), and won't trigger post-install steps (including
 # ldconfig).
-./install_gpg_all.sh master --sudo
+./install_gpg_all.sh --suite-version master --sudo
 
 ###############
 #    TESTS    #

examples/all_latest.sh

@@ -14,7 +14,7 @@ set -v # Print executed lines
 # Note that `sudo ./install_gpg_all …` is not the same—it would compile as
 # root (not recommended), and won't trigger post-install steps (including
 # ldconfig).
-./install_gpg_all.sh latest --sudo
+./install_gpg_all.sh --suite-version latest --sudo
 
 ###############
 #    TESTS    #

examples/build_dir.sh

@@ -22,7 +22,7 @@ mkdir -p ${BUILD_DIR}
 # Note that `sudo ./install_gpg_all …` is not the same—it would compile as
 # root (not recommended), and won't trigger post-install steps (including
 # ldconfig).
-./install_gpg_all.sh 2.2 --sudo --build-dir ${BUILD_DIR}
+./install_gpg_all.sh --suite-version 2.2 --sudo --build-dir ${BUILD_DIR}
 
 ###############
 #    TESTS    #

examples/components_individually.sh

@@ -22,15 +22,15 @@ BUILD_DIR="${TRAVIS_BUILD_DIR}/b"
 # libgpg-error, and enable it (default) for other components.
 # In order to satisfy dependencies, components should be installed
 # in a specific order.
-./install_gpg_component.sh --component libgpg-error --version latest --sudo \
+./install_gpg_component.sh --component-name libgpg-error --component-version latest --sudo \
   --configure-opts "--disable-doc"
-./install_gpg_component.sh --component libgcrypt --version latest --sudo \
+./install_gpg_component.sh --component-name libgcrypt --component-version latest --sudo \
   --build-dir "${BUILD_DIR}"
-./install_gpg_component.sh --component libassuan --version latest --sudo
-./install_gpg_component.sh --component libksba --version latest --sudo
-./install_gpg_component.sh --component npth --version latest --sudo
-./install_gpg_component.sh --component pinentry --version 1.1.0 --sudo
-./install_gpg_component.sh --component gnupg --version 2.2.10  --sudo \
+./install_gpg_component.sh --component-name libassuan --component-version latest --sudo
+./install_gpg_component.sh --component-name libksba --component-version latest --sudo
+./install_gpg_component.sh --component-name npth --component-version latest --sudo
+./install_gpg_component.sh --component-name pinentry --component-version 1.1.0 --sudo
+./install_gpg_component.sh --component-name gnupg --component-version 2.2.10  --sudo \
   --configure-opts "--enable-gpg-sha256 --disable-gpg-sha512 --enable-doc"
 
 ###############

examples/configure_options.sh

@@ -14,7 +14,7 @@ set -v # Print executed lines
 # --enable-gpg-sha256 and --disable-gpg-sha512 are relevant to GnuPG component,
 # whereas --disable-doc is relevant for all components.  This is okay, however
 # warnings will be printed.
-./install_gpg_all.sh latest --sudo --configure-opts "--disable-doc \
+./install_gpg_all.sh --suite-version latest --sudo --configure-opts "--disable-doc \
 	--enable-pinentry-curses --enable-gpg-sha256 --disable-gpg-sha512"
 
 ###############

examples/folding_travis.sh

@@ -14,7 +14,7 @@ set -v # Print executed lines
 # Note that `sudo ./install_gpg_all …` is not the same—it would compile as
 # root (not recommended), and won't trigger post-install steps (including
 # ldconfig).
-./install_gpg_all.sh latest --sudo --folding-style travis | tee ./output
+./install_gpg_all.sh --suite-version latest --sudo --folding-style travis | tee ./output
 
 ###############
 #    TESTS    #

examples/install_prefix.sh

@@ -33,7 +33,7 @@ export PATH="${EXEC_PREFIX}/bin:${PATH}"
 
 mkdir -p ${GPG_PREFIX} ${EXEC_PREFIX} ${MAN_DIR}
 
-./install_gpg_all.sh latest --sudo --configure-opts "${GPG_CONFIGURE_OPTS}"
+./install_gpg_all.sh --suite-version latest --sudo --configure-opts "${GPG_CONFIGURE_OPTS}"
 
 ###############
 #    TESTS    #

examples/no_sudo.sh

@@ -29,7 +29,7 @@ export PATH="${GPG_PREFIX}/bin:${PATH}"
 
 mkdir -p ${GPG_PREFIX}
 
-./install_gpg_all.sh latest --no-sudo --configure-opts "${GPG_CONFIGURE_OPTS}"
+./install_gpg_all.sh --suite-version latest --no-sudo --configure-opts "${GPG_CONFIGURE_OPTS}"
 
 ###############
 #    TESTS    #