size: Add '--map-file' option.

* guix/scripts/size.scm (profile->page-map): New procedures.
  (show-help, %options):  Add --map-file.
  (guix-size): Honor it.
* doc/guix.texi (Invoking guix size): Document it.
* doc/images/coreutils-size-map.png: New file.
* doc.am (dist_infoimage_DATA): Add it.

2 files changed, 14 insertions, 1 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index a669464feb..f9c9f2ab93 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -4038,10 +4038,23 @@ reports information based on information about the available substitutes
 (@pxref{Substitutes}).  This allows it to profile disk usage of store
 items that are not even on disk, only available remotely.
 
-A single option is available:
+The available options are:
 
 @table @option
 
+@item --map-file=@var{file}
+Write to @var{file} a graphical map of disk usage as a PNG file.
+
+For the example above, the map looks like this:
+
+@image{images/coreutils-size-map,5in,, map of Coreutils disk usage
+produced by @command{guix size}}
+
+This option requires that
+@uref{http://wingolog.org/software/guile-charting/, Guile-Charting} be
+installed and visible in Guile's module search path.  When that is not
+the case, @command{guix size} fails as it tries to load it.
+
 @item --system=@var{system}
 @itemx -s @var{system}
 Consider packages for @var{system}---e.g., @code{x86_64-linux}.
diff --git a/doc/images/coreutils-size-map.png b/doc/images/coreutils-size-map.png
new file mode 100644
index 0000000000..21d73a8458
--- /dev/null
+++ b/doc/images/coreutils-size-map.png