Commit Graph

56 Commits

Author SHA1 Message Date
Cyril Roelandt 9c0fc27968 ui: add the "dependencies" field to package->recutils:
* guix/ui.scm (package->recutils): Print the dependencies of the package.
2014-07-21 22:17:59 +02:00
Ludovic Courtès 07254feb24 ui: Avoid circularity with (guix gexp).
Fixes a regression introduced in 56b8210 ("guix build: Allow gexps to be
passed to '-e'.")

* guix/ui.scm (%guix-user-module): Wrap in 'delay'.
  (read/eval): Adjust accordingly.
2014-06-14 23:23:56 +02:00
Ludovic Courtès 56b8210697 guix build: Allow gexps to be passed to '-e'.
* guix/ui.scm (%guix-user-module): New variable.
  (read/eval): Pass it as the second argument to 'eval'.
* guix/scripts/build.scm (options/resolve-packages): Add case for
  'gexp?'.
* tests/guix-build.sh: Add tests.
* doc/guix.texi (Invoking guix build): Document '-e gexp'.
guxi build: Allow gexps to be passed to '-e'.

* guix/ui.scm (%guix-user-module): New variable.
  (read/eval): Pass it as the second argument to 'eval'.
* guix/scripts/build.scm (options/resolve-packages): Add case for
  'gexp?'.
* tests/guix-build.sh: Add tests.
* doc/guix.texi (Invoking guix build): Document '-e gexp'.
2014-06-14 22:55:59 +02:00
Ludovic Courtès ee76417972 Separate package description translations from string translations.
* po/packages/LINGUAS, po/packages/Makevars, po/packages/POTFILES.in:
  New files.
* po/guix/Makevars (DOMAIN): Change to "guix".
  (XGETTEXT_OPTIONS): Remove "--keyword=synopsis --keyword=description".
* po/guix/POTFILES.in: Remove gnu/packages/*.scm.
* configure.ac: Change to gettext 0.18.3.  Produce
  po/packages/Makefile.in.
* Makefile.am (SUBDIRS): Add po/packages.
* guix/ui.scm (%package-text-domain): New variable.
  (P_): New procedure.
  (package->recutils): Use 'P_' instead of '_'.
* guix/scripts/package.scm (find-packages-by-description): Use 'P_'
  instead of 'gettext'.
2014-06-13 17:30:40 +02:00
Ludovic Courtès 52ddf2ae6f ui: Gracefully deal with zero-output derivations.
* guix/ui.scm (show-what-to-build)[built-or-substitutable?]: New
  procedure.  Check whether OUT is #f.
  Use it.
* tests/ui.scm ("show-what-to-build, zero outputs"): New test.
2014-05-19 23:52:40 +02:00
Ludovic Courtès ada3df03e3 monads: Hide 'derivation-expression' and 'lower-inputs'.
* guix/monads.scm: Unexport 'lower-inputs' and 'derivation-expression'.
  (text-file*): Add comment about the switch to 'gexp->derivation'.
  (lower-inputs): Add comment about its doom.
  (derivation-expression): Likewise.
* guix/gexp.scm (lower-inputs*): Rename to...
  (lower-inputs): ... this.  Update callers.
* tests/monads.scm (derivation-expression): New procedure.
* doc/guix.texi (The Store Monad): Use 'gexp->derivation' instead of
  'derivation-expression'.  Remove documentation of
  'derivation-expression'.
* guix/ui.scm (read/eval): Use THE-ROOT-MODULE so that macros are
  properly expanded.
* tests/guix-build.sh: Use 'gexp->derivation' instead of
  'derivation-expression'.monads: Hide 'derivation-expression' and 'lower-inputs'.
2014-04-28 23:41:12 +02:00
Ludovic Courtès 1d6243cf70 ui: Add 'size->number'.
* guix/scripts/gc.scm (size->number): Remove.
* guix/ui.scm (size->number): New procedure.
* tests/ui.scm ("size->number, bytes",
  "size->number, MiB", "size->number, GiB", "size->number, 1.2GiB",
  "size->number, invalid unit"): New tests.
2014-04-08 22:01:44 +02:00
Ludovic Courtès bde8c0e6d9 ui: Improve reporting of 'system-error' exceptions.
* guix/ui.scm (call-with-error-handling): Change 'system-error' handler
  to display the error message as it was raised.
2014-04-04 22:04:43 +02:00
Ludovic Courtès c1d52c71aa ui: Handle SRFI-35 '&message' conditions.
* guix/ui.scm (call-with-error-handling): Add case for
  'message-condition?'.
* po/Makevars: Fix typo in comment.
2014-02-21 23:49:52 +01:00
Ludovic Courtès 49e6291a7a Add 'guix offload' as a daemon build hook.
* nix/nix-daemon/guix-daemon.cc (GUIX_OPT_NO_BUILD_HOOK): New macro.
  (options): Add '--no-build-hook'.
  (parse_opt): Handle it.
  (main)[HAVE_DAEMON_OFFLOAD_HOOK]: Set 'useBuildHook' by default.
  Set $NIX_BUILD_HOOK to our offload hook unless otherwise specified.
  [!HAVE_DAEMON_OFFLOAD_HOOK]: Clear 'useBuildHook'.
* pre-inst-env.in: Set and export NIX_BUILD_HOOK.
* nix/scripts/offload.in, guix/scripts/offload.scm: New files.
* guix/ui.scm (show-guix-help)[internal?]: Add "offload".
* config-daemon.ac: Call 'GUIX_CHECK_UNBUFFERED_CBIP'.
  Instantiate 'nix/scripts/offload'.  Set 'BUILD_DAEMON_OFFLOAD'
  conditional, and optionally define 'HAVE_DEAMON_OFFLOAD_HOOK' cpp
  macro.
* daemon.am (nodist_pkglibexec_SCRIPTS)[BUILD_DAEMON_OFFLOAD]: Add it.
* Makefile.am (MODULES)[BUILD_DAEMON_OFFLOAD]: Add
  'guix/scripts/offload.scm'.
  (EXTRA_DIST)[!BUILD_DAEMON_OFFLOAD]: Likewise.
* m4/guix.m4 (GUIX_CHECK_UNBUFFERED_CBIP): New macro.
* doc/guix.texi (Setting Up the Daemon): Move most of the body to...
  (Build Environment Setup): ... this.  New subsection.
  (Daemon Offload Setup): New subsection.
2014-01-24 00:01:50 +01:00
Ludovic Courtès 59f734f351 ui: Filter out internal commands from '--help'.
* guix/ui.scm (show-guix-help)[internal?]: New procedure.
  Use it to filter out internal commands reported by '--help'.
2014-01-24 00:01:49 +01:00
Ludovic Courtès c5e0eb2884 ui: Update copyright year in '--version' output.
* guix/ui.scm (show-version-and-exit): Increment copyright year.
2014-01-17 22:49:42 +01:00
Ludovic Courtès 8fa3e6b338 ui: Don't use hyphens in 'package->recutils' output.
* guix/ui.scm (package->recutils): Rename recutils field from
  'home-page' to 'homepage'.
2014-01-13 18:49:26 +01:00
Ludovic Courtès ac5de156ae guix build: '-e' can be passed a monadic thunk.
* guix/ui.scm (read/eval): New procedure.
  (read/eval-package-expression): Use it.
* guix/scripts/build.scm (derivations-from-package-expressions): Rename to...
  (derivation-from-expression): ... this.  Accept procedures, under the
  assumption that they are monadic thunk.
  (show-help): Adjust accordingly.
  (guix-build): Ditto.
* tests/guix-build.sh: Add test.
* doc/guix.texi (Invoking guix build): Augment description of '-e'.
2013-11-18 23:08:20 +01:00
Ludovic Courtès 64a967cc9c ui: Make '--version' output GCS-compliant.
* guix/ui.scm (show-version-and-exit): Display copyright year, license,
  and LACK OF WARRANTY.
2013-11-03 23:09:30 +01:00
Ludovic Courtès 2876b98925 ui: Factorize package specification parsing.
* guix/ui.scm (package-specification->name+version+output): New
  procedure.
* guix/scripts/package.scm (specification->package+output): Use it.
* tests/ui.scm ("package-specification->name+version+output"): New test.
2013-11-01 23:21:00 +01:00
Ludovic Courtès 39e9f95d05 guix: Add missing call to 'bindtextdomain'.
* scripts/guix.in (config-lookup): Add "localedir" entry.
  (run-guix-main): Add call to 'bindtextdomain'.
* guix/ui.scm (initialize-guix): Use %GETTEXT-DOMAIN instead of a
  literal.
2013-10-12 22:29:31 +02:00
Nikita Karetnikov 2cd09108c9 guix package: Add '--list-generations'.
* guix/scripts/package.scm: Import (srfi srfi-19).
  (generation-time, matching-generations): New functions.
  (show-help): Add '--list-generations'.
  (%options): Likewise.
  (guix-package)[process-query]: Add support for '--list-generations'.
* guix/ui.scm: Import (srfi srfi-19) and (ice-9 regex).
  (string->generations, string->duration): New functions.
* tests/guix-package.sh: Test '--list-generations'.
* tests/ui.scm: Import (srfi srfi-19).
  Test 'string->generations' and 'string->duration'.
* doc/guix.texi (Invoking guix-package): Document '--list-generations'.
2013-09-19 11:22:31 +00:00
Ludovic Courtès 59688fc4b5 derivations: 'derivation' and related procedures return a single value.
* guix/derivations.scm (derivation->output-path,
  derivation->output-paths): New procedures.
  (derivation-path->output-path): Use 'derivation->output-path'.
  (derivation-path->output-paths): Use 'derivation->output-paths'.
  (derivation): Accept 'derivation?' objects as inputs.  Return a single
  value.
  (build-derivations): New procedure.
  (compiled-modules): Use 'derivation->output-paths'.
  (build-expression->derivation)[source-path]: Add case for when the
  input matches 'derivation?'.
  [prologue]: Accept 'derivation?' objects in INPUTS.
  [mod-dir, go-dir]: Use 'derivation->output-path'.
* guix/download.scm (url-fetch): Adjust to the single-value return.
* guix/packages.scm (package-output): Use 'derivation->output-path'.
* guix/scripts/build.scm (guix-build): When the argument is
  'derivation-path?', pass it through 'read-derivation'.
  Use 'derivation-file-name' to print out the .drv file names, and to
  register them.  Use 'derivation->output-path' instead of
  'derivation-path->output-path'.
* guix/scripts/package.scm (roll-back): Adjust to the single-value
  return.
  (guix-package): Use 'derivation->output-path'.
* guix/ui.scm (show-what-to-build): Adjust to deal with 'derivation?'
  objects instead of .drv file names.
* gnu/system/grub.scm (grub-configuration-file): Use
  'derivation->output-path' instead of 'derivation-path->output-path'.
* gnu/system/vm.scm (qemu-image, system-qemu-image): Likewise.
* tests/builders.scm, tests/derivations.scm, tests/packages.scm,
  tests/store.scm, tests/union.scm: Adjust to the new calling
  convention.
* doc/guix.texi (Defining Packages, The Store, Derivations): Adjust
  accordingly.
2013-09-18 18:49:53 +02:00
Ludovic Courtès 00554b2a0f substitute-binary: Show the Nar size, when available.
* guix/scripts/substitute-binary.scm (guix-substitute-binary)["--substitute"]:
  Show the Nar size, when available.
* guix/ui.scm (show-what-to-build): Add 'TODO'.
2013-09-02 23:33:13 +02:00
Cyril Roelandt e12b3eb93e Make "guix -h" work as "guix --help".
* guix/ui.scm (guix-main): have the same behaviour for the "-h" and "--help"
  options.
2013-08-15 21:03:32 +02:00
Ludovic Courtès e14c39291b ui: Ignore SIGPIPE and catch `system-error' exceptions.
* guix/ui.scm (initialize-guix): Call `sigaction'.
  (call-with-error-handling): Wrap `thunk' in a (catch 'system-error ...).
2013-07-12 23:01:18 +02:00
Ludovic Courtès 1a8b783470 ui: Don't make substituter-related RPCs at all when substitutes are disabled.
Reported by Nikita Karetnikov and Cyril Roelandt.

* guix/ui.scm (show-what-to-build): Call `substitutable-path-info'
  only when USE-SUBSTITUTES? is true.
2013-07-01 00:30:44 +02:00
Ludovic Courtès 89d02b98f9 ui: define-diagnostic: Don't mark `_' and `N_' as literals.
* guix/ui.scm (define-diagnostic): Use `free-identifier=?' to compare
  the user's input with `_' and `N-".  This should fix builds with Guile 2.1.
  Reported by Cojocaru Alexandru <xojoc@gmx.com>.
2013-05-30 00:49:34 +02:00
Ludovic Courtès 9b222abe03 packages: Raise an error condition a cross builder is needed but unavailable.
* guix/packages.scm (&package-cross-build-system-error): New condition type.
  (package-cross-derivation): Raise &package-cross-build-system-error
  when the build system doesn't support cross builds.
* guix/ui.scm (call-with-error-handling): Add
  package-cross-build-system-error? case.
* tests/packages.scm ("package-cross-derivation, no cross builder"): New test.
2013-05-27 23:43:00 +02:00
Ludovic Courtès 969e678ed9 Add `--max-silent-time' to `guix build' and `guix package'.
* guix/scripts/build.scm (%default-options): Add default
  `max-silent-time' value.
  (show-help, %options):  Add `--max-silent-time'.
  (guix-build): Pass `max-silent-time' to `set-build-options'.
* guix/scripts/package.scm (%default-options): Add default
  `max-silent-time' value.
  (show-help, %options):  Add `--max-silent-time'.
  (guix-package): Pass `max-silent-time' to `set-build-options'.
* guix/ui.scm (string->number*): New procedure.
* tests/derivations.scm ("build-expression->derivation and
  max-silent-time"): New test.
* doc/guix.texi (Invoking guix package, Invoking guix build): Document
  `--max-silent-time'.
2013-05-20 18:29:26 +02:00
Ludovic Courtès b30b13dc3d Sort commands alphabetically in "guix --help".
* guix/ui.scm (show-guix-help): Sort commands.
2013-05-14 13:37:53 +02:00
Ludovic Courtès 2b8cf44fd9 Fix "guix --help" on Guile 2.0.5.
Reported at <http://linuxfr.org/news/sortie-de-gnu-guix-0-2>.

* guix/ui.scm (command-files): Filter the result of `scandir' to make
  sure only `.scm' files are present.
2013-05-14 13:37:21 +02:00
Ludovic Courtès 25c936766e ui: Invite users to try `--help' in the error message.
* guix/ui.scm (show-guix-usage): Mention `guix --help'.
  Suggested by Mark H. Weaver.
  (run-guix-command): Invoke it when a command is not found.
  (guix-main): Adjust accordingly.
2013-05-10 23:14:26 +02:00
Ludovic Courtès e31ff8b8d0 ui: Implement `guix --help'.
* guix/ui.scm (command-files, commands, show-guix-help): New procedures.
  (guix-main): Invoke `show-guix-help' when passed `--help'.
2013-05-10 12:33:18 +02:00
Ludovic Courtès ec5d0a85eb ui: Gracefully report "command not found" errors.
* guix/ui.scm (run-guix-command): Can `resolve-interface' errors and
  report them with `leave'.  Parameterize `program-name' from here.
  (guix-main): Remove parameterization of `program-name'.
2013-05-10 12:14:01 +02:00
Ludovic Courtès 83e61a73c4 ui: Capitalize informative messages.
* guix/ui.scm (show-what-to-build): Capitalize user messages, as per the
  GCS (info "(standards) Errors").
2013-05-07 13:28:11 +02:00
Ludovic Courtès a5975cedf2 ui: Add `args-fold*' and use it.
* guix/ui.scm (args-fold*): New procedure.
* guix/scripts/build.scm, guix/scripts/download.scm,
  guix/scripts/gc.scm, guix/scripts/hash.scm, guix/scripts/import.scm,
  guix/scripts/package.scm, guix/scripts/pull.scm,
  guix/scripts/refresh.scm: Use `args-fold*' instead of `args-fold'.
2013-04-27 16:46:39 +02:00
Ludovic Courtès 14e2afa74b ui: Use consistent spacing in `show-what-to-build' messages.
* guix/ui.scm (show-what-to-build): Use consistent spacing in "the
  following..." messages.
2013-04-27 16:37:09 +02:00
Ludovic Courtès b2a886f6c7 ui: Move macro definitions before any use.
* guix/ui.scm (define-diagnostic, warning, report-error, leave): Move
  definitions before any use.  Reported by Nikita Karetnikov.
  (install-locale): Move back close to `initialize-guix'.
2013-04-22 13:24:39 +02:00
Ludovic Courtès 861693f3e7 Factorize `download-and-store'.
* guix/download.scm (download-to-store): New procedure.
* guix/scripts/download.scm (fetch-and-store): Remove.
  (guix-download): Use `download-to-store' instead.
* guix/ui.scm (call-with-temporary-output-file): Move to...
* guix/utils.scm (call-with-temporary-output-file): ... here.
2013-04-21 22:40:40 +02:00
Ludovic Courtès 238328c990 ui: Move definition of `install-locale' after that of the `warning' macro.
* guix/ui.scm (install-locale): Move definition after that of `warning'.
2013-04-21 11:53:06 +02:00
Nikita Karetnikov 98eb8cbe8d ui: Add a 'define-diagnostic' macro.
* guix/ui.scm (define-diagnostic): New macro, which is based on the
  previous version of 'warning'.
  (warning, leave): Redefine using 'define-diagnostic'.
  (report-error): New macro.
  (install-locale): Use 'warning' instead of 'format'.
  (call-with-error-handling): Adjust 'leave'.
* gnu/packages.scm (package-files): Use 'warning' instead of 'format'.
* guix/gnu-maintenance.scm (http-fetch): Use 'warning' and 'leave'.
* guix/scripts/build.scm (derivations-from-package-expressions, guix-build):
  Adjust 'leave'.
* guix/scripts/download.scm (guix-download): Adjust 'leave'.
* guix/scripts/gc.scm (size->number, %options): Adjust 'leave'.
* guix/scripts/package.scm (roll-back, guix-package): Adjust 'leave'.
* po/POTFILES.in: Add 'guix/gnu-maintenance.scm'.
2013-04-21 08:08:40 +00:00
Ludovic Courtès 801486fe46 ui: Fix format string in `warning'.
* guix/ui.scm (warning)[augmented-format-string]: Add missing ~*.
2013-04-17 18:02:48 +02:00
Ludovic Courtès dd36b51bf7 scripts: Report what will be substituted.
* guix/derivations.scm (derivation-input-output-paths): New procedure.
  (derivation-prerequisites-to-build): New `use-substitutes?' keyword
  argument.  Change two return the list of substitutable paths as a
  second argument.
* guix/ui.scm (show-what-to-build): Turn `dry-run?' into a keyword
  argument.  New `use-substitutes?' keyword argument.  Use `fold2' and
  adjust to use both return values of
  `derivation-prerequisites-to-build'.  Display what will/would be
  downloaded.
* guix/scripts/build.scm (guix-build): Adjust accordingly.
* guix/scripts/package.scm (guix-package): Likewise.
* tests/derivations.scm ("derivation-prerequisites-to-build and
  substitutes"): New test.
2013-04-17 00:08:21 +02:00
Ludovic Courtès a2011be5df ui: Add a `warning' macro.
* guix/ui.scm (program-name, guix-warning-port): New variables.
  (warning): New macro.
  (guix-main): Parametrize PROGRAM-NAME.
* guix/scripts/build.scm, guix/scripts/download.scm,
  guix/scripts/gc.scm, guix/scripts/package.scm: Adjust to use `leave'
  and `warning' consistently.
2013-04-11 22:30:06 +02:00
Ludovic Courtès ef86c39f27 ui: Gracefully report failures to connect to the daemon.
* guix/store.scm (&nix-connection-error): New condition type.
  (open-connection): Translate `system-error' during the `connect' call
  into `&nix-connection-error'.
* guix/ui.scm (call-with-error-handling): Add case for `nix-connection-error?'.
* guix/scripts/package.scm (guix-package): Move `open-connection' call
  within `with-error-handling'.
* guix/scripts/pull.scm (guix-pull): Likewise.
* guix/scripts/download.scm (guix-download): Move body within
  `with-error-handling'.
2013-03-07 19:44:14 +01:00
Ludovic Courtès eb0880e71d ui: Factorize `read/eval-package-expression'.
* guix/scripts/package.scm (read/eval-package-expression): Move to...
* guix/ui.scm (read/eval-package-expression): ... here.
* guix/scripts/build.scm (derivations-from-package-expressions): Use it.
2013-03-01 21:55:42 +01:00
Ludovic Courtès 4d60610ad7 pull: Distinguish "already up to date" from "updated".
* guix/ui.scm (show-what-to-build): Return (length req*).
* guix/scripts/pull.scm (guix-pull): Print an "already up to date"
  message when there's nothing to build.
2013-02-22 21:08:06 +01:00
Ludovic Courtès f651b477b7 Add "guix pull".
* guix/scripts/pull.scm: New file.
* Makefile.am (MODULES): Add it.
* doc/guix.texi (Invoking guix pull): New node.
  (Invoking guix package): Add cross-ref to it.
* guix/ui.scm (config-directory): New procedure.
* scripts/guix.in: When `GUIX_UNINSTALLED' is undefined, add
  $XDG_CONFIG_HOME/guix/latest to the search path.
* po/POTFILES.in: Add guix/scripts/pull.scm.
2013-02-20 23:47:16 +01:00
Ludovic Courtès 9bb2b96aab ui: Factorize `show-what-to-build'.
* guix/scripts/package.scm (guix-package)[show-what-to-build]: Move to..
* guix/ui.scm (show-what-to-build): ... here.  Add a `store'
  parameter'.  Adjust callers.
* guix/scripts/build.scm (guix-build): Use it.  Remove `req' and `req*'
  variables.
2013-02-20 23:46:57 +01:00
Ludovic Courtès c61b026e3a ui: Add temporary file handling and atomic symlink switch.
* guix/scripts/download.scm (call-with-temporary-output-file): Move to
  ui.scm.
* guix/scripts/package.scm (switch-symlinks): Likewise.
* guix/ui.scm (call-with-temporary-output-file, switch-symlinks): New
  procedures.
2013-02-20 23:03:24 +01:00
Ludovic Courtès 633f045f62 scripts: Remove initialization now redundant with `initialize-guix'.
* guix/scripts/build.scm (guix-build): Remove calls to `install-locale',
  `textdomain', etc., now redundant with `initialize-guix'.
* guix/scripts/download.scm (guix-download): Likewise.
* guix/scripts/import.scm (guix-import): Likewise.
* guix/scripts/package.scm (guix-package): Likewise.
* guix/ui.scm: Remove export of `install-locale' and `initialize-guix'.
  (initialize-guix): Add docstring.
2013-02-17 15:38:02 +01:00
Mark H Weaver e49951eb3e Replace individual scripts with master 'guix' script.
* scripts/guix.in: New script.

* Makefile.am (bin_SCRIPTS): Add 'scripts/guix'.  Remove 'guix-build',
  'guix-download', 'guix-import', 'guix-package', and 'guix-gc'.

  (MODULES): Add 'guix/scripts/build.scm', 'guix/scripts/download.scm',
  'guix/scripts/import.scm', 'guix/scripts/package.scm', and
  'guix/scripts/gc.scm'.

* configure.ac (AC_CONFIG_FILES): Add 'scripts/guix'.  Remove 'guix-build',
  'guix-download', 'guix-import', 'guix-package', and 'guix-gc'.

* guix-build.in, guix-download.in, guix-gc.in, guix-import.in,
  guix-package.in: Remove shell script boilerplate.  Move to guix-COMMAND.in
  to guix/scripts/COMMAND.scm.  Rename module from (guix-COMMAND) to
  (guix scripts COMMAND).  Change "guix-COMMAND" to "guix COMMAND" in
  usage help string.

* pre-inst-env.in: Add "@abs_top_builddir@/scripts" to the front of $PATH.
  Export $GUIX_UNINSTALLED.

* tests/guix-build.sh, tests/guix-daemon.sh, tests/guix-download.sh,
  tests/guix-gc.sh, tests/guix-package.sh: Use "guix COMMAND" instead of
  "guix-COMMAND".

* doc/guix.texi: Replace all occurrences of "guix-COMMAND" with
  "guix COMMAND".

* po/POTFILES.in: Update.
2013-02-16 22:17:37 -05:00
Ludovic Courtès 299112d36e guix-package: Report `--search' matches in recutils format.
* guix/ui.scm (fill-paragraph, string->recutils, package->recutils): New
  procedures.
* guix-package.in (guix-package)[process-query]: Use `package->recutils'
  to display package meta-data.
* tests/guix-package.sh: Adjust test.
* tests/ui.scm: New file.
* Makefile.am (TESTS): Add it.
* doc/guix.texi (Invoking guix-package): Adjust `--search'
  documentation, and give an example.
2013-02-01 13:16:41 +01:00