[buildroot-mgba.git] / package / doc-asciidoc.mk

# we can't use suitable-host-package here because that's not available in
# the context of 'make release'
asciidoc-check-dependencies:
	$(Q)if [ -z "$(shell support/dependencies/check-host-asciidoc.sh)" ]; then \
		echo "You need a sufficiently recent asciidoc on your host" \
			"to generate documents"; \
		exit 1; \
	fi
	$(Q)if [ -z "`which w3m 2>/dev/null`" ]; then \
		echo "You need w3m on your host to generate documents"; \
		exit 1; \
	fi

asciidoc-check-dependencies-pdf:
	$(Q)if [ -z "`which dblatex 2>/dev/null`" ]; then \
		echo "You need dblatex on your host to generate PDF documents"; \
		exit 1; \
	fi

# PDF generation is broken because of a bug in xsltproc program provided
# by libxslt <=1.1.28, which does not honor an option we need to set.
# Fortunately, this bug is already fixed upstream:
#   https://gitorious.org/libxslt/libxslt/commit/5af7ad745323004984287e48b42712e7305de35c
#
# So, bail out when trying to build a PDF using a buggy version of the
# xsltproc program.
#
# So, to overcome this issue and being able to build a PDF, you can
# build xsltproc from its source repository, then run:
#   $ PATH=/path/to/custom-xsltproc/bin:${PATH} make manual
GENDOC_XSLTPROC_IS_BROKEN = \
	$(shell xsltproc --maxvars 0 >/dev/null 2>/dev/null || echo y)

# Apply this configuration to all documents
BR_ASCIIDOC_CONF = docs/conf/asciidoc.conf

################################################################################
# ASCIIDOC_INNER -- generates the make targets needed to build a specific type of
#                   asciidoc documentation.
#
#  argument 1 is the name of the document and the top-level asciidoc file must
#             have the same name
#  argument 2 is the uppercase name of the document
#  argument 3 is the directory containing the document
#  argument 4 is the type of document to generate (-f argument of a2x)
#  argument 5 is the document type as used in the make target
#  argument 6 is the output file extension for the document type
#  argument 7 is the human text for the document type
#  argument 8 (optional) are extra arguments for a2x
#
# The variable <DOCUMENT_NAME>_SOURCES defines the dependencies.
#
# Since this function will be called from within an $(eval ...)
# all variable references except the arguments must be $$-quoted.
################################################################################
define ASCIIDOC_INNER
$(1): $(1)-$(5)
.PHONY: $(1)-$(5)
$(1)-$(5): $$(O)/docs/$(1)/$(1).$(6)

# Single line, because splitting a foreach is not easy...
asciidoc-check-dependencies-$(5):
$(1)-check-dependencies-$(5): asciidoc-check-dependencies-$(5)
	$$(Q)$$(foreach hook,$$($(2)_CHECK_DEPENDENCIES_$$(call UPPERCASE,$(5))_HOOKS),$$(call $$(hook))$$(sep))

# Include Buildroot's AsciiDoc configuration first:
#  - generic configuration,
#  - then output-specific configuration
ifneq ($$(wildcard $$(BR_ASCIIDOC_CONF)),)
$(2)_$(4)_ASCIIDOC_OPTS += -f $$(BR_ASCIIDOC_CONF)
endif
BR_$(4)_ASCIIDOC_CONF = docs/conf/asciidoc-$(4).conf
ifneq ($$(wildcard $$(BR_$(4)_ASCIIDOC_CONF)),)
$(2)_$(4)_ASCIIDOC_OPTS += -f $$(BR_$(4)_ASCIIDOC_CONF)
endif

# Then include the document's AsciiDoc configuration:
#  - generic configuration,
#  - then output-specific configuration
ifneq ($$(wildcard $$($(2)_ASCIIDOC_CONF)),)
$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_ASCIIDOC_CONF)
endif
$(2)_$(4)_ASCIIDOC_CONF = $(3)/asciidoc-$(4).conf
ifneq ($$(wildcard $$($(2)_$(4)_ASCIIDOC_CONF)),)
$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_$(4)_ASCIIDOC_CONF)
endif

