dpkg-buildflags(1): Document export mode usage

Closes: #691449

[guillem@debian.org:
 - Move examples to an EXAMPLES section.
 - Add an --export=configure example on $(MAKE). ]

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Guillem Jover <guillem@debian.org>

debian/changelog

@@ -41,6 +41,8 @@ dpkg (1.17.0) UNRELEASED; urgency=low
     Closes: #635117
   * Also check Build-Depends-Arch for minimal versions in dpkg-shlibdeps.
     Closes: #681470
+  * Document dpkg-buildflags export mode usage in man page. Closes: #691449
+    Thanks to Jonathan Nieder <jrnieder@gmail.com>.
 
  -- Guillem Jover <guillem@debian.org>  Fri, 03 Aug 2012 13:21:00 +0200
 

man/dpkg-buildflags.1

@@ -83,14 +83,27 @@ keeps a clear trace of the build flags used. This can be useful to diagnose
 problems related to them.
 .TP
 .BI \-\-export= format
-Print to standard output shell (if \fIformat\fP is \fBsh\fP) or make
-(if \fIformat\fP is \fBmake\fP) commands that can be used to export
-all the compilation flags in the environment. If \fIformat\fP is
-\fBconfigure\fP then the output can be used on a \fB./configure\fP
-command-line. If the \fIformat\fP value is not
+Print to standard output commands that can be used to export all the
+compilation flags for some particular tool. If the \fIformat\fP value is not
 given, \fBsh\fP is assumed. Only compilation flags starting with an
 upper case character are included, others are assumed to not be suitable
-for the environment.
+for the environment. Supported formats:
+.RS
+.TP
+.B sh
+Shell commands to set and export all the compilation flags in the
+environment. The flag values are quoted so the output is ready for
+evaluation by a shell.
+.TP
+.B configure
+Arguments to pass to a GNU-style configuration script to use all
+the compilation flags. The flag values are quoted in shell syntax.
+.TP
+.B make
+Make directives to set and export all the compilation flags in the
+environment. Output can be written to a makefile fragment and
+evaluated using an \fBinclude\fP directive.
+.RE
 .TP
 .BI \-\-get " flag"
 Print the value of the flag on standard output. Exits with 0
@@ -309,3 +322,32 @@ System wide configuration file.
 .TP
 .BR $XDG_CONFIG_HOME/dpkg/buildflags.conf " or " $HOME/.config/dpkg/buildflags.conf
 User configuration file.
+.
+.SH EXAMPLES
+To pass build flags to a build command in a makefile:
+.PP
+.RS 4
+.nf
+$(MAKE) $(shell dpkg\-buildflags \-\-export=configure)
+
+\&./configure $(shell dpkg\-buildflags \-\-export=configure)
+.fi
+.RE
+.PP
+To set build flags in a shell script or shell fragment, "eval" can be
+used to interpret the output and to export the flags in the environment:
+.PP
+.RS 4
+.nf
+eval "$(dpkg\-buildflags \-\-export=sh)" && make
+.fi
+.RE
+.PP
+or to set the positional parameters to pass to a command:
+.PP
+.RS 4
+.nf
+eval "set \-\- $(dpkg\-buildflags \-\-export=configure)"
+for dir in a b c; do (cd $dir && ./configure "$@" && make); done
+.fi
+.RE