commit d4152242d3fccda213f8ef149ea3d48bebca781e
parent 25accd3b0e34d251f0730392422e21e11c814c0c
Author: Kyle Milz <krwmilz@gmail.com>
Date: Mon, 22 Nov 2021 16:14:55 +0000
mk: update to reflect reality
- mk/ dir no longer
- remove clean target
- .depend -> .d
- describe BSDOBJDIR better
- describe OUT OF TREE builds better
Diffstat:
M | html.mk.5 | | | 125 | +++++++++++++++++++++++++++++++++++++++---------------------------------------- |
1 file changed, 61 insertions(+), 64 deletions(-)
diff --git a/html.mk.5 b/html.mk.5
@@ -13,7 +13,7 @@
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: February 24 2021 $
+.Dd $Mdocdate: September 9 2021 $
.Dt HTML.MK 5
.Os
.Sh NAME
@@ -23,101 +23,98 @@
.Fd .include <bsd.html.mk>
.Sh DESCRIPTION
.Nm
-contains a website creation framework using
+contains an HTML content creation framework using
.Xr make 1
and
-.Xr cpp 1 ,
-in the form of documented public targets,
-variables and paths, and directives.
-.Pp
-Identifiers beginning with an underscore
-are internal-use only and likely to change without
-notice.
+.Xr cpp 1 .
.Pp
This documentation contains sections covering targets, variables,
ordered in alphabetical order, followed
by a secion covering out of tree builds, and a section covering
include suffixes.
-.Pp
-.Nm
-uses a few other Makefile fragments located in
-.Pa mk/ .
.Sh TARGETS
.Bl -tag -width Ds
.It Cm all
-The default target. Reads any input files listed in
+The default target. Reads any input files listed in the
.Ev SRCS
-and builds their dependencies, then preprocesses the files
+array, creates their dependencies, then preprocesses the files
into complete HTML documents.
-Copies any files listed in the
+If an out of tree build is occurring, then any files in the
.Ev CP_OBJ
-array.
-.It Cm clean
-Not implemented.
+array are copied to
+.Ev BSDOBJDIR .
.It Cm depend
Creates
-.Pa .depend
-file from any dependencies found in files listed in the
+.Pa .d
+files that contain dependency rules for any files in the
.Ev SRCS
-array.
+array. Must be invoked before the 'all' target.
.It Cm obj
+If the value of
+.Ev BSDOBJDIR
+is a directory that exists on the system, then create a new directory in
+.Ev BSDOBJDIR with the same name as the current directory and
+create a symbolic link
+.Pa obj
+in the current directory that points to the newly created directory.
+Otherwise create a new directory
+.Pa obj
+in the current directory.
See
.Sx OUT OF TREE BUILDS .
-Create a directory structure identical to the one
-.Xr make 1
-is currently operating in under
-.Ev BSDOBJDIR .
-Symbolic links named
-.Pa obj
-are created in each source directory that point to the corresponding
-location in the destination tree.
.El
.Sh VARIABLES
-The following variables are to be set in your
-.Pa Makefile .
+The following
+.Pa Makefile
+variables influence
+.Nm
+behavior.
.Bl -tag -width Ds
+.It Ev BSDSRCDIR
+This variable is only useful for
+.Sx OUT OF TREE BUILDS .
+Must contain an absolute path to the current directories parent.
+.It Ev BSDOBJDIR
+This variable is only useful for
+.Sx OUT OF TREE BUILDS .
+The destination output directory for any created objects. If the path
+specified does not exist, or is not a directory, the current directory
+is used instead.
.It Ev CP_OBJ
-Only useful for
+This variable is only useful for
.Sx OUT OF TREE BUILDS .
-An array of files that exist in this directory that should be copied into
-.Pa obj/ .
+Any files in this array will be copied from the current directory
+into
+.Pa obj .
+If a file does not exist then
+.Xr make 1
+will error.
+.It Ev CPPFLAGS
+This variable is passed to all
+.Xr cpp 1
+invocations.
.It Ev SRCS
-An array of input files that will be analyzed and transformed by
-.Nm .
+Any files in this array will be preprocessed by
+.Xr cpp 1
+into HTML documents. If a file specified does not exist then
+.Xr make 1
+will error.
All files must have a
.Pa .in
-suffix. Files output will have a
-.Pa .html
+suffix. After preprocessing the files will have an
+.Pa .html
suffix.
.It Ev SUBDIR
-An array of directories that
.Xr make 1
-will enter after it is finished building in the current directory.
-.El
-.Pp
-The following variable can either be set in a site wide
-.Pa site.mk
-file or a
-.Pa Makefile .
-.Bl -tag -width Ds
-.It Ev BSDSRCDIR
-Only useful for
-.Sx OUT OF TREE BUILDS .
-An absolute path to the parent of the site root.
-.It Ev BSDOBJDIR
-Only useful for
-.Sx OUT OF TREE BUILDS .
-The location where a directory tree structure similar to the source tree
-will be constructed, and linked to, by symbolic links from the source tree.
-All generated intermediate and final files will be placed here.
+will enter any directories found in this array after it has
+finished building the current directory. If a directory specified does not
+exist
+.Xr make 1
+will error.
.It Ev WOBJMASK
-Only useful for
+This variable is only useful for
.Sx OUT OF TREE BUILDS .
-The umask for any output files built.
-.It Ev CPPFLAGS
-Flags passed to all
-.Xr cpp 1
-invocations, can be used for common include directories.
+The umask for any created files.
.El
.Sh OUT OF TREE BUILDS
.Nm