.\"
.\" Copyright (c) 2008-2015 Hypertriton, Inc. <http://www.hypertriton.com/>
.\" 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 July 18, 2007
.Dt BUILD.WWW.MK 5
.Os
.ds vT BSDBuild Reference
.ds oS BSDBuild 2.0
.Sh NAME
.Nm build.www.mk
.Nd bsdbuild - HTML document preprocessing
.Sh SYNOPSIS
.Fd .include <bsd.www.mk>
.Sh DESCRIPTION
The
.Nm
module is used to generate a set of HTML documents in different languages
and character set variants from an HTML source file and one or more templates
using the
.Xr m4 1
macro processor in conjunction with the
.Xr xsltproc 1
XSLT processor.
The following source types are recognized:
.Bl -bullet -compact
.It
HTML+M4 documents (*.htm)
.It
Cascading style sheets (*.css-in)
.It
M4 macro packages (*.m4)
.El
.Pp
From those sources,
.Nm
is able to generate:
.Bl -bullet -compact
.It
Cascading style sheets (*.css)
.It
HTML documents in multiple languages/character sets
.It
HTTP variant data (*.html.var)
.El
.Sh TARGETS
.Bl -tag -width "deinstall-www "
.It Ar ${HTML}
Source from which to generate HTML documents (may include M4 macro calls and
use optional XSL transforms).
.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 "CONF_OVERWRITE "
.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 XSLTPROC
Path to the
.Xr xsltproc 1
XSLT processor.
.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 XSLDIR
Directory containing XSLT source files
(Default = "xsl").
Note that
.Pa ml.xsl
is required for multi-lingual support.
.It Ev DTD
DTD to specify at the beginning of the generated document
(default to HTML 4.01 Transitional).
.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 XSL
Space-separated list of XSLT stylesheets to apply to the documents
(Default = "ml.xsl").
.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, XSLT 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.
Since the
.Pa ml.xsl
XSLT stylesheet is applied by default, HTML documents (usually encoded in
UTF-8) can contain multiple translations in a single file.
Language-specific parts are separated using the
.Sq <ml>
tag, like so:
.Bd -literal
	<ml lang="en">Hello</ml>
	<ml lang="fr">Bonjour</ml>
.Ed
.Sh SEE ALSO
.Xr build.common.mk 5
.Sh HISTORY
.Nm
first appeared in BSDBuild 1.0.
.Pp
BSDBuild is based on the 4.4BSD build system.