.\" .\" Copyright (c) 2008-2024 Julien Nadeau Carriere .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .Dd March 1, 2024 .Dt BUILD.WWW.MK 5 .Os BSDBuild 3.2 .Sh NAME .Nm build.www.mk .Nd bsdbuild - HTML document preprocessing .Sh SYNOPSIS .Fd include .Sh DESCRIPTION The .Nm module generates a set of HTML documents (or code fragments), possibly in multiple language variants, from an HTML source file. The HTML source is processed by .Xr m4 1 macro processor in conjunction with the multi-language preprocessor .Xr mlproc 1 . The following source types are recognized: .Pp .Bl -bullet -compact .It HTML4/HTML5 + M4 sources (*.htm) .It M4 macro packages (*.m4) .It JavaScript sources (*.js) .It Cascading style sheets (*.css-in) .El .Pp From those sources, .Nm is able to generate: .Pp .Bl -bullet -compact .It Minified HTML documents/fragments (*.html.) .It Matching HTTP variant data (*.html.var) .It Minified, translated JavaScript (*..js) .It Minified cascading style sheets (*.css) .El .Sh TARGETS .Bl -tag -width "deinstall-www " .It Ar ${HTML} Source from which to generate HTML documents. The source may include M4 macro calls, multi-language "" tags, and "$_(gettext)" sequences (see .Xr mlproc 1 for details). .It Ar ${JS} JavaScript source files. The source is only fed through .Xr mlproc 1 , and may include "$_(gettext)" sequences. .It Ar ${CSS} Source from which to generate cascading style sheets (may include M4 macro calls). .It Ar clean-www Clean up the generated files. .It Ar cleandir-www Clean up for packaging. .It Ar install-www Install HTML documents to the target installation directory .Ev HTMLDIR , overwriting any existing document if .Ev HTML_OVERWRITE is .Sq Yes . If .Ev HTML_INSTSOURCE is .Sq Yes , all files needed for re-generating the documents are also installed into the target directory (including a Makefile). .It Ar deinstall-www Uninstall documents from the installation directory. .El .Sh VARIABLES .Bl -tag -width "MINIFIERFLAGSCSS " .It Ev HTML Documents to generate and install. If multilingual support is not required, use the .html extension. Otherwise, specify the .html.var extension (documents will be generated for each combination of language and character set -- the .html.var file may then be used directly by Apache's mod_negotiation or equivalent). .It Ev M4 Path to the .Xr m4 1 macro processor. .It Ev M4FLAGS Extra flags to pass to m4. .It Ev MINIFIER Path to HTML/CSS minifier (such as .Xr html-minifier 1 ) . .It Ev MINIFIERFLAGS Flags to minifier (for HTML). .It Ev MINIFIERFLAGSCSS Flags to minifier (for CSS). .It Ev MLPROC Path to the .Xr mlproc 1 preprocessor (part of BSDBuild). .It Ev MLPROCFLAGS Arguments to .Xr mlproc 1 . For gettext-style translation, the .Ar -L and .Ar -D arguments should be specified. .It Ev PERL Path to the .Xr perl 1 interpreter. .It Ev ICONV Path to the .Xr iconv 1 utility, needed to generate the character set variants. .It Ev BASEDIR Directory containing the macro files (Default = "m4"). .It Ev DTD Insert at beginning of generated documents (default: ""). .It Ev TEMPLATE Template to use for preprocessing the HTML source. It must reside in .Ev BASEDIR and use the .m4 extension. .It Ev CSS_TEMPLATE Similarly to .Ev TEMPLATE , but used to preprocess CSS source. .It Ev LANGUAGES Space-separated list of translations available for the documents specified in ${HTML}. See the section .Dq MULTI-LINGUAL SUPPORT for more details. .It Ev DEF_LANGUAGE The default language. .It Ev CLEANFILES Extra files to remove in the .Sq clean target. .It Ev HTMLDIR Installation directory. The special value .Sq none indicates that the .Sq install operation should be a no-op (Default = "none"). .It Ev HTML_OVERWRITE Don't overwrite existing documents in the .Sq install phase (Default = "No"). .It Ev HTML_INSTSOURCE Install the HTML source, templates, JS/stylesheets and all other files needed to be able to re-generate the documents in the installation directory, including a Makefile. (Default = "Yes"). .El .Sh MULTI-LINGUAL SUPPORT The .Ev LANGUAGES variable specifies a list of languages in which the documents specified in .Ev HTML are available. If documents are fed to .Xr mlproc 1 (the default), they may contain translations enclosed in tags, like so: .Bd -literal Hello Bonjour .Ed .Pp Sequences such as "$_(foo)" will also be translated using .Xr gettext 3 (see .Xr mlproc 1 for details). .Sh SEE ALSO .Xr build.common.mk 5 , .Xr build.lib.mk 5 , .Xr build.man.mk 5 , .Xr build.prog.mk 5 .Pp .Lk https://bsdbuild.hypertriton.com/ .Sh HISTORY .Nm first appeared in BSDBuild 1.0. .Pp BSDBuild is based on the 4.4BSD build system.