#   Zerocat Project Template --- Create something excitingly free!
#
#   Copyright (C) 2021, 2022, 2023  Kai Mertens <kmx@posteo.net>
#
#   This file is part of Zerocat Project Template.
#
#   Zerocat Project Template is free software: you can redistribute it
#   and/or modify it under the terms of the GNU General Public License as
#   published by the Free Software Foundation, either version 3 of the
#   License, or (at your option) any later version.
#
#   Zerocat Project Template is distributed in the hope that it will be
#   useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
#   General Public License for more details.
#
#   You should have received a copy of the GNU General Public License
#   along with Zerocat Project Template.
#   If not, see <http://www.gnu.org/licenses/>.


#   Usage
#   =====
#
#   To get an overview of targets, type:
#
#           make -C ../doc help


#   Workaround for GNU Make < 4.3
#   =============================
#
#   Finalize commands within a $(shell) function with semicolon, e.g.:
#
#           $(shell echo;)


# Shell
SHELL                         := /bin/sh


# White Space
EMPTY                         :=
SPACE                         := $(EMPTY) $(EMPTY)
COMMA                         := ,
M5                            := zzzzz
TAB1                          := \r\t\t
TAB2                          := \r\t\t\t
TOKEN_SPACE                   := ~~~SPACE~~~
TOKEN_URLSTART                := ~~~URLSTART~~~


# Suffixes
.SUFFIXES :
.SUFFIXES : .html .css


# Root Paths
ROOT                          := ../
ROOT_GIT                      := ../.git/
#   GNU Guix System ...
ROOT_GUIX                     := ../guix/
#   Code Sources ...
ROOT_SRC                      := ../src/
#   Documentation ...
ROOT_IMAGES                   := ../images/
ROOT_DOC                      := ../doc/
#   Artwork
ROOT_ARTWORK                  := ../artwork/
ROOT_ARTWORK_LOGO             := ../artwork/logo/
#   Hardware ...
ROOT_HW                       := ../hardware/


# Standard Utilities
WHEREIS                       := $(shell command -v whereis;)
WHEREIS_FLAGS                 := -b
$(if $(strip $(WHEREIS)),,    $(error Cannot find whereis utility))

CD                            := $(shell command -v cd;)
CD_FLAGS                      :=
$(if $(strip $(CD)),,         $(error Cannot find cd utility))

LN                            := $(shell command -v ln;)
LN_FLAGS                      := -s -f
$(if $(strip $(LN)),,         $(error Cannot find ln utility))

RM                            := $(shell command -v rm;)
RM_FLAGS                      := -f
$(if $(strip $(RM)),,         $(error Cannot find rm utility))

CAT                           := $(shell command -v cat;)
CAT_FLAGS                     :=
$(if $(strip $(CAT)),,        $(error Cannot find cat utility))

CUT                           := $(shell command -v cut;)
CUT_FLAGS                     := -d' '
$(if $(strip $(CUT)),,        $(error Cannot find cut utility))

GIT                           := $(shell command -v git;)
GIT_FLAGS                     :=
$(if $(strip $(GIT)),,        $(error Cannot find git utility))

SED                           := $(shell command -v sed;)
SED_FLAGS                     := -r
$(if $(strip $(SED)),,        $(error Cannot find sed utility))

SET                           := $(shell command -v set;)
SET_FLAGS                     := -f
$(if $(strip $(SET)),,        $(error Cannot find set utility))

TAR                           := $(shell command -v tar;)
TAR_FLAGS                     :=
$(if $(strip $(TAR)),,        $(error Cannot find tar utility))

DATE                          := $(shell command -v date;)
DATE_FLAGS                    := -R
$(if $(strip $(DATE)),,       $(error Cannot find date utility))

DIFF                          := $(shell command -v diff;)
DIFF_FLAGS                    :=
$(if $(strip $(DIFF)),,       $(error Cannot find diff utility))

ECHO                          := $(shell $(WHEREIS) $(WHEREIS_FLAGS) echo | $(CUT) $(CUT_FLAGS) -f2;)
ECHO_FLAGS                    := -e
$(if $(strip $(ECHO)),,       $(error Cannot find echo utility))

GREP                          := $(shell command -v grep;)
GREP_FLAGS                    :=
$(if $(strip $(GREP)),,       $(error Cannot find grep utility))

SORT                          := $(shell command -v sort;)
SORT_FLAGS                    := -u
$(if $(strip $(SORT)),,       $(error Cannot find sort utility))

UNIQ                          := $(shell command -v uniq;)
UNIQ_FLAGS                    :=
$(if $(strip $(UNIQ)),,       $(error Cannot find uniq utility))

WGET                          := $(shell command -v wget;)
WGET_FLAGS                    :=
$(if $(strip $(WGET)),,       $(error Cannot find wget utility))