# Handle a2x warning about --destination-dir option only applicable to HTML
# based outputs. So:
# - use the --destination-dir option if possible (html and split-html),
# - otherwise copy the generated document to the output directory
$(2)_$(4)_A2X_OPTS =
ifneq ($$(filter $(5),html split-html),)
$(2)_$(4)_A2X_OPTS += --destination-dir="$$(@D)"
else
define $(2)_$(4)_INSTALL_CMDS
	$$(Q)cp -f $$(BUILD_DIR)/docs/$(1)/$(1).$(6) $$(@D)
endef
endif

$$(O)/docs/$(1)/$(1).$(6): export TZ=UTC

ifeq ($(6)-$$(GENDOC_XSLTPROC_IS_BROKEN),pdf-y)
$$(O)/docs/$(1)/$(1).$(6):
	$$(warning PDF generation is disabled because of a bug in \
		xsltproc. To be able to generate a PDF, you should \
		build xsltproc from the libxslt sources >=1.1.29 and pass it \
		to make through the command line: \
		'PATH=/path/to/custom-xsltproc/bin:$$$${PATH} make $(1)-pdf')
else
# -r $(@D) is there for documents that use external filters; those filters
# generate code at the same location it finds the document's source files.
$$(O)/docs/$(1)/$(1).$(6): $$($(2)_SOURCES) \
			   $(1)-check-dependencies \
			   $(1)-check-dependencies-$(5) \
			   $(1)-prepare-sources
	$$(Q)$$(call MESSAGE,"Generating $(7) $(1)...")
	$$(Q)mkdir -p $$(@D)
	$$(Q)a2x $(8) -f $(4) -d book -L \
		$$(foreach r,$$($(2)_RESOURCES) $$(@D), \
			--resource="$$(abspath $$(r))") \
		$$($(2)_$(4)_A2X_OPTS) \
		--asciidoc-opts="$$($(2)_$(4)_ASCIIDOC_OPTS)" \
		$$(BUILD_DIR)/docs/$(1)/$(1).txt
# install the generated document
	$$($(2)_$(4)_INSTALL_CMDS)
endif
endef

################################################################################
# ASCIIDOC -- generates the make targets needed to build asciidoc documentation.
#
# argument 1 is the lowercase name of the document; the document's main file
#            must have the same name, with the .txt extension
# argument 2 is the uppercase name of the document
# argument 3 is the directory containing the document's sources
#
# The variable <DOCUMENT_NAME>_SOURCES defines the dependencies.
# The variable <DOCUMENT_NAME>_RESOURCES defines where the document's
# resources, such as images, are located; must be an absolute path.
################################################################################
define ASCIIDOC
# Single line, because splitting a foreach is not easy...
$(1)-check-dependencies: asciidoc-check-dependencies $$($(2)_DEPENDENCIES)
	$$(Q)$$(foreach hook,$$($(2)_CHECK_DEPENDENCIES_HOOKS),$$(call $$(hook))$$(sep))

# Single line, because splitting a foreach is not easy...
# Do not touch the stamp file, so we get to rsync again every time we build
# the document.
$$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced:
	$$(Q)$$(call MESSAGE,"Preparing the $(1) sources...")
	$$(Q)mkdir -p $$(@D)
	$$(Q)rsync -a $(3) $$(@D)
	$$(Q)$$(foreach hook,$$($(2)_POST_RSYNC_HOOKS),$$(call $$(hook))$$(sep))

$(1)-prepare-sources: $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced

$(2)_ASCIIDOC_CONF = $(3)/asciidoc.conf

$(call ASCIIDOC_INNER,$(1),$(2),$(3),xhtml,html,html,HTML,\
	--xsltproc-opts "--stringparam toc.section.depth 1")

$(call ASCIIDOC_INNER,$(1),$(2),$(3),chunked,split-html,chunked,split HTML,\
	--xsltproc-opts "--stringparam toc.section.depth 1")

