commit 2e73d29918a7bb24edd07c99ef0f179a0f6a59f6
parent d91bdac19115959d812e6eefae516c4c7a3f791f
Author: Kyle Milz <milz@0x30.net>
Date: Wed, 17 Mar 2021 00:40:23 +0000
man: add WIP
Diffstat:
| A | man/html.mk.5 | | | 213 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 213 insertions(+), 0 deletions(-)
diff --git a/man/html.mk.5 b/man/html.mk.5
@@ -0,0 +1,213 @@
+.\"
+.\" Copyright (c) 2021 Kyle Milz <milz@0x30.net>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" 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 $
+.Dt HTML.MK 5
+.Os
+.Sh NAME
+.Nm html.mk
+.Nd html.mk master Makefile fragment
+.Sh SYNOPSIS
+.Fd .include mk/html.mk
+.Sh DESCRIPTION
+.Nm
+contains a website 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.
+.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
+.Ev SRCS
+and builds their dependencies, then preprocesses the files
+into complete HTML documents.
+Copies any files listed in the
+.Ev CP_OBJ
+array.
+.It Cm clean
+Not implemented.
+.It Cm depend
+Creates
+.Pa .depend
+files for
+.Xr make 1
+to read.
+.It Cm obj
+See
+.Sx OUT OF TREE BUILDS .
+Create a directory structure identical to the one
+.Xr make 1
+is currently operating in under
+.Ev DESTDIR .
+Symbolic links named
+.Pa obj
+are created in each source directory that point to the corresponding
+location in the destination tree.
+.El
+.Sh VARIABLES
+All of these variables except
+.Ev DESTDIR
+are set in your Makefile.
+.Ev DESTDIR
+should be set in
+.Pa mk/site.mk .
+.Bl -tag -width Ds
+.It Ev CP_OBJ
+An array of files that exist in this directory that should be copied into
+.Pa obj/ .
+Only useful for
+.Sx OUT OF TREE BUILDS .
+.It Ev DESTDIR
+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.
+Only useful for
+.Sx OUT OF TREE BUILDS .
+.It Ev SRCS
+An array of input files that will be analyzed and transformed by
+.Nm .
+All files must have a
+.Pa .in
+suffix. Files output will have a
+.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.
+.It Ev TOP
+A relative path to the root of the website where the file
+.Pa mk/html.mk
+is located.
+.El
+.Sh OUT OF TREE BUILDS
+.Nm
+can create many intermediate and output files and it may be desirable
+to put them all in a different location. This is the idea behind an
+out of tree build, and is similar to how other large C programs are built.
+.Pp
+To enable this feature
+.Ic make obj
+is called from the root of the website. A directory tree identical to the
+one
+.Xr make 1
+knows about (through
+.Ev SUBDIR
+variables) will be created under
+.Ev DESTDIR .
+Any further intermediate or output files created will be placed there,
+instead of the current directory.
+.Sh INCLUDE SUFFIXES
+.Nm
+can generate HTML fragments for inclusion in source files using the
+.Xr cpp 1
+#include directive.
+These fragments will depend on existing files, but have special file names.
+Specifically these file names will have a different suffix.
+What that suffix is will change what
+.Nm
+does to transform the existing file into an HTML fragment.
+.Pp
+The following suffixes are supported:
+.Bl -tag -width Ds
+.It Cm Pa .img_html
+The following source file suffixes are supported:
+.Pp
+.Bl -bullet -compact
+.It
+.Pa .jpg
+.It
+.Pa .jpeg
+.It
+.Pa .png
+.El
+.Pp
+Copies a source file with one of the above suffixes into the object
+directory and uses
+.Pa convert
+to create a thumbnail.
+Emits HTML of the form:
+.Bd -literal
+ <a href="pic_cp.jpg"><img src="pic_thumb.jpg"
+.Ed
+.Pp
+Note you must manually close this tag, preferably with:
+.Bd -literal
+ alt="" /></a>
+.Ed
+.It Cm Pa .video_html
+The following source file suffixes are supported:
+.Pp
+.Bl -bullet -compact
+.It
+.Pa .mov
+.It
+.Pa .mp4
+.El
+.Pp
+Copies source video file into object directory.
+Emits HTML of the form:
+.Bd -literal
+<video controls>
+ <source src='movie.mov' type='video/mp4'>
+</video>
+.Ed
+.It Cm Pa .xliterate
+The following source file suffixes are supported:
+.Pp
+.Bl -bullet -compact
+.It
+.Pa .c
+.It
+.Pa .html
+.It
+.Pa .txt
+.El
+.Pp
+Transliterates entire source file, transforming various special characters
+into HTML named character references. Specifically:
+.Pp
+.Bl -bullet -compact
+.It
+.Sq <
+.It
+.Sq >
+.It
+.Sq \\
+.It
+.Sq #
+.El
+.El
+.Sh EXIT STATUS
+.Ex -std
+.Sh SEE ALSO
+.Xr cpp 1
+.Xr make 1