PRINTF                        := $(shell command -v printf;)
PRINTF_FLAGS                  :=
$(if $(strip $(PRINTF)),,     $(error Cannot find printf utility))

MKTEMP                        := $(shell command -v mktemp;)
MKTEMP_FLAGS                  :=
$(if $(strip $(MKTEMP)),,     $(error Cannot find mktemp utility))

MARKDOWN                      := $(shell command -v markdown;)
MARKDOWN_FLAGS                :=
$(if $(strip $(MARKDOWN)),,   $(error Cannot find markdown utility))


# Files
THEMECONFIG                   := $(ROOT_DOC)theme.conf
FAVICON                       := $(ROOT_ARTWORK_LOGO)logo_icon-black.png
FAVICON_BLACK                 := $(subst white,black,$(FAVICON))
FAVICON_WHITE                 := $(subst black,white,$(FAVICON))
PTR_FAVICON                   := $(ROOT_DOC)favicon
LOGO                          := $(ROOT_ARTWORK_LOGO)logo_combi-black.png
LOGO_BLACK                    := $(subst white,black,$(LOGO))
LOGO_WHITE                    := $(subst black,white,$(LOGO))
PTR_LOGO                      := $(ROOT_DOC)logo
STYLESHEET                    := $(ROOT_DOC)project.css
STYLESHEET_BLACK              := $(addsuffix .black,$(STYLESHEET))
STYLESHEET_WHITE              := $(addsuffix .white,$(STYLESHEET))
PTR_STYLESHEET                := $(ROOT_DOC)stylesheet.css
TEMPLATE_TITLEPAGE            := $(ROOT_DOC)TITLEPAGE.md.tmpl
TITLEPAGE                     := $(ROOT_DOC)TITLEPAGE.md
OUT_HTML                      := $(ROOT_DOC)index.html


# Settings
URL_LOGOTYPE                  := http://www.zerocat.org/
BUTTON_MAIN                   := Main/Subordinate
BUTTON_TOP                    := Top/Sections
BUTTON_TAIL                   := Back to Top
MAIN                          := $(OUT_HTML)
IMAGES                        := $(strip\
	$(sort\
		$(filter\
			%.png %.jpg %.jpeg,\
			$(wildcard $(ROOT_DOC)*)\
			$(wildcard $(ROOT_IMAGES)*)\
		)\
	)\
)
FILES_GNU                     := $(strip\
	$(sort\
		$(filter\
			$(wildcard $(ROOT_DOC)GNU-*.md)\
			,$(wildcard $(ROOT_DOC)*)\
		)\
	)\
)
FILES_DOC                     := $(strip\
	$(sort\
		$(filter-out\
			$(ROOT_DOC)TITLEPAGE.md\
			$(FILES_GNU)\
			,\
			$(filter\
				%Makefile\
				%favicon %logo\
				%.md.tmpl\
				%.txt %.css\
				%.md %.mdwn %.markdown,\
				$(wildcard $(ROOT_DOC)*)\
			)\
		)\
	)\
)
LIST_GUIX_ENVIRONMENT         := $(strip\
	$(sort\
		$(filter\
			%Makefile\
			%.scm,\
			$(wildcard $(ROOT_GUIX)*)\
		)\
	)\
)
LIST_CODE                     := $(strip\
	$(sort\
		$(filter\
			%Makefile,\
			$(wildcard $(ROOT_SRC)*)\
		)\
	)\
)
LIST_TEMPLATE                 := $(strip\
	$(sort\
		$(filter\
			%Makefile\
			%.txt %.md %.mdwn %.markdown\
			%.png %.jpg %.jpeg\
			%.sh %.scm,\
			$(wildcard ../template/artwork/logo/*)\
			$(wildcard ../template/hardware/*)\
			$(wildcard ../template/guix/*)\
			$(wildcard ../template/doc/*)\
		)\
	)\
)
LIST_ARTWORK                  := $(strip\
	$(sort\
		$(filter\
			%Makefile\
			%.txt %.md %.mdwn %.markdown\
			%.svg %.png %.jpg %.jpeg %.pdf,\
			$(wildcard $(ROOT_ARTWORK)*)\
		)\
	)\
)
LIST_HW                       := $(strip\
	$(sort\
		$(filter\
			%Makefile\
			%.txt %.md %.mdwn %.markdown\
			%.c %.h %.cfg %.scm,\
			$(wildcard $(ROOT_HW)*)\
		)\
	)\
)
# LIST_DOCUMENTATIONS, e.g.:
#
#     Documentation$(TOKEN_URLSTART)$(OUT_HTML)\
#
LIST_DOCUMENTATIONS           := $(strip\
)
LIST_ORDERED                  := $(strip\
	$(filter $(ROOT_DOC)NEWS.md,$(FILES_DOC))\
	$(filter $(ROOT_DOC)README.md,$(FILES_DOC))\
	$(filter $(ROOT_DOC)CONTRIBUTING.md,$(FILES_DOC))\
	$(filter $(ROOT_DOC)FUNDING.md,$(FILES_DOC))\
	$(filter $(ROOT_DOC)COPYING.md,$(FILES_DOC))\
	$(filter $(ROOT_DOC)CHANGES.md,$(FILES_DOC))\
	$(filter $(ROOT_DOC)CREDITS.md,$(FILES_DOC))\
	$(filter $(ROOT_DOC)ISSUES.md,$(FILES_DOC))\
)
LIST_SECTIONS                 := $(strip\
	$(LIST_ORDERED)\
	$(sort\
		$(filter-out\
			$(LIST_ORDERED)\
			,$(filter\
				%.md,\
				$(FILES_DOC)\
			)\
		)\
	)\
	$(sort\
		$(FILES_GNU)\
	)\
)
SOURCES                       := $(strip\
	$(IMAGES)\
	$(FILES_GNU)\
	$(FILES_DOC)\
	$(LIST_GUIX_ENVIRONMENT)\
	$(LIST_CODE)\
	$(LIST_TEMPLATE)\
	$(LIST_ARTWORK)\
	$(LIST_HW)\
)
PROJECT_TITLE                 := Zerocat Project Template
PROJECT_BRIEF                 := Create something excitingly free!
# Use escaped, special characters for image path:
PROJECT_IMAGE                 :=
# Use escaped, special characters for image title:
PROJECT_IMAGE_TITLE           :=
PROJECT_REPO                  := git://zerocat.org/zerocat/projects/zerocat-project-template
PROJECT_NUMBER                := $(strip\
	$(shell\
		$(SET) $(SET_FLAGS)\
		&& $(GIT) $(GIT_FLAGS)\
			describe\
				--long\
				--always\
				--match v*\
		| $(SED) $(SED_FLAGS)\
			-e 's/(.*)(-g)([0-9a-f]*)/\1-\3/;'\
				-;\
	)\
)
PROJECT_BRANCH                := $(strip\
	$(shell\
		$(GIT) $(GIT_FLAGS)\
			branch\
		| $(SED) $(SED_FLAGS)\
			-e '/^\*/!d; s/^\* //;'\
				-;\
	)\
)
PROJECT_ARCHIVE               := $(ROOT_DOC)$(subst .git,,$(notdir $(PROJECT_REPO)))-$(PROJECT_NUMBER).tar
MAKEFILE_TITLE                := Generate the Documentation


# Tinned Cans
define SCOPE_OF_COPYRIGHT     =
$(strip\
	{\
		format='%an <%ae> %as'\
		&& $(GIT) log\
			--format="$$format"\
				-- $(ROOT);\
	}\
)
endef
define HEADER                 =
$(strip\
	$(ECHO) $(ECHO_FLAGS)\
		"\n$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)"\
		"\n$(M5) $(PROJECT_TITLE)"\
		"\n$(M5) – $(PROJECT_BRIEF)"\
		"\n$(M5) $(MAKEFILE_TITLE)"\
		"\n$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)"\
)
endef
define HEADLINE               =
$(strip\
	$(ECHO) $(ECHO_FLAGS)\
		"$(M5) Process target “$@” $(M5)$(M5)"\
)
endef
define DONE                   =
$(strip\
	$(ECHO) $(ECHO_FLAGS)\
		"... successfully processed: “$@”"\
		"\n"\
)
endef


# Tinned Cans: URL_DROPDOWN
#   dropdown_label:   Button Label
#   dropdown_urls:    List of URLs for Dropdown Box
define URL_DROPDOWN           =
$(strip\
	if [ -n "$$dropdown_urls" ];\
		then\
			$(ECHO) $(ECHO_FLAGS)\
				"\n        <div>"\
					>> $@\
			&& if [ "$${dropdown_label}" = "$(BUTTON_MAIN)" ];\
				then\
					$(ECHO) $(ECHO_FLAGS)\
						"\n          <a href=\"$(MAIN)\">"\
						"\n            <button type=\"button\">$$dropdown_label</button>"\
						"\n          </a>"\
							>> $@;\
				else\
					$(ECHO) $(ECHO_FLAGS)\
						"\n          <button type=\"button\">$$dropdown_label</button>"\
							>> $@;\
				fi\
			&& $(ECHO) $(ECHO_FLAGS)\
				"\n          <div>"\
					>> $@\
			&& if [ -n "$$dropdown_urls" ];\
				then\
					for n in $$dropdown_urls;\
						do\
							label="\
								$$(\
									$(ECHO) $(ECHO_FLAGS) $$n\
									| $(SED) $(SED_FLAGS)\
										-e 's/$(TOKEN_URLSTART).*$$//; s/$(TOKEN_SPACE)/ /g;'\
											-;\
								)\
							"\
							&& url="\
								$$(\
									$(ECHO) $(ECHO_FLAGS) $$n\
									| $(SED) $(SED_FLAGS)\
										-e 's/^.*$(TOKEN_URLSTART)//;'\
											-;\
								)\
							"\
							&& $(ECHO) $(ECHO_FLAGS) -n\
								"\n            <a href=\"$${url}\">$${label}</a>"\
									>> $@;\
						done\
				fi\
			&& $(ECHO) $(ECHO_FLAGS)\
				"\n          </div>"\
				"\n        </div>"\
					>> $@;\
		fi\
)
endef


# Tinned Cans: TAG_DROPDOWN
#   dropdown_label:   Button Label
#   dropdown_tags:    List of Tags for Dropdown Box
define TAG_DROPDOWN           =
$(strip\
	if [ -n "$$dropdown_tags" ];\
		then\
			$(ECHO) $(ECHO_FLAGS)\
				"\n        <div>"\
					>> $@\
			&& if [ "$$dropdown_label" = "$(BUTTON_TOP)" ];\
				then\
					$(ECHO) $(ECHO_FLAGS)\
						"\n          <a href=\"#top\">"\
						"\n            <button type=\"button\">$$dropdown_label</button>"\
						"\n          </a>"\
							>> $@;\
				else\
					$(ECHO) $(ECHO_FLAGS)\
						"\n          <button type=\"button\">$$dropdown_label</button>"\
							>> $@;\
				fi\
			&& $(ECHO) $(ECHO_FLAGS)\
				"\n          <div>"\
					>> $@\
			&& for n in $$dropdown_tags;\
				do\
					$(ECHO) $(ECHO_FLAGS) -n\
						"\n            <a href=\"#$${n#\.\/}\">#$${n#\.\/}</a>"\
							>> $@;\
				done\
			&& $(ECHO) $(ECHO_FLAGS)\
				"\n          </div>"\
				"\n        </div>"\
					>> $@;\
		fi\
)
endef


# Tinned Cans: FILE_DROPDOWN
#   dropdown_label:   Button Label
#   dropdown_files:   List of Files for Dropdown Box
define FILE_DROPDOWN          =
$(strip\
	if [ -n "$$dropdown_files" ];\
		then\
			$(ECHO) $(ECHO_FLAGS)\
				"\n        <div>"\
				"\n          <button type=\"button\">$$dropdown_label</button>"\
				"\n          <div>"\
					>> $@\
			&& for n in $$dropdown_files;\
				do\
					$(ECHO) $(ECHO_FLAGS) -n\
						"\n            <a href=\"$${n}\">$${n}</a>"\
							>> $@;\
				done\
			&& $(ECHO) $(ECHO_FLAGS)\
				"\n          </div>"\
				"\n        </div>"\
					>> $@;\
		fi\
)
endef


# Tinned Cans: NAVBAR
define NAVBAR                 =
$(strip\
	$(ECHO) $(ECHO_FLAGS)\
		"    <div class=\"navbar-container\">"\
		"\n      <a id=\"$${id}\"></a>"\
		"\n      <div class=\"navbar\">"\
			>> $@\
	&& dropdown_label="$(BUTTON_MAIN)"\
	&& dropdown_urls="$(LIST_DOCUMENTATIONS)"\
	&& $(URL_DROPDOWN)\
	&& dropdown_label="$(BUTTON_TOP)"\
	&& dropdown_tags="$(LIST_SECTIONS) ./tail"\
	&& $(TAG_DROPDOWN)\
	&& dropdown_label="GNU Guix Environment"\
	&& dropdown_files="$(LIST_GUIX_ENVIRONMENT)"\
	&& $(FILE_DROPDOWN)\
	&& dropdown_label="Code Sources"\
	&& dropdown_files="$(LIST_CODE)"\
	&& $(FILE_DROPDOWN)\
	&& dropdown_label="Template"\
	&& dropdown_files="$(LIST_TEMPLATE)"\
	&& $(FILE_DROPDOWN)\
	&& dropdown_label="Artwork"\
	&& dropdown_files="$(LIST_ARTWORK)"\
	&& $(FILE_DROPDOWN)\
	&& dropdown_label="Hardware Design Files"\
	&& dropdown_files="$(LIST_HW)"\
	&& $(FILE_DROPDOWN)\
	&& $(ECHO) $(ECHO_FLAGS)\
		"\n      </div>"\
		"\n    </div>"\
			>> $@\
)
endef


# Tinned Cans: Tail Button
define TAIL_BUTTON            =
$(strip\
	$(ECHO) $(ECHO_FLAGS)\
		"    <div class=\"navbar-container\">"\
		"\n      <a id=\"$${id}\"></a>"\
		"\n      <div class=\"navbar\">"\
			>> $@\
	&& $(ECHO) $(ECHO_FLAGS)\
		"\n        <div>"\
		"\n          <a href=\"#top\">"\
		"\n            <button type=\"button\">$(BUTTON_TAIL)</button>"\
		"\n          </a>"\
		"\n        <div>"\
			>> $@\
	&& $(ECHO) $(ECHO_FLAGS)\
		"\n          </div>"\
		"\n        </div>"\
			>> $@\
)
endef


# Built-in Special Targets
#~ .SECONDARY :                  # Uncomment for debugging
.PHONY :\
	all\
	\
	hello\
	help\
	\
	config-icon-black\
	config-icon-white\
	config-black\
	config-white\
	\
	titlepage\
	$(PTR_LOGO)\
	$(PTR_FAVICON)\
	point-to-html\
	archive-members\
	archive\
	\
	clean-titlepage\
	clean-archive\
	clean


# Targets
#   Reset skin, generate all documents
all : hello
	@$(HEADLINE)\
	&& $(MAKE)\
		config-icon-black\
	&& $(MAKE)\
		config-white\
	&& $(MAKE)\
		point-to-html\
	&& $(DONE);

#   display greeting
#     provided with all, clean and help
hello :
	@$(HEADER)\
	&& $(DONE);

#   display help information
help : hello
	@$(HEADLINE)\
	&& $(ECHO) $(ECHO_FLAGS)\
		"\nList of Targets"\
		"\n==============="\
		"\n"\
		"\nDefault"\
		"\n-------"\
		"\n"\
		"\nall$(TAB2)build the html documentation with default favicon and theme"\
		"\n"\
		"\nHelp"\
		"\n----"\
		"\n"\
		"\nhello$(TAB2)greeter, provided with targets all, clean and help"\
		"\nhelp$(TAB2)list available targets"\
		"\n"\
		"\nConfigure"\
		"\n---------"\
		"\n"\
		"\nconfig-icon-black$(TAB2)switch to black favicon"\
		"\nconfig-icon-white$(TAB2)switch to white favicon"\
		"\nconfig-black$(TAB2)switch to black html theme"\
		"\nconfig-white$(TAB2)switch to white html theme"\
		"\n"\
		"\nActions"\
		"\n-------"\
		"\n"\
		"\narchive$(TAB2)generate $(PROJECT_ARCHIVE)"\
		"\narchive-members$(TAB2)list members of $(PROJECT_ARCHIVE)"\
		"\ntitlepage$(TAB2)generate $(TITLEPAGE)"\
		"\npoint-to-html$(TAB2)point to $(OUT_HTML)"\
		"\n"\
		"\nClean"\
		"\n-----"\
		"\n"\
		"\nclean-titlepage$(TAB2)remove $(TITLEPAGE)"\
		"\nclean-archive$(TAB2)remove $(PROJECT_ARCHIVE)"\
		"\nclean$(TAB2)remove all generated files"\
		"\n"\
	&& $(DONE);

#   generate config file, if not already available
$(THEMECONFIG) :
	@$(HEADLINE)\
	&& $(ECHO) $(ECHO_FLAGS)\
		"config-icon-black"\
		"\nconfig-white"\
			> $@\
	&& $(DONE);

#   set black icon configuration tag
config-icon-black : $(THEMECONFIG)
	@$(HEADLINE)\
	&& $(SED) $(SED_FLAGS)\
		--in-place\
		-e 's/config-icon-white/config-icon-black/;'\
			$<\
	&& $(DONE);

#   set white icon configuration tag
config-icon-white : $(THEMECONFIG)
	@$(HEADLINE)\
	&& $(SED) $(SED_FLAGS)\
		--in-place\
		-e 's/config-icon-black/config-icon-white/;'\
			$<\
	&& $(DONE);

#   set black configuration tag
config-black : $(THEMECONFIG)
	@$(HEADLINE)\
	&& $(SED) $(SED_FLAGS)\
		--in-place\
		-e 's/config-white/config-black/;'\
			$<\
	&& $(DONE);

#   set white configuration tag
config-white : $(THEMECONFIG)
	@$(HEADLINE)\
	&& $(SED) $(SED_FLAGS)\
		--in-place\
		-e 's/config-black/config-white/;'\
			$<\
	&& $(DONE);

#   create black stylesheet
$(STYLESHEET_BLACK) : $(STYLESHEET)
	@$(HEADLINE)\
	&& $(SED) $(SED_FLAGS)\
		-e '/black color set\: start/,/black color set\: stop/{;/.*--.*\:.*\;.*/s/[/*]*//g;};'\
		-e '/white color set\: start/,/white color set\: stop/{;/.*--.*\:.*\;.*/s/[/*]*//g;};'\
		-e '/white color set\: start/,/white color set\: stop/s/.*--.*/\/\*&\*\//;'\
			$<\
				> $@\
	&& $(DONE);

#   create white stylesheet
$(STYLESHEET_WHITE) : $(STYLESHEET)
	@$(HEADLINE)\
	&& $(SED) $(SED_FLAGS)\
		-e '/black color set\: start/,/black color set\: stop/{;/.*--.*\:.*\;.*/s/[/*]*//g;};'\
		-e '/white color set\: start/,/white color set\: stop/{;/.*--.*\:.*\;.*/s/[/*]*//g;};'\
		-e '/black color set\: start/,/black color set\: stop/s/.*--.*/\/\*&\*\//;'\
			$<\
				> $@\
	&& $(DONE);

#   update icon pointer
$(PTR_FAVICON) : $(THEMECONFIG) $(FAVICON_BLACK) $(FAVICON_WHITE)
	@$(HEADLINE)\
	&& if [ "`$(SED) $(SED_FLAGS) -e '/config-icon-white/!d;' $<`" != "" ];\
		then\
			$(LN) $(LN_FLAGS)\
				$(FAVICON_WHITE) $@;\
		else\
			$(LN) $(LN_FLAGS)\
				$(FAVICON_BLACK) $@;\
		fi\
	&& $(DONE);

#   update logo pointer
$(PTR_LOGO) : $(THEMECONFIG) $(LOGO_BLACK) $(LOGO_WHITE)
	@$(HEADLINE)\
	&& if [ "`$(SED) $(SED_FLAGS) -e '/config-white/!d;' $<`" != "" ];\
		then\
			$(LN) $(LN_FLAGS)\
				$(LOGO_BLACK) $@;\
		else\
			$(LN) $(LN_FLAGS)\
				$(LOGO_WHITE) $@;\
		fi\
	&& $(DONE);

#   update stylesheet pointer
$(PTR_STYLESHEET) : $(THEMECONFIG) $(STYLESHEET_BLACK) $(STYLESHEET_WHITE)
	@$(HEADLINE)\
	&& if [ "`$(SED) $(SED_FLAGS) -e '/config-white/!d;' $<`" != "" ];\
		then\
			$(LN) $(LN_FLAGS)\
				$(STYLESHEET_WHITE) $@;\
		else\
			$(LN) $(LN_FLAGS)\
				$(STYLESHEET_BLACK) $@;\
		fi\
	&& $(DONE);

#   point to html documentation entry
point-to-html :
	@$(HEADLINE)\
	&& $(MAKE)\
		$(TITLEPAGE)\
	&& $(MAKE)\
		$(OUT_HTML)\
	&& $(ECHO) $(ECHO_FLAGS)\
		"\n$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)"\
		"\n"\
		"\nPlease direct your favorite browser to:"\
		"\n"\
		"\n  file://$${PWD}/$(OUT_HTML)"\
		"\n"\
		"\n$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)"\
	&& $(DONE);

#   html documentation
$(OUT_HTML) : $(PTR_FAVICON) $(PTR_LOGO) $(PTR_STYLESHEET) $(SOURCES) $(TITLEPAGE) $(addsuffix .section.figcap,$(LIST_SECTIONS))
	@$(HEADLINE)\
	&& $(ECHO) $(ECHO_FLAGS)\
		"<!DOCTYPE html>"\
		"\n<html>"\
		"\n  <head>"\
		"\n    <meta http-equiv=\"content-type\" content=\"text/html; charset=UTF-8\">"\
		"\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0, maximum-scale=3.0, user-scalable=1\">"\
		"\n    <meta name=\"referrer\" content=\"origin\">"\
		"\n    <link rel=\"icon\" type=\"image/png\" href=\"$(PTR_FAVICON)\">"\
		"\n    <title>$(PROJECT_TITLE)</title>"\
		"\n    <style type=\"text/css\">"\
		"\n      @import url($(PTR_STYLESHEET)) all;"\
		"\n    </style>"\
		"\n  </head>"\
		"\n  <body>"\
		"\n    <a name=\"top\"><div><br></div></a>"\
		"\n    <a href=\"$(URL_LOGOTYPE)\">"\
		"\n      <img id=\"project-logo\" src=\"$(PTR_LOGO)\" alt=\"$(PTR_LOGO)\">"\
		"\n    </a>"\
		"\n    <p id="doc-reference">"\
		"\n      Documentation for “$(PROJECT_TITLE)”<br>"\
		"\n      Generated on: $(shell $(DATE) $(DATE_FLAGS);)<br>"\
		"\n      Repository: $(PROJECT_REPO)<br>"\
		"\n      Version: $(PROJECT_NUMBER)<br>"\
		"\n      Branch: $(PROJECT_BRANCH)<br>"\
		"\n    </p>"\
			> $@\
	&& id="topnav"\
	&& $(NAVBAR)\
	&& $(ECHO) $(ECHO_FLAGS)\
		"\n    <div class=\"section\">"\
			>> $@\
	&& $(MARKDOWN) $(MARKDOWN_FLAGS)\
		$(TITLEPAGE)\
	| $(SED) $(SED_FLAGS)\
		-e '1,4{;'\
		-e 's/(<h.)(>)(.*)([ ]+)(–[ ]*)(.*)(<\/h.>)/      \1 id=\"project-title\"\2\3\7\n      <div id=\"project-brief\"\2\6<\/div>/;'\
		-e 's/<p><img/      <div class=\"figure\">\n        &/; s/<\/p>/&\n        <p>$(PROJECT_IMAGE_TITLE)<\/p>\n      <\/div>/;'\
		-e 's/<img/& id=\"project-image\"/;'\
		-e 's/~~Project-Image~~/$(PROJECT_IMAGE)/g;'\
		-e 's/~~Project-Image-Title~~/$(PROJECT_IMAGE_TITLE)/g;'\
		-e '};'\
			>> $@\
	&& $(ECHO) $(ECHO_FLAGS)\
		"\n    </div>"\
			>> $@\
	&& for i in $(LIST_SECTIONS);\
		do\
			id="$${i}"\
			&& $(NAVBAR)\
			&& $(ECHO) $(ECHO_FLAGS)\
				"\n    <div class=\"section\">"\
				"\n      <div class=\"section-file\">Section #$${i}</div>"\
					>> $@\
			&& $(CAT) $(CAT_FLAGS)\
				$${i}.section\
					>> $@\
			&& $(ECHO) $(ECHO_FLAGS)\
				"\n    </div>"\
					>> $@;\
		done\
	&& id="tail"\
	&& $(TAIL_BUTTON)\
	&& $(ECHO) $(ECHO_FLAGS)\
		"    <br>"\
			>> $@\
	&& $(ECHO) $(ECHO_FLAGS)\
		"\n  </body>"\
		"\n</html>"\
			>> $@\
	&& $(DONE);

#   Strip copyright and license notice from files that are listed as sections.
#   Take care: Do not strip copyright notices from GNU-GPL or GNU-FDL!
%.md.stripped : %.md
	@$(HEADLINE)\
	&& $(SED) $(SED_FLAGS)\
		-e '/^Copyright.*> ? ?$$/d;'\
		-e '/^Permission/,/License\".$$/d;'\
			$<\
				>> $@\
	&& $(DONE);

#   html section
%.md.section : %.md.stripped
	@$(HEADLINE)\
	&& $(MARKDOWN) $(MARKDOWN_FLAGS)\
		$<\
			> $@\
	&& $(DONE);

#   html section with figure caption
#
#     TODO: Why would the target file not be treated as an intermediate file??
#
#     isolate <p>, </p> tags\
#     place a new </p> in front of first <img> line (if not inline)\
#     delete </p> line after last <img> line\
#     delete empty <p></p> combination\
#     search inline <img> and add <p></p> tags\
#     add <figure><figcaption></figcaption></figure> to <img> lines,\
#     but use html4 code as suggested on:\
#     https://www.w3.org/Style/Examples/007/figures.en.html#Illustrati
#
%.md.section.figcap : %.md.section
	@$(HEADLINE)\
	&& $(SED) $(SED_FLAGS)\
		--in-place\
		-e '/<img .*\/>/{; s/<p>/&\n/; s/<\/p>/\n&/; };'\
			$<\
	&& $(SED) $(SED_FLAGS)\
		--in-place\
		-e '/<p>/,/^<img .*\/>$$/{; s/^<img .*\/>$$/<\/p>\n&/; };'\
			$<\
	&& $(SED) $(SED_FLAGS)\
		--in-place\
		-e '/^<img .*\/>$$/,/^<\/p>/{; /^<\/p>$$/d; };'\
			$<\
	&& $(SED) $(SED_FLAGS)\
		--in-place\
		-e '/^<p>$$/{; N; /^<p>\n^<\/p>$$/d;};'\
			$<\
	&& $(SED) $(SED_FLAGS)\
		--in-place\
		-e '/^<p>/,/<\/p>/!{;'\
		-e '/^..*<img .*\/>..*$$/{; s/^/<p>/; s/$$/<\/p>/; };'\
		-e '/^..*<img .*\/>$$/{; s/^/<p>/; s/$$/<\/p>/; };'\
		-e '/^<img .*\/>..*$$/{; s/^/<p>/; s/$$/<\/p>/; };'\
		-e '};'\
			$<\
	&& $(SED) $(SED_FLAGS)\
		--in-place\
		-e '/^<img .*\/>$$/{;'\
		-e 'i\<div class="figure">\n<p>'\
		-e 'a\<\/div>'\
		-e 'P;'\
		-e 's/<img .*title=\"/<\/p>\n<p>\n/'\
		-e 's/\".*$$/\n<\/p>/'\
		-e '}'\
			$<\
	&& $(DONE);

#   generate list of copyright statements for title page
$(TITLEPAGE).copyright : $(TEMPLATE_TITLEPAGE)
	@$(HEADLINE)\
	&& $(SED) $(SED_FLAGS)\
		-e '/^Copyright/!d;'\
			$<\
				> $@\
	&& entries=$(strip\
		$$(\
			$(SCOPE_OF_COPYRIGHT)\
			| $(SED) $(SED_FLAGS) -e 's/(....)(-..-..)$$/\1/;'\
			| $(SORT) $(SORT_FLAGS)\
			| $(SED) $(SED_FLAGS) -e 's/ /\#/g;';\
		)\
	)\
	&& authors=$(strip\
		$$(\
			$(PRINTF) $(PRINTF_FLAGS) "$${entries}"\
			| $(SED) $(SED_FLAGS) -e 's/\#....$$//;'\
			| $(SORT) $(SORT_FLAGS)\
			| $(SED) $(SED_FLAGS) -e 's/ /\#/g;'\
		)\
	)\
	&& for author in $${authors};\
		do\
			years=$(strip\
				$$(\
					$(PRINTF) $(PRINTF_FLAGS) "$${entries}"\
					| $(SORT) $(SORT_FLAGS)\
					| $(SED) $(SED_FLAGS) -e '/'"$$author"'/!d; s/'"$$author"'\#//; s/$$/, /;'\
				)\
			)\
			&& years=$$($(ECHO) $(ECHO_FLAGS) $${years%, })\
			&& author=$$(\
				$(ECHO) $(ECHO_FLAGS) $${author}\
				| $(SED) $(SED_FLAGS) -e 's/\#/ /g;';\
			)\
			&& $(ECHO) $(ECHO_FLAGS)\
				"Copyright (C) $${years}  $${author}  "\
					>> $@;\
		done\
	&& $(DONE);

#   create title page file
$(TITLEPAGE) : $(TITLEPAGE).copyright $(TEMPLATE_TITLEPAGE)
	@$(HEADLINE)\
	&& $(SED) $(SED_FLAGS)\
		-e '/^Copyright|^~~Generated-Copyright-Statements~~/,$$d;'\
			$(TEMPLATE_TITLEPAGE)\
				> $@\
	&& $(CAT) $(CAT_FLAGS)\
		$<\
	| $(SORT) $(SORT_FLAGS)\
		-\
			>> $@\
	&& $(ECHO) $(ECHO_FLAGS)\
		>> $@\
	&& $(SED) $(SED_FLAGS)\
		-e '/^Permission/,/License\".$$/!d;'\
			$(TEMPLATE_TITLEPAGE)\
				>> $@\
	&& $(DONE);

#   create title page
titlepage : $(TITLEPAGE)
	@$(HEADLINE)\
	&& $(DONE);

archive : $(PROJECT_ARCHIVE)
	@$(HEADLINE)\
	&& $(DONE);

#   list archive members
archive-members : $(PROJECT_ARCHIVE)
	@$(HEADLINE)\
	&& $(TAR) $(TAR_FLAGS)\
		--file $<\
		--list\
	&& $(DONE);

$(PROJECT_ARCHIVE) : $(ROOT_GIT)
	@$(HEADLINE)\
	&& tmpfolder=$(basename $(@F))\
	&& $(GIT) $(GIT_FLAGS)\
		clone\
			--no-hardlinks\
			--branch master\
			$<\
				$(@D)/$${tmpfolder}\
	&& $(CD) $(CD_FLAGS)\
		$(@D)/\
	&& $(TAR) $(TAR_FLAGS)\
		--file $(@F)\
		--create\
			$${tmpfolder}\
	&& $(RM) $(RM_FLAGS) -r\
		$${tmpfolder}\
	&& $(CD) $(CD_FLAGS)\
		-\
	&& $(DONE);

#   clean title page
clean-titlepage :
	@$(HEADLINE)\
	&& $(RM) $(RM_FLAGS)\
		$(TITLEPAGE).copyright\
		$(TITLEPAGE)\
	&& $(DONE);

#   clean archive
clean-archive :
	@$(HEADLINE)\
	&& $(RM) $(RM_FLAGS)\
		$(PROJECT_ARCHIVE)\
	&& $(DONE);

#   clean generated files
clean : hello clean-titlepage clean-archive
	@$(HEADLINE)\
	&& $(RM) $(RM_FLAGS) -r\
		$(OUT_HTML)\
		$(PTR_FAVICON)\
		$(PTR_LOGO)\
		$(PTR_STYLESHEET)\
		$(STYLESHEET_BLACK)\
		$(STYLESHEET_WHITE)\
		$(THEMECONFIG)\
	&& $(DONE);