# dblatex needs to pass the '--maxvars ...' option to xsltproc to prevent it
# from reaching the template recursion limit when processing the (long) target
# package table and bailing out.
$(call ASCIIDOC_INNER,$(1),$(2),$(3),pdf,pdf,pdf,PDF,\
	--dblatex-opts "-P latex.output.revhistory=0 -x '--maxvars 100000'")

$(call ASCIIDOC_INNER,$(1),$(2),$(3),text,text,text,text)

$(call ASCIIDOC_INNER,$(1),$(2),$(3),epub,epub,epub,ePUB)

clean: $(1)-clean
$(1)-clean:
	$$(Q)$$(RM) -rf $$(BUILD_DIR)/docs/$(1)
.PHONY: $(1) $(1)-clean
endef

################################################################################
# asciidoc-document -- the target generator macro for asciidoc documents
################################################################################

asciidoc-document = $(call ASCIIDOC,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir))
Commit	Line	Data
2dfe1b83 YM	1	# we can't use suitable-host-package here because that's not available in
2dfe1b83 YM	2	# the context of 'make release'
ab6a6212	3	asciidoc-check-dependencies:
2dfe1b83 YM	4	$(Q)if [ -z "$(shell support/dependencies/check-host-asciidoc.sh)" ]; then \
	5	echo "You need a sufficiently recent asciidoc on your host" \
	6	"to generate documents"; \
	7	exit 1; \
	8	fi
	9	$(Q)if [ -z "`which w3m 2>/dev/null`" ]; then \
	10	echo "You need w3m on your host to generate documents"; \
	11	exit 1; \
	12	fi
	13
ab6a6212	14	asciidoc-check-dependencies-pdf:
2dfe1b83 YM	15	$(Q)if [ -z "`which dblatex 2>/dev/null`" ]; then \
	16	echo "You need dblatex on your host to generate PDF documents"; \
	17	exit 1; \
	18	fi
	19
	20	# PDF generation is broken because of a bug in xsltproc program provided
	21	# by libxslt <=1.1.28, which does not honor an option we need to set.
	22	# Fortunately, this bug is already fixed upstream:
	23	# https://gitorious.org/libxslt/libxslt/commit/5af7ad745323004984287e48b42712e7305de35c
	24	#
	25	# So, bail out when trying to build a PDF using a buggy version of the
	26	# xsltproc program.
	27	#
	28	# So, to overcome this issue and being able to build a PDF, you can
	29	# build xsltproc from its source repository, then run:
	30	# $ PATH=/path/to/custom-xsltproc/bin:${PATH} make manual
	31	GENDOC_XSLTPROC_IS_BROKEN = \
	32	$(shell xsltproc --maxvars 0 >/dev/null 2>/dev/null \|\| echo y)
	33
d79042bd YM	34	# Apply this configuration to all documents
	35	BR_ASCIIDOC_CONF = docs/conf/asciidoc.conf
	36
2dfe1b83	37	################################################################################
ab6a6212 YM	38	# ASCIIDOC_INNER -- generates the make targets needed to build a specific type of
ab6a6212 YM	39	# asciidoc documentation.
2dfe1b83 YM	40	#
	41	# argument 1 is the name of the document and the top-level asciidoc file must
	42	# have the same name
	43	# argument 2 is the uppercase name of the document
	44	# argument 3 is the directory containing the document
	45	# argument 4 is the type of document to generate (-f argument of a2x)
	46	# argument 5 is the document type as used in the make target
	47	# argument 6 is the output file extension for the document type
	48	# argument 7 is the human text for the document type
	49	# argument 8 (optional) are extra arguments for a2x
	50	#
	51	# The variable <DOCUMENT_NAME>_SOURCES defines the dependencies.
	52	#
	53	# Since this function will be called from within an $(eval ...)
	54	# all variable references except the arguments must be $$-quoted.
	55	################################################################################
ab6a6212	56	define ASCIIDOC_INNER
2dfe1b83 YM	57	$(1): $(1)-$(5)
	58	.PHONY: $(1)-$(5)
	59	$(1)-$(5): $$(O)/docs/$(1)/$(1).$(6)
	60
	61	# Single line, because splitting a foreach is not easy...
