# file      : doc/buildfile
# license   : MIT; see accompanying LICENSE file

define css: doc
css{*}: extension = css

define xhtml: doc
xhtml{*}: extension = xhtml

define ps: doc
ps{*}: extension = ps

define pdf: doc
pdf{*}: extension = pdf

define html2ps: file
html2ps{*}: extension = html2ps

./: css{default} xhtml{cli-guide}

# Man pages.
#

## Consumption build ($develop == false).
#

# Use pregenerated versions in the consumption build.
#
./: pregenerated/{man1 xhtml}{*}: include = (!$develop)

# Distribute pregenerated versions only in the consumption build.
#
pregenerated/{man1 xhtml}{*}: dist = (!$develop)

#
##

## Development build ($develop == true).
#

./: {man1 xhtml}{cli}: include = $develop

if $develop
{
  doc_version = [string] "$version.major.$version.minor.$version.patch"
  if $version.pre_release
    doc_version += "-$version.pre_release_string"

  # Let's take the last four-digit number to cover 2000-2021,2022.
  #
  doc_year = $regex.replace($copyright, '.+[-, ]([0-9][0-9][0-9][0-9]) .+', '\1')

  man_options = -v project="CLI" -v version="$doc_version" \
                -v copyright="$copyright" --suppress-undocumented

  # We use the cli version we've built to generate the documentation.
  #
  include ../cli/
}

# Note: avoid cleaning exe{cli} through this dependency.
#
{man1 xhtml}{cli}: ../cli/exe{cli}: clean = false

# In the development build distribute regenerated versions, remapping their
# locations to the paths of the pregenerated versions (which are only
# distributed in the consumption build; see above). This way we make sure that
# the distributed files are always up-to-date.
#
{man1 xhtml}{cli}: dist = ($develop ? pregenerated/ : false)

man1{cli}: ../cli/cli{options} file{cli-prologue.1 cli-epilogue.1}
%
if $develop
{{
  diag 'cli --man' ($<[1]) -> $>

  # Use the copyright year to approximate the last authoring date.
  #
  ($<[0]) --generate-man $man_options      \
          -v date="January $doc_year"      \
          --man-prologue-file $path($<[2]) \
          --man-epilogue-file $path($<[3]) \
          --stdout $path($<[1]) >$path($>)

  # If the result differs from the pregenerated version, copy it over. Unlike
  # the bootstrap compiler case, here we don't need to cause a build restart
  # (since nothing depends on it).
  #
  if! diff $src_base/pregenerated/cli.1 $path($>) >-
    cp $path($>) $src_base/pregenerated/cli.1
  end
}}

xhtml{cli}: ../cli/cli{options} file{cli-prologue.xhtml cli-epilogue.xhtml}
%
if $develop
{{
  diag 'cli --html' ($<[1]) -> $>

  ($<[0]) --generate-html $man_options      \
          --html-prologue-file $path($<[2]) \
          --html-epilogue-file $path($<[3]) \
          --stdout $path($<[1]) >$path($>)

  if! diff $src_base/pregenerated/cli.xhtml $path($>) >-
    cp $path($>) $src_base/pregenerated/cli.xhtml
  end
}}

#
##

# Manual.
#
# This case is slightly more involved because we make the generation of the
# manual's ps/pdf optional and also don't keep the result in the repository.
# Specifically:
#
# 1. In the consumption build we will install/redistribute ps/pdf if present.
#
# 2. In the development build we will generate ps/pdf if we are able to import
#    the needed tools, issuing a warning otherwise.

## Consumption build ($develop == false).
#

# Use pregenerated versions, if exist, in the consumption build.
#
./: pregenerated/{ps pdf}{*}: include = (!$develop)

# Distribute pregenerated versions only in the consumption build.
#
pregenerated/{ps pdf}{*}: dist = (!$develop)

#
##

## Development build ($develop == true).
#

html2pdf = false

if $develop
{
  # Import the html2ps and ps2pdf programs from the system, if available.
  #
  import? html2ps = html2ps%exe{html2ps}
  import? ps2pdf  = ps2pdf14%exe{ps2pdf14}

  html2pdf = ($html2ps != [null] && $ps2pdf != [null])

  if! $html2pdf
    warn "html2ps and/or ps2pdf14 are not available, not generating .ps and .pdf documentation"
}

./: {ps pdf}{cli-guide}: include = $html2pdf

# In the development build distribute regenerated versions, remapping their
# locations to the paths of the pregenerated versions (which are only
# distributed in the consumption build; see above). This way we make sure that
# the distributed files are always up-to-date.
#
{ps pdf}{cli-guide}: dist = ($html2pdf ? pregenerated/ : false)

# Note: the pregenerated files may not exist, thus --no-cleanup option is
# required for the cp builtin call. Strictly speaking we don't really need
# to copy them since they are not stored in the repository, but let's do
# that for consistency with the distributed source tree.
#
# @@ TMP Note that cli-guide.xhtml and guide.html2ps still have copyright
#        years hard-coded.
#
ps{cli-guide}: xhtml{cli-guide} html2ps{guide} $html2ps
%
if $html2pdf
{{
  options =

  diag html2ps ($<[0]) -> $>
  $html2ps $options -f $path($<[1]) -o $path($>) $path($<[0])

  cp --no-cleanup $path($>) $src_base/pregenerated/cli-guide.ps
}}

pdf{cli-guide}: ps{cli-guide} $ps2pdf
%
if $html2pdf
{{
  options = -dOptimize=true -dEmbedAllFonts=true

  diag ps2pdf ($<[0]) -> $>
  $ps2pdf $options $path($<[0]) $path($>)

  cp --no-cleanup $path($>) $src_base/pregenerated/cli-guide.pdf
}}

#
##