document more reality.

proper english usage and okay jmc@

diff --git a/share/mk/bsd.README b/share/mk/bsd.README
index 26598b7..afbf122 100644 (file)
--- a/share/mk/bsd.README
+++ b/share/mk/bsd.README
@@ -1,4 +1,4 @@
-#      $OpenBSD: bsd.README,v 1.67 2017/07/05 10:41:01 espie Exp $
+#      $OpenBSD: bsd.README,v 1.68 2017/07/09 17:17:46 espie Exp $
 #      $NetBSD: bsd.README,v 1.17 1996/04/13 02:08:08 thorpej Exp $
 #      @(#)bsd.README  5.1 (Berkeley) 5/11/90
 
@@ -67,8 +67,8 @@ variables are expanded only when needed. Which means that, in
 
        a=      bar
 
-the command "make b" will echo "foo"; echo "bar".  The first $(a) means 
-"foo", because it's needed to generate the dependency rule when it's read, 
+the command "make b" will echo "foo"; echo "bar".  The first $(a) means
+"foo", because it's needed to generate the dependency rule when it's read,
 but the second $(a) is only expanded when needed, at which point a contains
 bar.
 
@@ -81,7 +81,10 @@ architectures so we can quit using the symbolic link stuff.  (Imake doesn't
 count.)
 
 Dependencies are handled using the compiler's -M* options, resulting in
-lots of .d files. These are manually included through bsd.dep.mk.
+lots of .d files. These are manually included through <bsd.dep.mk>.
+
+<bsd.dep.mk> also provides an empty depend target to <bsd.prog.mk> and
+<bsd.lib.mk>, for backward compatibility.
 
 The variable DESTDIR works as before.  It's not set anywhere but will change
 the tree where the file gets installed.
@@ -124,7 +127,7 @@ MLINKS              List of manual page links (using a .1 - .9 suffix).  The
                linked-to file must come first, the linked file second,
                and there may be multiple pairs.  The files are soft-linked.
 
-BEFOREMAN      List of extra targets that must be already built before the 
+BEFOREMAN      List of extra targets that must be already built before the
                man target can be run. Those targets must be real files (and
                not .PHONY targets).
 
@@ -252,7 +255,7 @@ The include file <bsd.prog.mk> handles building programs from one or
 more source files, along with their manual pages.  It has a limited number
 of suffixes, consistent with the current needs of the BSD tree.
 
-It has seven targets:
+It has six targets:
 
        all:
                build the program and its manual page
@@ -262,9 +265,6 @@ It has seven targets:
        cleandir:
                remove all of the files removed by the target clean, as
                well as .depend, tags, and any manual pages.
-       depend:
-               Misnomer as dependencies are built on-the-fly during make all.
-               No longer used in normal builds.
        includes:
                install any header files.
        install:
@@ -390,12 +390,26 @@ If foo has multiple source files, add the line:
 
        SRCS=   a.c b.c c.c d.c
 
+SRCS may contain lex and yacc files, in which case the framework will
+convert these files to C and header files first, before building anything
+else.
+
+SRCS may contain C++ files, in which case the C++ compiler will be used
+for linking.
+
+If YFLAGS contains -d, the header file will be named like the C file,
+and a proper rule tying both together will be generated. For instance, if
+SRCS contains grammar.y, then effectively you will have
+
+grammar.c grammar.h: grammar.y
+       ${YACC.Y} -o grammar.c grammar.y
+
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 
 The include file <bsd.subdir.mk> contains the default targets for building
-subdirectories.  It has the same seven targets as <bsd.prog.mk>: all, 
-clean, cleandir, depend, includes, install, and tags.  For all of
-the directories listed in the variable SUBDIR, the specified directory 
+subdirectories.  It has the same six targets as <bsd.prog.mk>: all,
+clean, cleandir, includes, install, and tags.  For all of
+the directories listed in the variable SUBDIR, the specified directory
 will be visited and the target made.  There is also a default target which
 allows the command "make subdir" where subdir is any directory listed in
 the variable SUBDIR.
@@ -411,7 +425,7 @@ yacc that allow multiple lex and yacc targets to be built in parallel.
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 
 The include file <bsd.lib.mk> has support for building libraries.  It has
-the same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend,
+the same seven targets as <bsd.prog.mk>: all, clean, cleandir,
 includes, install, and tags.  It has a limited number of suffixes,
 consistent with the current needs of the BSD tree.
 
@@ -437,7 +451,10 @@ MAN                The manual pages to be installed (use a .1 - .9 suffix).
 SRCS           List of source files to build the library.  Suffix types
                .s, .c, and .f are supported.  Note, .s files are preferred
                to .c files of the same name.  (This is not the default for
-               versions of make.)
+               POSIX make without bsd.lib.mk).
+
+               The same support for yacc and lex files as <bsd.prog.mk>
+               is provided.
 
 The include file <bsd.lib.mk> includes the file named "../Makefile.inc"
 if it exists, as well as the include file <bsd.man.mk>.