ab6a6212 YM	62	asciidoc-check-dependencies-$(5):
ab6a6212 YM	63	$(1)-check-dependencies-$(5): asciidoc-check-dependencies-$(5)
2dfe1b83 YM	64	$$(Q)$$(foreach hook,$$($(2)_CHECK_DEPENDENCIES_$$(call UPPERCASE,$(5))_HOOKS),$$(call $$(hook))$$(sep))
2dfe1b83 YM	65
d79042bd YM	66	# Include Buildroot's AsciiDoc configuration first:
	67	# - generic configuration,
	68	# - then output-specific configuration
	69	ifneq ($$(wildcard $$(BR_ASCIIDOC_CONF)),)
	70	$(2)_$(4)_ASCIIDOC_OPTS += -f $$(BR_ASCIIDOC_CONF)
	71	endif
	72	BR_$(4)_ASCIIDOC_CONF = docs/conf/asciidoc-$(4).conf
	73	ifneq ($$(wildcard $$(BR_$(4)_ASCIIDOC_CONF)),)
	74	$(2)_$(4)_ASCIIDOC_OPTS += -f $$(BR_$(4)_ASCIIDOC_CONF)
	75	endif
	76
	77	# Then include the document's AsciiDoc configuration:
	78	# - generic configuration,
	79	# - then output-specific configuration
3c40c9ee YM	80	ifneq ($$(wildcard $$($(2)_ASCIIDOC_CONF)),)
	81	$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_ASCIIDOC_CONF)
	82	endif
2dfe1b83 YM	83	$(2)_$(4)_ASCIIDOC_CONF = $(3)/asciidoc-$(4).conf
	84	ifneq ($$(wildcard $$($(2)_$(4)_ASCIIDOC_CONF)),)
	85	$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_$(4)_ASCIIDOC_CONF)
	86	endif
	87
	88	# Handle a2x warning about --destination-dir option only applicable to HTML
	89	# based outputs. So:
	90	# - use the --destination-dir option if possible (html and split-html),
	91	# - otherwise copy the generated document to the output directory
	92	$(2)_$(4)_A2X_OPTS =
	93	ifneq ($$(filter $(5),html split-html),)
	94	$(2)_$(4)_A2X_OPTS += --destination-dir="$$(@D)"
	95	else
	96	define $(2)_$(4)_INSTALL_CMDS
	97	$$(Q)cp -f $$(BUILD_DIR)/docs/$(1)/$(1).$(6) $$(@D)
	98	endef
	99	endif
	100
e2cd2337 YM	101	$$(O)/docs/$(1)/$(1).$(6): export TZ=UTC
e2cd2337 YM	102
2dfe1b83 YM	103	ifeq ($(6)-$$(GENDOC_XSLTPROC_IS_BROKEN),pdf-y)
	104	$$(O)/docs/$(1)/$(1).$(6):
	105	$$(warning PDF generation is disabled because of a bug in \
	106	xsltproc. To be able to generate a PDF, you should \
	107	build xsltproc from the libxslt sources >=1.1.29 and pass it \
	108	to make through the command line: \
	109	'PATH=/path/to/custom-xsltproc/bin:$$$${PATH} make $(1)-pdf')
	110	else
	111	# -r $(@D) is there for documents that use external filters; those filters
	112	# generate code at the same location it finds the document's source files.
	113	$$(O)/docs/$(1)/$(1).$(6): $$($(2)_SOURCES) \
	114	$(1)-check-dependencies \
	115	$(1)-check-dependencies-$(5) \
	116	$(1)-prepare-sources
	117	$$(Q)$$(call MESSAGE,"Generating $(7) $(1)...")
	118	$$(Q)mkdir -p $$(@D)
	119	$$(Q)a2x $(8) -f $(4) -d book -L \
9d4a1a78 AS	120	$$(foreach r,$$($(2)_RESOURCES) $$(@D), \
9d4a1a78 AS	121	--resource="$$(abspath $$(r))") \
2dfe1b83 YM	122	$$($(2)_$(4)_A2X_OPTS) \
	123	--asciidoc-opts="$$($(2)_$(4)_ASCIIDOC_OPTS)" \
	124	$$(BUILD_DIR)/docs/$(1)/$(1).txt
	125	# install the generated document
	126	$$($(2)_$(4)_INSTALL_CMDS)
	127	endif
	128	endef
	129
	130	################################################################################
