.\"
.\" Copyright (c) 2008 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 file types are recognized:
.Bl -bullet -compact
.It
HTML source (*.htm)
.It
M4 macro package (*.m4)
.El
.Pp
The following files types are generated by
.Nm :
.Bl -bullet -compact
.It
HTML document (*.html.<lang>.<charset>)
.It
Variant information (*.html.var)
.El
.Pp
.Sh TARGETS
.Bl -tag -width "deinstall-www "
.It Ar ${HTML}
Generate the preprocessed HTML document variants from the source.
.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
Filenames of the HTML documents (*.html extensions).
.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 TEMPLATE
Template to use for preprocessing the HTML source.
It must reside in
.Ev BASEDIR
and use the .m4 extension.
.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
.Pp
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.