Tweaks to variant dir documentation [skip appveyor]

Manpage/shared VariantDir function wording tries to make more
clear that build happens in the variant. Other tweaking.

User guide variant description similarly updated. A (worded) example
of why one might want variants is added.

Formerly separate chapter doc/user/variants.xml is now included
as a section in the previous chapter.  An additional example
is enabled (was in the file but commented out), which some
introductiory wording. The introduction to the other sample
in the file is also built up slightly.

Dropped embedded comments that were the old Cons documentation
for these topics.

Signed-off-by: Mats Wichmann <mats@linux.com>

1 files changed, 2 insertions, 0 deletions

diff --git a/doc/generated/examples/separate_ex1_1.xml b/doc/generated/examples/separate_ex1_1.xml
index 6efc16f..803bc4f 100644
--- a/doc/generated/examples/separate_ex1_1.xml
+++ b/doc/generated/examples/separate_ex1_1.xml
@@ -3,6 +3,8 @@ SConscript  hello.c
 % <userinput>scons -Q</userinput>
 cc -o build/hello.o -c build/hello.c
 cc -o build/hello build/hello.o
+% <userinput>ls src</userinput>
+SConscript  hello.c
 % <userinput>ls build</userinput>
 SConscript  hello  hello.c  hello.o
 </screen>