static html creation framework using make(1) and cpp(1)
Log | Files | Refs | README | LICENSE

commit 2e73d29918a7bb24edd07c99ef0f179a0f6a59f6
parent d91bdac19115959d812e6eefae516c4c7a3f791f
Author: Kyle Milz <>
Date:   Wed, 17 Mar 2021 00:40:23 +0000

man: add WIP

Aman/ | 213+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 213 insertions(+), 0 deletions(-)

diff --git a/man/ b/man/ @@ -0,0 +1,213 @@ +.\" +.\" Copyright (c) 2021 Kyle Milz <> +.\" +.\" 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 +.Nd master Makefile fragment +.Sh SYNOPSIS +.Fd .include 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/ . +.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/ +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='' 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