From 910b33f06a16362f8a41114894d977df928c18fc Mon Sep 17 00:00:00 2001
From: John Ankarstrom <john@ankarstrom.se>
Date: Wed, 7 Jul 2021 17:09:21 +0200
Subject: build.1: Clarify target parsing

---
 build.1 | 38 ++++++++++++++++++++++++++++++--------
 1 file changed, 30 insertions(+), 8 deletions(-)

diff --git a/build.1 b/build.1
index b3beb4e..3d8fcda 100644
--- a/build.1
+++ b/build.1
@@ -30,26 +30,42 @@ is decidedly not a
 .Xr make 1
 replacement, except in trivial cases.
 In such cases, however,
-it is quite a nice and simple solution.
-It is originally designed for generating
+it is a nice and simple solution.
+The program is originally designed for generating
 .Xr troff 1
 documents,
 but can be used with arbitrary source files.
+.
+.Sh SYNTAX
 .Pp
 The first twenty lines of each
 .Ar file
 are scanned for build information.
 Build information is encoded in two ways:
 .Bl -tag -width indent
-.It command line
-[anything] <whitespace> "$ " <shell command> [">" <target>]
-.It dependency line
+.It command line (one or more)
+[anything] <whitespace> "$ " <shell command>
+.It dependency line (only one)
 [anything] <whitespace> "% " <files separated by whitespace>
 .El
 .Pp
-There can be multiple command lines,
-but only one dependency line.
-The last target read is regarded as the true target.
+Within each command line,
+.Nm
+searches for a
+.Em target :
+.Bl -tag -width indent
+.It target
+.br
+">" <filename without whitespace>
+.El
+.Pp
+The last target found will be counted
+as the real target for the build process.
+If no target is found,
+the commands will always be executed,
+regardless of modification times.
+.
+.Sh OPERATION
 .Pp
 Unlike
 .Xr make 1 ,
@@ -80,6 +96,12 @@ $ build prg.c
 .Pp
 will build
 .Pa prg .
+(Because
+.Xr cc 1
+does not print the built file on standard output,
+a commented
+.Ql > prg
+is necessary to set the target correctly.
 .Pp
 Assuming that the file
 .Pa doc.t
-- 
cgit v1.2.3