[pkgsrc/trunk]: pkgsrc/doc/guide/files guide: document how to test yes/no var...

[rillig <rillig%pkgsrc.org@localhost>]

details:   https://anonhg.NetBSD.org/pkgsrc/rev/dc0b4d15ded1
branches:  trunk
changeset: 388404:dc0b4d15ded1
user:      rillig <rillig%pkgsrc.org@localhost>
date:      Fri Nov 18 19:35:03 2022 +0000

description:
guide: document how to test yes/no variables

https://mail-index.netbsd.org/tech-pkg/2022/11/16/msg026992.html

diffstat:

 doc/guide/files/makefile.xml |  30 ++++++++++++++++++++++++++----
 1 files changed, 26 insertions(+), 4 deletions(-)

diffs (62 lines):

diff -r b7997a813a4c -r dc0b4d15ded1 doc/guide/files/makefile.xml
--- a/doc/guide/files/makefile.xml      Fri Nov 18 18:55:37 2022 +0000
+++ b/doc/guide/files/makefile.xml      Fri Nov 18 19:35:03 2022 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: makefile.xml,v 1.30 2019/04/28 11:16:07 rillig Exp $ -->
+<!-- $NetBSD: makefile.xml,v 1.31 2022/11/18 19:35:03 rillig Exp $ -->
 
 <chapter id="makefile"> <?dbhtml filename="makefile.html"?>
   <title>Programming in <filename>Makefile</filename>s</title>
@@ -47,13 +47,13 @@
     <filename>wrong</filename> will exist, although there was an error
     message in the first run. On the other hand, running <command>make
     correct</command> gives an error message twice, as expected.</para>
-    
+
     <para>You might remember that &man.make.1; sometimes removes
     <literal>${.TARGET}</literal> in case of error, but this only
     happens when it is interrupted, for example by pressing
     <literal>Ctrl+C</literal>. This does <emphasis>not</emphasis> happen
     when one of the commands fails (like &man.false.1; above).</para>
-    
+
     </listitem>
     </itemizedlist>
   </sect1>
@@ -229,7 +229,7 @@
 To fix this syntax error, use one of the snippets below.</para>
 
 <programlisting>
-EMPTY=          # empty
+EGFILES=        # empty
 
 install-examples:
         for egfile in ${EGFILES} ""; do         \
@@ -257,5 +257,27 @@
 the following code: <code>${TEST} -z ${POSSIBLY_EMPTY:Q}""</code>.</para>
 
 </sect2>
+
+<sect2 id="makefile.yesno">
+<title>Testing yes/no variables in conditions</title>
+
+<para>When a variable can have the values <literal>yes</literal> or
+<literal>no</literal>, use the following pattern to test the variable:</para>
+
+<programlisting>
+.if ${VAR:U:tl} == "yes"
+# do something
+.endif
+</programlisting>
+
+<para>The <literal>:U</literal> modifier is only necessary if the variable
+can be undefined. If the variable is guaranteed to be defined, the
+<literal>:U</literal> can be omitted.</para>
+
+<para>The <literal>:tl</literal> modifier converts the variable value to
+lowercase, allowing for the values <literal>yes</literal>,
+<literal>Yes</literal>, <literal>YES</literal>.</para>
+
+</sect2>
 </sect1>
 </chapter>