ab6a6212	131	# ASCIIDOC -- generates the make targets needed to build asciidoc documentation.
2dfe1b83	132	#
13f5f02e YM	133	# argument 1 is the lowercase name of the document; the document's main file
	134	# must have the same name, with the .txt extension
	135	# argument 2 is the uppercase name of the document
	136	# argument 3 is the directory containing the document's sources
	137	#
2dfe1b83 YM	138	# The variable <DOCUMENT_NAME>_SOURCES defines the dependencies.
	139	# The variable <DOCUMENT_NAME>_RESOURCES defines where the document's
	140	# resources, such as images, are located; must be an absolute path.
	141	################################################################################
ab6a6212	142	define ASCIIDOC
2dfe1b83	143	# Single line, because splitting a foreach is not easy...
3c695928	144	$(1)-check-dependencies: asciidoc-check-dependencies $$($(2)_DEPENDENCIES)
13f5f02e	145	$$(Q)$$(foreach hook,$$($(2)_CHECK_DEPENDENCIES_HOOKS),$$(call $$(hook))$$(sep))
2dfe1b83	146
2dfe1b83	147	# Single line, because splitting a foreach is not easy...
3d2a49f7 YM	148	# Do not touch the stamp file, so we get to rsync again every time we build
	149	# the document.
	150	$$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced:
13f5f02e	151	$$(Q)$$(call MESSAGE,"Preparing the $(1) sources...")
3d2a49f7 YM	152	$$(Q)mkdir -p $$(@D)
3d2a49f7 YM	153	$$(Q)rsync -a $(3) $$(@D)
13f5f02e	154	$$(Q)$$(foreach hook,$$($(2)_POST_RSYNC_HOOKS),$$(call $$(hook))$$(sep))
2dfe1b83	155
3d2a49f7	156	$(1)-prepare-sources: $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced
2dfe1b83	157
3c40c9ee YM	158	$(2)_ASCIIDOC_CONF = $(3)/asciidoc.conf
3c40c9ee YM	159
13f5f02e	160	$(call ASCIIDOC_INNER,$(1),$(2),$(3),xhtml,html,html,HTML,\
2dfe1b83 YM	161	--xsltproc-opts "--stringparam toc.section.depth 1")
2dfe1b83 YM	162
13f5f02e	163	$(call ASCIIDOC_INNER,$(1),$(2),$(3),chunked,split-html,chunked,split HTML,\
2dfe1b83 YM	164	--xsltproc-opts "--stringparam toc.section.depth 1")
	165
	166	# dblatex needs to pass the '--maxvars ...' option to xsltproc to prevent it
	167	# from reaching the template recursion limit when processing the (long) target
	168	# package table and bailing out.
13f5f02e	169	$(call ASCIIDOC_INNER,$(1),$(2),$(3),pdf,pdf,pdf,PDF,\
2dfe1b83 YM	170	--dblatex-opts "-P latex.output.revhistory=0 -x '--maxvars 100000'")
2dfe1b83 YM	171
13f5f02e	172	$(call ASCIIDOC_INNER,$(1),$(2),$(3),text,text,text,text)
2dfe1b83	173
13f5f02e	174	$(call ASCIIDOC_INNER,$(1),$(2),$(3),epub,epub,epub,ePUB)
2dfe1b83	175
13f5f02e YM	176	clean: $(1)-clean
	177	$(1)-clean:
	178	$$(Q)$$(RM) -rf $$(BUILD_DIR)/docs/$(1)
	179	.PHONY: $(1) $(1)-clean
2dfe1b83	180	endef
ab6a6212 YM	181
	182	################################################################################
	183	# asciidoc-document -- the target generator macro for asciidoc documents
	184	################################################################################
	185
13f5f02e	186	asciidoc-document = $(call ASCIIDOC,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir))