#   Zerocat Dev Kit --- Put the fun back into hardware development!
#
#   Copyright (C) 2021, 2022, 2023, 2024  Kai Mertens <kmx@posteo.net>
#
#   This file is part of Zerocat Dev Kit.
#
#   Zerocat Dev Kit 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 Dev Kit 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 Dev Kit.
#   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                          := $(SPACE)$(SPACE)$(SPACE)$(SPACE)
TOKEN_SPACE                   := ~~~SPACE~~~
TOKEN_URLSTART                := ~~~URLSTART~~~


# Root Paths
ROOT                          := ../
ROOT_GIT                      := ../.git/
#   Logo ...
ROOT_ARTWORK_LOGO             := ../artwork/logo/
#   GNU Guix System ...
ROOT_GUIX                     := ../guix/
ROOT_HW_GUIX                  := ../hardware/guix/
#   Documentation ...
ROOT_DOC                      := ../doc/
ROOT_IMAGES                   := ../images/
#   Artwork ...
ROOT_ARTWORK                  := ../artwork/
#   Firmware Sources ...
ROOT_FW                       := ../firmware/
ROOT_FW_SRC                   := ../firmware/src/
ROOT_FW_START                 := ../firmware/start/
#   Hardware ...
ROOT_HW                       := ../hardware/
ROOT_HW_ARTWORK               := ../hardware/artwork/
#   Hardware: System ...
ROOT_HW_SYSTEM_GSCHEM         := ../hardware/system/gschem/
ROOT_HW_SYSTEM_PCB            := ../hardware/system/pcb/


# Utilities
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 command -v echo;)
ECHO_FLAGS                    :=
$(if $(strip $(ECHO)),,       $(error Cannot find echo utility))

FIND                          := $(shell command -v find;)
FIND_FLAGS                    :=
$(if $(strip $(FIND)),,       $(error Cannot find find 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))

TEST                          := $(shell command -v test;)
TEST_FLAGS                    :=
$(if $(strip $(TEST)),,       $(error Cannot find test utility))

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

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

#   Note ‘mkdir -p’ might not be supported.
MKDIR                         := $(shell command -v mkdir;)
MKDIR_FLAGS                   :=
$(if $(strip $(MKDIR)),,      $(error Cannot find mkdir utility))

TOUCH                         := $(shell command -v touch;)
TOUCH_FLAGS                   :=
$(if $(strip $(TOUCH)),,      $(error Cannot find touch 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))


# Project Numbers
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_COMMIT                := $(strip\
	$(shell\
		$(SET) $(SET_FLAGS)\
		&& $(GIT) $(GIT_FLAGS)\
			describe\
				--long\
				--always\
		| $(SED) $(SED_FLAGS)\
			-e 's/^.*-g//;'\
				-\
	;)\
)


# Settings
MAKEFILE_TITLE                := Generate the Documentation
PROJECT_TITLE                 := Zerocat Dev Kit
PROJECT_BRIEF                 := Put the fun back into hardware development!
# Use escaped, special characters for image path:
PROJECT_IMAGE                 := $(subst /,\/,../hardware/system/pcb/display10x64.pcb.top.photo.png)
# Use escaped, special characters for image title:
PROJECT_IMAGE_TITLE           := Prototype, yet untested: Display 10x64 PCB, top view
PROJECT_REPO                  := git://zerocat.org/zerocat/projects/zerocat-dev-kit.git
PROJECT_WEBPAGE               := https://www.zerocat.org
PROJECT_TIME                  := $(shell LANG=en_US.utf8 && $(DATE) $(DATE_FLAGS);)
PROJECT_DATE                  := $(shell LANG=en_US.utf8 && $(DATE) +'%Y-%b-%d';)
PROJECT_ARCHIVE               := $(ROOT_DOC)$(notdir $(subst .git,,$(PROJECT_REPO)))-$(PROJECT_NUMBER).tar
DIR_RESOURCES                 := resources.$(PROJECT_COMMIT)@$(shell $(DATE) +%s;)


# 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              := $(subst .css,.black.css,$(STYLESHEET))
STYLESHEET_WHITE              := $(subst .css,.white.css,$(STYLESHEET))
PTR_STYLESHEET                := $(ROOT_DOC)stylesheet.css
TMPL_TITLEPAGE                := $(ROOT_DOC)TITLEPAGE.md.tmpl
TITLEPAGE                     := $(ROOT_DOC)TITLEPAGE.md
OUT_HTML                      := $(ROOT_DOC)index.html


# Chip Documentation
include chip-urls.mk


# Sources
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 %.mk\
				%favicon %logo\
				%.md.tmpl\
				%.txt %.css\
				%.md %.mdml %.mdwn %.markdown,\
				$(wildcard $(ROOT_DOC)*)\
			)\
		)\
	)\
)
FILES_ARTWORK                 := $(strip\
	$(sort\
		$(filter\
			%Makefile\
			%.txt\
			%.md %.mdml %.mdwn %.markdown\
			%.svg %.png %.jpg %.jpeg %.pdf,\
			$(wildcard $(ROOT_ARTWORK)*)\
		)\
	)\
)
FILES_LOGO                    := $(strip\
	$(sort\
		$(filter\
			%Makefile\
			%.txt\
			%.md %.mdml %.mdwn %.markdown\
			%.svg %.png %.jpg %.jpeg %.pdf,\
			$(wildcard $(ROOT_ARTWORK_LOGO)*)\
		)\
	)\
)
FILES_GNUGUIX                 := $(strip\
	$(sort\
		$(filter\
			%Makefile\
			%.mk\
			%.scm,\
			$(wildcard $(ROOT_GUIX)*)\
			$(wildcard $(ROOT_HW_GUIX)*)\
		)\
	)\
)
FILES_FIRMWARE_DOCU           := $(strip\
	$(sort\
		$(filter\
			%.spin.txt.html,\
			$(wildcard $(ROOT_FW_SRC)*)\
			$(wildcard $(ROOT_FW_START)*)\
		)\
	)\
)
FILES_FIRMWARE_CODE           := $(strip\
	$(sort\
		$(filter\
			%Makefile %.mk %.txt\
			%.cfg\
			%.spin,\
			$(wildcard $(ROOT_FW_SRC)*)\
			$(wildcard $(ROOT_FW_START)*)\
		)\
	)\
)
FILES_HARDWARE_DOCU           := $(strip\
	$(filter\
		%.txt.html\
		%.bom.txt.html\
		%.drc.html\
		%.sch.pdf\
		%.pcb.top.png\
		%.pcb.bottom.png,\
		$(wildcard $(ROOT_HW)*)\
		$(wildcard $(ROOT_HW_SYSTEM_GSCHEM)*)\
		$(wildcard $(ROOT_HW_SYSTEM_PCB)*)\
	)\
)
FILES_HARDWARE_CODE           := $(strip\
	$(sort\
		$(filter\
			%Makefile\
			%.mk\
			%.scm\
			%gafrc,\
			$(wildcard $(ROOT_HW)*)\
		)\
	)\
)
FILES_HARDWARE_CAD            := $(strip\
	$(sort\
		$(filter\
			%.svg\
			%.dxf,\
			$(wildcard $(ROOT_HW_ARTWORK)multiboard*)\
			$(wildcard $(ROOT_HW)librecad/*)\
		)\
	)\
)
FILES_HARDWARE_GSCHEM         := $(strip\
	$(sort\
		$(filter\
			%attribs\
			%.sch\
			%.sym,\
			$(wildcard $(ROOT_HW_SYSTEM_GSCHEM)symbols/*)\
			$(wildcard $(ROOT_HW_SYSTEM_GSCHEM)multiboard*)\
		)\
	)\
)
FILES_HARDWARE_PCB            := $(strip\
	$(sort\
		$(filter\
			%.pcb\
			%.pcb.tmpl\
			%.fp,\
			$(wildcard $(ROOT_HW_SYSTEM_PCB)*)\
			$(wildcard $(ROOT_HW_SYSTEM_PCB)footprints/*)\
		)\
	)\
)
FILES_HARDWARE_ARCHIVES       := $(strip\
	$(sort\
		$(filter\
			%.zip,\
			$(wildcard $(ROOT_HW_SYSTEM_PCB)*)\
		)\
	)\
)
FILES_IMG                     := $(strip\
	$(sort\
		$(filter\
			%.png %.jpg %.jpeg,\
			$(wildcard $(ROOT_DOC)*)\
			$(wildcard $(ROOT_IMAGES)*)\
		)\
	)\
)
SOURCES                       := $(strip\
	$(FILES_IMG)\
	$(FILES_DOC)\
	$(FILES_GNU)\
	$(FILES_GNUGUIX)\
	$(FILES_ARTWORK)\
	$(FILES_LOGO)\
	$(FILES_FIRMWARE_DOCU)\
	$(FILES_FIRMWARE_CODE)\
	$(FILES_HARDWARE_DOCU)\
	$(FILES_HARDWARE_CODE)\
	$(FILES_HARDWARE_CAD)\
	$(FILES_HARDWARE_GSCHEM)\
	$(FILES_HARDWARE_PCB)\
)


# Buttons: BUTTON_MAIN
BUTTON_MAIN                   := Main/Subordinate
DROPDOWN_MAIN                 = $(LIST_DOCUMENTATIONS)
MAIN                          := $(OUT_HTML)
#
# LIST_DOCUMENTATIONS, e.g.:
#
#     Documentation$(TOKEN_URLSTART)$(OUT_HTML)\
#
LIST_DOCUMENTATIONS           := $(strip\
)


# Buttons: BUTTON_TOP
BUTTON_TOP                    := Top/Sections
DROPDOWN_TOP                  = $(LIST_SECTIONS)
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))\
	$(filter $(ROOT_DOC)TODO.md,$(FILES_DOC))\
)
LIST_SECTIONS                 := $(strip\
	$(LIST_ORDERED)\
	$(sort\
		$(filter-out\
			$(LIST_ORDERED)\
			,$(filter\
				%.md,\
				$(FILES_DOC)\
			)\
		)\
	)\
	$(sort\
		$(FILES_GNU)\
	)\
)


# Buttons: BUTTON_TAIL
BUTTON_TAIL                   := Back to Top


# Buttons: BUTTON_ARTWORK
BUTTON_ARTWORK                := Artwork
DROPDOWN_ARTWORK              = $(FILES_ARTWORK)


# Buttons: BUTTON_LOGO
BUTTON_LOGO                   := Logo
DROPDOWN_LOGO                 = $(FILES_LOGO)


# Buttons: BUTTON_GNUGUIX
BUTTON_GNUGUIX                := GNU Guix Environment
DROPDOWN_GNUGUIX              = $(FILES_GNUGUIX)


# Buttons: BUTTON_FIRMWARE
BUTTON_FIRMWARE               := Firmware
DROPDOWN_FIRMWARE             = $(FILES_FIRMWARE_DOCU)


# Buttons: BUTTON_HARDWARE
BUTTON_HARDWARE               := System Design
DROPDOWN_HARDWARE             = $(FILES_HARDWARE_DOCU) $(FILES_HARDWARE_ARCHIVES)


# Button: BUTTON_FREE
BUTTON_FREE                   := Chips, free Design
DROPDOWN_FREE                 = $(CHIPS_FREE)


# Buttons: BUTTON_NONFREE
BUTTON_NONFREE                := Chips, non-free Design
DROPDOWN_NONFREE              = $(CHIPS_NONFREE)


# Tinned Cans: CAN_GETWEBPAGE
define CAN_GETWEBPAGE
$(strip\
	for n in $${list}\
		; do\
			url=$$(\
				$(ECHO) $(ECHO_FLAGS) $${n}\
				| $(SED) $(SED_FLAGS)\
					-e 's/^.*$(TOKEN_URLSTART)//;'\
			;)\
			&& $(WGET) $(WGET_FLAGS) -p -k\
				"$${url}"\
			|| $(TEST) $(TEST_FLAGS) $$? -eq 8\
			|| exit\
		; done\
)
endef


# Tinned Cans: CAN_GETURL
define CAN_GETURL
$(strip\
	for n in $${list}\
		; do\
			url=$$(\
				$(ECHO) $(ECHO_FLAGS) "$${n}"\
				| $(SED) $(SED_FLAGS)\
					-e 's/^.*$(TOKEN_URLSTART)//;'\
			)\
			&& filename=$$(\
				$(ECHO) $(ECHO_FLAGS) "$${url}"\
				| $(SED) $(SED_FLAGS)\
					-e 's/^.*\///;'\
					-e 's/^.*\&filename\=//;'\
					-e 's/\?.*//g;'\
			)\
			&& $(WGET) $(WGET_FLAGS)\
				-O "$${filename}"\
				"$${url}"\
			|| $(RM) $(RM_FLAGS) "$${filename}"\
		; done\
)
endef


# Tinned Cans: FIND_DOC_FILES
define FIND_DOC_FILES         =
$(strip\
	$$(\
		$(FIND) $(FIND_FLAGS)\
			$(ROOT_DOC)\
			-name "Makefile"\
			-o -name "$(notdir $(STYLESHEET))"\
			-o -name "*.md"\
			-a ! -name "GNU-FDL.md"\
			-a ! -name "GNU-GPL.md"\
	)\
)
endef


# Tinned Cans: HEADER
define HEADER                 =
$(strip\
	$(ECHO) $(ECHO_FLAGS)    ""\
	&& $(ECHO) $(ECHO_FLAGS) "$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)"\
	&& $(ECHO) $(ECHO_FLAGS) "$(M5) $(PROJECT_TITLE)"\
	&& $(ECHO) $(ECHO_FLAGS) "$(M5) – $(PROJECT_BRIEF)"\
	&& $(ECHO) $(ECHO_FLAGS) "$(M5) $(MAKEFILE_TITLE)"\
	&& $(ECHO) $(ECHO_FLAGS) "$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)"\
)
endef


# Tinned Cans: HEADLINE
define HEADLINE               =
$(strip\
	$(ECHO) $(ECHO_FLAGS) "$(M5) Process target “$@” $(M5)$(M5)"\
)
endef


# Tinned Cans: DONE
define DONE                   =
$(strip\
	$(ECHO) $(ECHO_FLAGS)    "... successfully processed: “$@”"\
	&& $(ECHO) $(ECHO_FLAGS) ""\
)
endef


# Tinned Cans: HTML_HEAD
define HTML_HEAD              =
$(strip\
	$(ECHO) $(ECHO_FLAGS)    "  <head>" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "    <meta http-equiv=\"content-type\" content=\"text/html; charset=UTF-8\">" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0, maximum-scale=3.0, user-scalable=1\">" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "    <link rel=\"icon\" type=\"image/png\" href=\"$${prefix}$(PTR_FAVICON)\">" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "    <title>$(PROJECT_TITLE) | $@</title>" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "    <style type=\"text/css\">" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "      @import url($${prefix}$(PTR_STYLESHEET)) all;" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "    </style>" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "  </head>" >> $@\
)
endef


# Tinned Cans: HTML_TOP
define HTML_TOP               =
$(strip\
	$(ECHO) $(ECHO_FLAGS)    "    <a name=\"top\"><div><br></div></a>" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "    <a href=\"$(PROJECT_WEBPAGE)\">" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "      <img id=\"project-logo\" src=\"$${prefix}$(PTR_LOGO)\" alt=\"$${prefix}$(PTR_LOGO)\">" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "    </a>" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "    <p id="doc-reference">" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "      Documentation for “$(PROJECT_TITLE)”<br>" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "      Generated on: $(PROJECT_TIME)<br>" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "      Repository: $(PROJECT_REPO)<br>" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "      Version: $(PROJECT_NUMBER)<br>" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "      Branch: $(PROJECT_BRANCH)<br>" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "    </p>" >> $@\
)
endef


# Tinned Cans: URL_DROPDOWN
#   dropdown_label:   Button Label
#   dropdown_urls:    List of URLs for Dropdown Box
define URL_DROPDOWN           =
$(strip\
	if $(TEST) $(TEST_FLAGS) -n "$$dropdown_urls"\
		; then\
			$(ECHO) $(ECHO_FLAGS)            "        <div>" >> $@\
			&& if $(TEST) $(TEST_FLAGS) "$${dropdown_label}" = "$(BUTTON_MAIN)"\
				; then\
					$(ECHO) $(ECHO_FLAGS)        "          <a href=\"$(MAIN)\">" >> $@\
					&& $(ECHO) $(ECHO_FLAGS)     "            <button type=\"button\">$$dropdown_label</button>" >> $@\
					&& $(ECHO) $(ECHO_FLAGS)     "          </a>" >> $@\
				; else\
					$(ECHO) $(ECHO_FLAGS)        "          <button type=\"button\">$$dropdown_label</button>" >> $@\
				; fi\
			&& $(ECHO) $(ECHO_FLAGS)         "          <div>" >> $@\
			&& if $(TEST) $(TEST_FLAGS) -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) "            <a href=\"$${url}\">$${label}</a>" >> $@\
						; done\
				; fi\
			&& $(ECHO) $(ECHO_FLAGS)         "          </div>" >> $@\
			&& $(ECHO) $(ECHO_FLAGS)         "        </div>" >> $@\
		; fi\
)
endef


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


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


# Tinned Cans: NAVBAR
#
#   Main/Sub | Top/Sections | Artwork | GNU Guix Environment | Sources ... | URLs ...
#
define NAVBAR                 =
$(strip\
	$(ECHO) $(ECHO_FLAGS)    "    <div class=\"navbar-container\">" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "      <a id=\"$${id}\"></a>" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "      <div class=\"navbar\">" >> $@\
	&& dropdown_label="$(BUTTON_MAIN)"\
	&& dropdown_urls="$(DROPDOWN_MAIN)"\
	&& $(URL_DROPDOWN)\
	&& dropdown_label="$(BUTTON_TOP)"\
	&& dropdown_tags="$(DROPDOWN_TOP)"\
	&& $(TAG_DROPDOWN)\
	&& dropdown_label="$(BUTTON_ARTWORK)"\
	&& dropdown_files="$(DROPDOWN_ARTWORK)"\
	&& $(FILE_DROPDOWN)\
	&& dropdown_label="$(BUTTON_GNUGUIX)"\
	&& dropdown_files="$(DROPDOWN_GNUGUIX)"\
	&& $(FILE_DROPDOWN)\
	&& dropdown_label="$(BUTTON_FIRMWARE)"\
	&& dropdown_files="$(DROPDOWN_FIRMWARE)"\
	&& $(FILE_DROPDOWN)\
	&& dropdown_label="$(BUTTON_HARDWARE)"\
	&& dropdown_files="$(DROPDOWN_HARDWARE)"\
	&& $(FILE_DROPDOWN)\
	&& dropdown_label="$(BUTTON_FREE)"\
	&& dropdown_urls="$(DROPDOWN_FREE)"\
	&& $(URL_DROPDOWN)\
	&& dropdown_label="$(BUTTON_NONFREE)"\
	&& dropdown_urls="$(DROPDOWN_NONFREE)"\
	&& $(URL_DROPDOWN)\
	&& $(ECHO) $(ECHO_FLAGS) "      </div>" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "    </div>" >> $@\
)
endef


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


# Tinned Cans: BACK_BUTTON
define BACK_BUTTON
$(strip\
	$(ECHO) $(ECHO_FLAGS)    "    <div class=\"navbar-container\">" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "      <a id=\"$${id}\"></a>" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "      <div class=\"navbar\">" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "        <div>" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "          <a href=\"$${prefix}$(ROOT_DOC)index.html\"><button type=\"button\">Back to Main</button></a>" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "          <div>" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "          </div>" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "        </div>" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "      </div>" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "    </div>" >> $@\
)
endef


# Tinned Cans: WRAP_TXT_INTO_HTML
define WRAP_TXT_INTO_HTML            =
$(strip\
	$(ECHO) $(ECHO_FLAGS)    "<!DOCTYPE html>" > $@\
	&& $(ECHO) $(ECHO_FLAGS) "<html>" >> $@\
	&& $(HTML_HEAD)\
	&& $(ECHO) $(ECHO_FLAGS) "  <body>" >> $@\
	&& $(HTML_TOP)\
	&& $(BACK_BUTTON)\
	&& $(ECHO) $(ECHO_FLAGS) "    <h1>$@</h1>" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "    <pre>" >> $@\
	&& $(SED) $(SED_FLAGS)\
		-e 's/<.*@.*\..*>//g;'\
		-e 's/\&/\&amp;/g; s/\"/\&quot;/g;'\
		-e 's/</\&lt;/g; s/>/\&gt;/g;'\
			$<\
				>> $@\
	&& $(ECHO) $(ECHO_FLAGS) "    </pre>" >> $@\
	&& $(TAIL_BUTTON)\
	&& $(ECHO) $(ECHO_FLAGS) "  </body>" >> $@\
	&& $(ECHO) $(ECHO_FLAGS) "</html>" >> $@\
)
endef


# Suffixes, to be checked for old fashioned suffix rules
.SUFFIXES :


# Intermediate Targets
#~ .INTERMEDIATE :


# Secondary Targets
#~ .SECONDARY :                  # Uncomment for debugging


# Phony Targets
.PHONY :\
	all\
	\
	hello\
	help\
	\
	config-icon-black\
	config-icon-white\
	config-black\
	config-white\
	\
	titlepage\
	wrap-firmware-docs\
	wrap-hardware-docs\
	point-to-html\
	archive-members\
	archive\
	resources\
	\
	clean-resources\
	clean-hardware-docs\
	clean-firmware-docs\
	clean-titlepage\
	clean-archives\
	clean


# Targets
#   reset skin, generate all documents
all : hello
	@$(HEADLINE)\
	&& $(MAKE)\
		config-icon-black\
	&& $(MAKE)\
		config-white\
	&& $(MAKE)\
		-C $(ROOT_FW_SRC)\
			docs\
	&& $(MAKE)\
		wrap-firmware-docs\
	&& $(MAKE)\
		wrap-hardware-docs\
	&& $(MAKE)\
		point-to-html\
	&& $(DONE);

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

#   display help information
help : hello
	@$(HEADLINE)\
	&& $(CAT) $(CAT_FLAGS)\
		$(ROOT_DOC)help.txt\
	&& $(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);

#   wrap firmware *.spin.txt files into html
wrap-firmware-docs : $(addsuffix .html,$(wildcard $(ROOT_FW_SRC)*.spin.txt))
	@$(HEADLINE)\
	&& $(DONE);

#   wrap hardware gschem *.txt and *.drc files into html
wrap-hardware-docs :\
	$(addsuffix .html,$(wildcard $(ROOT_HW)*.txt))\
		$(addsuffix .html,$(wildcard $(ROOT_HW_SYSTEM_GSCHEM)*.drc))\
			$(addsuffix .html,$(wildcard $(ROOT_HW_SYSTEM_GSCHEM)*.bom.txt))
	@$(HEADLINE)\
	&& $(DONE);

#   wrap *.drc files into html
%.drc.html : %.drc
	@$(HEADLINE)\
	&& prefix="../../"\
	&& $(WRAP_TXT_INTO_HTML)\
	&& $(DONE);

#   wrap *.txt files into html
%.txt.html : %.txt
	@$(HEADLINE)\
	&& prefix=""\
	&& $(WRAP_TXT_INTO_HTML)\
	&& $(DONE);

#   wrap *.spin.txt files into html
%.spin.txt.html : %.spin.txt
	@$(HEADLINE)\
	&& prefix="../"\
	&& $(WRAP_TXT_INTO_HTML)\
	&& $(DONE);

#   wrap *.bom.txt files into html
%.bom.txt.html : %.bom.txt
	@$(HEADLINE)\
	&& prefix="../../"\
	&& $(WRAP_TXT_INTO_HTML)\
	&& $(DONE);

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

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

#   create project archive to ease distribution
archive : $(PROJECT_ARCHIVE)
	@$(HEADLINE)\
	&& $(DONE);

#   list archive members
archive-members : $(PROJECT_ARCHIVE)
	@$(HEADLINE)\
	&& $(TAR) $(TAR_FLAGS)\
		--file $<\
		--list\
	&& $(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 $(TEST) $(TEST_FLAGS) "`$(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 $(TEST) $(TEST_FLAGS) "`$(SED) $(SED_FLAGS) -e '/config-white/!d;' $<`" != ""\
		; then\
			$(LN) $(LN_FLAGS)\
				$(LOGO_BLACK) $@\
		; else\
			$(LN) $(LN_FLAGS)\
				$(LOGO_WHITE) $@\
		; fi\
	&& $(TOUCH) $(TOUCH_FLAGS)\
		$@\
	&& $(DONE);

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

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

#   generate list of copyright statements for title page
$(TITLEPAGE).copyright : $(TMPL_TITLEPAGE)
	@$(HEADLINE)\
	&& $(SED) $(SED_FLAGS)\
		-e '/^Copyright/!d;'\
			$<\
				> $@\
	&& tmpfile=$(strip\
		$$(\
			$(MKTEMP) $(MKTEMP_FLAGS)\
				copyrights.XXXXXXX\
		)\
	)\
	&& files=($(FIND_DOC_FILES))\
	&& $(ECHO) $(ECHO_FLAGS) ""\
	&& $(ECHO) $(ECHO_FLAGS) "Files to parse:"\
	&& $(ECHO) $(ECHO_FLAGS) "$${files[@]}"\
	&& $(ECHO) $(ECHO_FLAGS) ""\
	&& $(ECHO) $(ECHO_FLAGS) "All copyright statements:"\
	&& $(strip\
		$(SED) $(SED_FLAGS) -r\
			-e's/[\t ]/#/g;                                         # convert white space into token'\
			-e's/^[#]*//g;                                          # remove in excess characters at line start'\
			-e's/[#]*$$//g;                                         # remove in excess characters at line end'\
			-e'/[Cc]opyright#\([cC]\)#[0-9][0-9][0-9][0-9]/!d;      # filter copyright statements'\
				$${files[@]}\
	)\
	| $(SORT) $(SORT_FLAGS)\
		-\
			> $${tmpfile}\
	&& $(CAT) $(CAT_FLAGS)\
		$${tmpfile}\
	&& $(ECHO) $(ECHO_FLAGS) ""\
	&& $(ECHO) $(ECHO_FLAGS) "Uniq candidates:"\
	&& candidates=$(strip\
		(\
			$$(\
				$(CAT) $(CAT_FLAGS)\
					$${tmpfile}\
				| $(SED) $(SED_FLAGS) -r\
					-e's/([Cc]opyright#\([cC]\)#)//;            # remove copyright intro'\
					-e's/[,0-9#–\-]*//;                         # remove years'\
				| $(SORT) $(SORT_FLAGS)\
					-\
			)\
		)\
	)\
	&& $(ECHO) $(ECHO_FLAGS) "$${candidates[@]}"\
	&& $(ECHO) $(ECHO_FLAGS) ""\
	&& $(ECHO) $(ECHO_FLAGS) "Compound copyright statements:"\
	&& $(strip\
		for i in $${!candidates[@]}\
			; do\
				years=(\
					$$(\
						$(CAT) $(CAT_FLAGS)\
							$${tmpfile}\
						| $(SED) $(SED_FLAGS) -r\
							-e"/$${candidates[i]}/!d;               # filter statements of uniq candidate"\
						| $(SED) $(SED_FLAGS) -r\
							-e's/\,//g;                             # remove commata'\
							-e's/([Cc]opyright#\([cC]\)#)//;        # remove copyright intro'\
							-e's/([0-9#–\-]*)(.*$$)/\1/;            # remove name and email'\
							-e's/#*$$//;                            # remove trailing tokens'\
							-e's/#/\n/g;                            # break line into multiple lines'\
						| $(SORT) $(SORT_FLAGS)\
						| $(SED) $(SED_FLAGS) -r\
							-e's/$$/,/g;                            # add commata'\
							-e'$$s/,//g;                            # but remove last one'\
								-\
					)\
				)\
			)\
			&& $(ECHO) $(ECHO_FLAGS) "Copyright (C) $${years[@]//#/ }  $${candidates[i]//#/ }  "\
			&& $(ECHO) $(ECHO_FLAGS) "Copyright (C) $${years[@]//#/ }  $${candidates[i]//#/ }  " >> $@\
		; done\
	&& $(RM) $(RM_FLAGS)\
		$${tmpfile}\
	&& $(DONE);

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

#   html documentation
$(OUT_HTML) : $(SOURCES) $(TITLEPAGE) $(addsuffix .section.figcap,$(LIST_SECTIONS))
	@$(HEADLINE)\
	&& $(ECHO) $(ECHO_FLAGS)     "<!DOCTYPE html>" > $@\
	&& $(ECHO) $(ECHO_FLAGS)     "<html>" >> $@\
	&& $(HTML_HEAD)\
	&& $(ECHO) $(ECHO_FLAGS)     "  <body>" >> $@\
	&& $(HTML_TOP)\
	&& id="topnav"\
	&& $(NAVBAR)\
	&& $(ECHO) $(ECHO_FLAGS)     "    <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)     "    </div>" >> $@\
	&& for i in $(LIST_SECTIONS)\
		; do\
			id="$${i}"\
			&& prefix=""\
			&& $(NAVBAR)\
			&& $(ECHO) $(ECHO_FLAGS) "    <div class=\"section\">" >> $@\
			&& $(ECHO) $(ECHO_FLAGS) "      <div class=\"section-file\">Section #$${i}</div>" >> $@\
			&& $(CAT) $(CAT_FLAGS)\
				$${i}.section\
					>> $@\
			&& $(ECHO) $(ECHO_FLAGS) "    </div>" >> $@\
		; done\
	&& id="tail"\
	&& $(TAIL_BUTTON)\
	&& $(ECHO) $(ECHO_FLAGS)     "    <br>" >> $@\
	&& $(ECHO) $(ECHO_FLAGS)     "  </body>" >> $@\
	&& $(ECHO) $(ECHO_FLAGS)     "</html>" >> $@\
	&& $(DONE);

$(PROJECT_ARCHIVE) : $(ROOT_GIT)
	@$(HEADLINE)\
	&& tmpfolder=$(basename $(@F))\
	&& $(GIT) $(GIT_FLAGS)\
		clone\
			--no-hardlinks\
			$<\
				$(@D)/$${tmpfolder}\
	&& $(CD) $(CD_FLAGS)\
		$(@D)/\
	&& $(TAR) $(TAR_FLAGS)\
		--file $(@F)\
		--create\
			$${tmpfolder}\
	&& $(RM) $(RM_FLAGS) -r\
		$${tmpfolder}\
	&& $(CD) $(CD_FLAGS)\
		-\
	&& $(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
%.md.section.figcap : %.md.section
	@$(HEADLINE)\
	&& $(SED) $(SED_FLAGS)\
		--in-place\
		-e '# isolate <p>, </p> tags'\
		-e '/<img .*\/>/{; s/<p>/&\n/; s/<\/p>/\n&/; };'\
			$<\
	&& $(SED) $(SED_FLAGS)\
		--in-place\
		-e '# place a new </p> in front of first <img> line (if not inline)'\
		-e '/<p>/,/^<img .*\/>$$/{; s/^<img .*\/>$$/<\/p>\n&/; };'\
			$<\
	&& $(SED) $(SED_FLAGS)\
		--in-place\
		-e '# delete </p> line after last <img> line'\
		-e '/^<img .*\/>$$/,/^<\/p>/{; /^<\/p>$$/d; };'\
			$<\
	&& $(SED) $(SED_FLAGS)\
		--in-place\
		-e '# delete empty <p></p> combination'\
		-e '/^<p>$$/{; N; /^<p>\n^<\/p>$$/d;};'\
			$<\
	&& $(SED) $(SED_FLAGS)\
		--in-place\
		-e '# search inline <img> and add <p></p> tags'\
		-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 '# add <figure><figcaption></figcaption></figure> to <img> lines,'\
		-e '# but use html4 code as suggested on:'\
		-e '# https://www.w3.org/Style/Examples/007/figures.en.html#Illustrati'\
		-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);

#   Download chip resources
resources : | $(DIR_RESOURCES)
	@$(HEADLINE)\
	&& dir_P8X32A="P8X32A"\
	&& dir_other="other"\
	&& $(ECHO) $(ECHO_FLAGS) "Descending into $(DIR_RESOURCES) ..."\
	&& $(CD) $(CD_FLAGS) $(DIR_RESOURCES)\
	&& $(ECHO) $(ECHO_FLAGS) "Downloading files from various web sites ..."\
	&& $(MKDIR) $(MKDIR_FLAGS) $${dir_P8X32A}\
	&& $(CD) $(CD_FLAGS) $${dir_P8X32A}\
	&& list="$(PAGES_P8X32A)"\
	&& $(CAN_GETWEBPAGE)\
	&& list="$(DOCS_P8X32A)"\
	&& $(CAN_GETURL)\
	&& $(CD) $(CD_FLAGS) ..\
	&& $(MKDIR) $(MKDIR_FLAGS) $${dir_other}\
	&& $(CD) $(CD_FLAGS) $${dir_other}\
	&& list="$(DOCS_OTHER)"\
	&& $(CAN_GETURL)\
	&& $(CD) $(CD_FLAGS) ..\
	&& $(ECHO) $(ECHO_FLAGS) "... done."\
	&& $(ECHO) $(ECHO_FLAGS) "Leaving $(DIR_RESOURCES) ..."\
	&& $(CD) $(CD_FLAGS) -\
	&& $(ECHO) $(ECHO_FLAGS) "... done."\
	&& $(DONE);

#   resources folder
$(DIR_RESOURCES) :
	@$(HEADLINE)\
	&& $(MKDIR) $(MKDIR_FLAGS)\
		$@\
	&& $(DONE);

#   clean downloaded resources
clean-resources :
	@$(HEADLINE)\
	&& $(ECHO) $(ECHO_FLAGS) "Removing temporary download folders ..."\
	&& $(RM) $(RM_FLAGS) -r\
		$(wildcard $(subst clean-,,$@).*@[0-9]*)\
	&& $(ECHO) $(ECHO_FLAGS) "... done."\
	&& $(DONE);

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

#   clean archives
clean-archives :
	@$(HEADLINE)\
	&& $(RM) $(RM_FLAGS)\
		$(wildcard $(ROOT_DOC)$(notdir $(subst .git,,$(PROJECT_REPO)))*.tar)\
	&& $(DONE);

#   clean hardware compiled, wrapped txt output
clean-hardware-docs :
	@$(HEADLINE)\
	&& $(RM) $(RM_FLAGS)\
		$(wildcard\
			$(ROOT_HW)*.txt.html\
			$(ROOT_HW_SYSTEM_GSCHEM)*.bom.txt.html\
			$(ROOT_HW_SYSTEM_GSCHEM)*.drc.html\
		)\
	&& $(DONE);

#   clean firmware compiled, wrapped txt output
clean-firmware-docs :
	@$(HEADLINE)\
	&& $(RM) $(RM_FLAGS)\
		$(wildcard $(ROOT_FW_SRC)*.spin.txt.html)\
	&& $(MAKE)\
		-C $(ROOT_FW_SRC)\
			clean-docs\
	&& $(DONE);

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