2014-10-03 19:01:51 +02:00
|
|
|
# we can't use suitable-host-package here because that's not available in
|
|
|
|
|
# the context of 'make release'
|
2017-06-15 00:11:33 +02:00
|
|
|
.PHONY: asciidoc-check-dependencies
|
2014-10-03 19:01:52 +02:00
|
|
|
asciidoc-check-dependencies:
|
2014-10-03 19:01:51 +02:00
|
|
|
$(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
|
|
|
|
|
|
2014-10-03 19:01:52 +02:00
|
|
|
asciidoc-check-dependencies-pdf:
|
2014-10-03 19:01:51 +02:00
|
|
|
$(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)
|
|
|
|
|
|
doc/asciidoc: always apply Buildroot's AsciiDoc config
As suggested by Thomas: the AsciiDoc options we use ensure we get a sane
output of the document. We want that configuration to be applied to
other documents as well.
Up until now, it was implicit that the configuration was applied to
our manual, becasue we only supported document-specific configuration,
and the configuration we had was in our manual dir, so we got to use it.
But now, we can render other documents, especially ones from
br2-external, and we want those to also use the default configuration
from Buildroot, but still be able to provide their own customisation.
So, always add Buildroot's configuration first, if available, before we
append the document's configuration.
Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Reviewed-by: Samuel Martin <s.martin49@gmail.com>
Reviewed-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-10-03 19:01:56 +02:00
|
|
|
# Apply this configuration to all documents
|
|
|
|
|
BR_ASCIIDOC_CONF = docs/conf/asciidoc.conf
|
|
|
|
|
|
2014-10-03 19:01:51 +02:00
|
|
|
################################################################################
|
2014-10-03 19:01:52 +02:00
|
|
|
# ASCIIDOC_INNER -- generates the make targets needed to build a specific type of
|
|
|
|
|
# asciidoc documentation.
|
2014-10-03 19:01:51 +02:00
|
|
|
#
|
|
|
|
|
# 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
|
package/doc-asciidoc: fix build for out-of-tree documents
The doc-asciidoc infra allows document to define sources and resources,
and those can only be local (there is no download support for documents).
The currently documented way to specify those is to use the $(pkgdir)
macro to point to the document sources and resources when they are along
the .mk.
However, this works only for sources and not for resources.
Indeed, sources are used to generate Makefile dependency rules, so
$(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc),
while resources are expanded and evaluated when the rules are executed,
which always happen after all the parsing has be done, at which point
$(pkgdir) expands to the last Makefile that was parsed, which is always
Buildroot's own manual.
This went unnoticed so far because Buildroot's manual is 1) the last to
be parsed, and 2) not using $(pkgdir) anyway.
Additionally, $(pkgdir) is mostly an internal macro, that is, as this
change demonstrates, difficult to use, and thus should not be used, in
packages or in documents.
We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR),
which points to the document directory. We choose not to name the
variable FOO_PKGDIR, because it semantically is not a package.
As a consequence, the last argument to the doc-asciidoc macro is now
superfluous, so it is removed, which causes a little bit of churn in
the main macro. As a further consequence, the third argument in the
inner macro is no longer needed either, so it too is removed, which
causes a bit more churn yet in the inner macro.
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Cc: Frederic GARDES <frederic.gardes@orange.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
2022-02-01 14:49:44 +01:00
|
|
|
# argument 3 is the type of document to generate (-f argument of a2x)
|
|
|
|
|
# argument 4 is the document type as used in the make target
|
|
|
|
|
# argument 5 is the output file extension for the document type
|
|
|
|
|
# argument 6 is the human text for the document type
|
|
|
|
|
# argument 7 (optional) are extra arguments for a2x
|
2014-10-03 19:01:51 +02:00
|
|
|
#
|
|
|
|
|
# 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.
|
|
|
|
|
################################################################################
|
2014-10-03 19:01:52 +02:00
|
|
|
define ASCIIDOC_INNER
|
package/doc-asciidoc: fix build for out-of-tree documents
The doc-asciidoc infra allows document to define sources and resources,
and those can only be local (there is no download support for documents).
The currently documented way to specify those is to use the $(pkgdir)
macro to point to the document sources and resources when they are along
the .mk.
However, this works only for sources and not for resources.
Indeed, sources are used to generate Makefile dependency rules, so
$(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc),
while resources are expanded and evaluated when the rules are executed,
which always happen after all the parsing has be done, at which point
$(pkgdir) expands to the last Makefile that was parsed, which is always
Buildroot's own manual.
This went unnoticed so far because Buildroot's manual is 1) the last to
be parsed, and 2) not using $(pkgdir) anyway.
Additionally, $(pkgdir) is mostly an internal macro, that is, as this
change demonstrates, difficult to use, and thus should not be used, in
packages or in documents.
We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR),
which points to the document directory. We choose not to name the
variable FOO_PKGDIR, because it semantically is not a package.
As a consequence, the last argument to the doc-asciidoc macro is now
superfluous, so it is removed, which causes a little bit of churn in
the main macro. As a further consequence, the third argument in the
inner macro is no longer needed either, so it too is removed, which
causes a bit more churn yet in the inner macro.
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Cc: Frederic GARDES <frederic.gardes@orange.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
2022-02-01 14:49:44 +01:00
|
|
|
$(1): $(1)-$(4)
|
|
|
|
|
.PHONY: $(1)-$(4)
|
|
|
|
|
$(1)-$(4): $$(O)/docs/$(1)/$(1).$(5)
|
2014-10-03 19:01:51 +02:00
|
|
|
|
package/doc-asciidoc: fix build for out-of-tree documents
The doc-asciidoc infra allows document to define sources and resources,
and those can only be local (there is no download support for documents).
The currently documented way to specify those is to use the $(pkgdir)
macro to point to the document sources and resources when they are along
the .mk.
However, this works only for sources and not for resources.
Indeed, sources are used to generate Makefile dependency rules, so
$(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc),
while resources are expanded and evaluated when the rules are executed,
which always happen after all the parsing has be done, at which point
$(pkgdir) expands to the last Makefile that was parsed, which is always
Buildroot's own manual.
This went unnoticed so far because Buildroot's manual is 1) the last to
be parsed, and 2) not using $(pkgdir) anyway.
Additionally, $(pkgdir) is mostly an internal macro, that is, as this
change demonstrates, difficult to use, and thus should not be used, in
packages or in documents.
We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR),
which points to the document directory. We choose not to name the
variable FOO_PKGDIR, because it semantically is not a package.
As a consequence, the last argument to the doc-asciidoc macro is now
superfluous, so it is removed, which causes a little bit of churn in
the main macro. As a further consequence, the third argument in the
inner macro is no longer needed either, so it too is removed, which
causes a bit more churn yet in the inner macro.
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Cc: Frederic GARDES <frederic.gardes@orange.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
2022-02-01 14:49:44 +01:00
|
|
|
asciidoc-check-dependencies-$(4):
|
|
|
|
|
.PHONY: $(1)-check-dependencies-$(4)
|
2017-06-15 00:11:33 +02:00
|
|
|
# Single line, because splitting a foreach is not easy...
|
package/doc-asciidoc: fix build for out-of-tree documents
The doc-asciidoc infra allows document to define sources and resources,
and those can only be local (there is no download support for documents).
The currently documented way to specify those is to use the $(pkgdir)
macro to point to the document sources and resources when they are along
the .mk.
However, this works only for sources and not for resources.
Indeed, sources are used to generate Makefile dependency rules, so
$(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc),
while resources are expanded and evaluated when the rules are executed,
which always happen after all the parsing has be done, at which point
$(pkgdir) expands to the last Makefile that was parsed, which is always
Buildroot's own manual.
This went unnoticed so far because Buildroot's manual is 1) the last to
be parsed, and 2) not using $(pkgdir) anyway.
Additionally, $(pkgdir) is mostly an internal macro, that is, as this
change demonstrates, difficult to use, and thus should not be used, in
packages or in documents.
We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR),
which points to the document directory. We choose not to name the
variable FOO_PKGDIR, because it semantically is not a package.
As a consequence, the last argument to the doc-asciidoc macro is now
superfluous, so it is removed, which causes a little bit of churn in
the main macro. As a further consequence, the third argument in the
inner macro is no longer needed either, so it too is removed, which
causes a bit more churn yet in the inner macro.
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Cc: Frederic GARDES <frederic.gardes@orange.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
2022-02-01 14:49:44 +01:00
|
|
|
$(1)-check-dependencies-$(4): asciidoc-check-dependencies-$(4)
|
|
|
|
|
$$(Q)$$(foreach hook,$$($(2)_CHECK_DEPENDENCIES_$$(call UPPERCASE,$(4))_HOOKS),$$(call $$(hook))$$(sep))
|
2014-10-03 19:01:51 +02:00
|
|
|
|
doc/asciidoc: always apply Buildroot's AsciiDoc config
As suggested by Thomas: the AsciiDoc options we use ensure we get a sane
output of the document. We want that configuration to be applied to
other documents as well.
Up until now, it was implicit that the configuration was applied to
our manual, becasue we only supported document-specific configuration,
and the configuration we had was in our manual dir, so we got to use it.
But now, we can render other documents, especially ones from
br2-external, and we want those to also use the default configuration
from Buildroot, but still be able to provide their own customisation.
So, always add Buildroot's configuration first, if available, before we
append the document's configuration.
Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Reviewed-by: Samuel Martin <s.martin49@gmail.com>
Reviewed-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-10-03 19:01:56 +02:00
|
|
|
# Include Buildroot's AsciiDoc configuration first:
|
|
|
|
|
# - generic configuration,
|
|
|
|
|
# - then output-specific configuration
|
|
|
|
|
ifneq ($$(wildcard $$(BR_ASCIIDOC_CONF)),)
|
package/doc-asciidoc: fix build for out-of-tree documents
The doc-asciidoc infra allows document to define sources and resources,
and those can only be local (there is no download support for documents).
The currently documented way to specify those is to use the $(pkgdir)
macro to point to the document sources and resources when they are along
the .mk.
However, this works only for sources and not for resources.
Indeed, sources are used to generate Makefile dependency rules, so
$(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc),
while resources are expanded and evaluated when the rules are executed,
which always happen after all the parsing has be done, at which point
$(pkgdir) expands to the last Makefile that was parsed, which is always
Buildroot's own manual.
This went unnoticed so far because Buildroot's manual is 1) the last to
be parsed, and 2) not using $(pkgdir) anyway.
Additionally, $(pkgdir) is mostly an internal macro, that is, as this
change demonstrates, difficult to use, and thus should not be used, in
packages or in documents.
We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR),
which points to the document directory. We choose not to name the
variable FOO_PKGDIR, because it semantically is not a package.
As a consequence, the last argument to the doc-asciidoc macro is now
superfluous, so it is removed, which causes a little bit of churn in
the main macro. As a further consequence, the third argument in the
inner macro is no longer needed either, so it too is removed, which
causes a bit more churn yet in the inner macro.
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Cc: Frederic GARDES <frederic.gardes@orange.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
2022-02-01 14:49:44 +01:00
|
|
|
$(2)_$(3)_ASCIIDOC_OPTS += -f $$(BR_ASCIIDOC_CONF)
|
doc/asciidoc: always apply Buildroot's AsciiDoc config
As suggested by Thomas: the AsciiDoc options we use ensure we get a sane
output of the document. We want that configuration to be applied to
other documents as well.
Up until now, it was implicit that the configuration was applied to
our manual, becasue we only supported document-specific configuration,
and the configuration we had was in our manual dir, so we got to use it.
But now, we can render other documents, especially ones from
br2-external, and we want those to also use the default configuration
from Buildroot, but still be able to provide their own customisation.
So, always add Buildroot's configuration first, if available, before we
append the document's configuration.
Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Reviewed-by: Samuel Martin <s.martin49@gmail.com>
Reviewed-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-10-03 19:01:56 +02:00
|
|
|
endif
|
package/doc-asciidoc: fix build for out-of-tree documents
The doc-asciidoc infra allows document to define sources and resources,
and those can only be local (there is no download support for documents).
The currently documented way to specify those is to use the $(pkgdir)
macro to point to the document sources and resources when they are along
the .mk.
However, this works only for sources and not for resources.
Indeed, sources are used to generate Makefile dependency rules, so
$(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc),
while resources are expanded and evaluated when the rules are executed,
which always happen after all the parsing has be done, at which point
$(pkgdir) expands to the last Makefile that was parsed, which is always
Buildroot's own manual.
This went unnoticed so far because Buildroot's manual is 1) the last to
be parsed, and 2) not using $(pkgdir) anyway.
Additionally, $(pkgdir) is mostly an internal macro, that is, as this
change demonstrates, difficult to use, and thus should not be used, in
packages or in documents.
We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR),
which points to the document directory. We choose not to name the
variable FOO_PKGDIR, because it semantically is not a package.
As a consequence, the last argument to the doc-asciidoc macro is now
superfluous, so it is removed, which causes a little bit of churn in
the main macro. As a further consequence, the third argument in the
inner macro is no longer needed either, so it too is removed, which
causes a bit more churn yet in the inner macro.
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Cc: Frederic GARDES <frederic.gardes@orange.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
2022-02-01 14:49:44 +01:00
|
|
|
BR_$(3)_ASCIIDOC_CONF = docs/conf/asciidoc-$(3).conf
|
|
|
|
|
ifneq ($$(wildcard $$(BR_$(3)_ASCIIDOC_CONF)),)
|
|
|
|
|
$(2)_$(3)_ASCIIDOC_OPTS += -f $$(BR_$(3)_ASCIIDOC_CONF)
|
doc/asciidoc: always apply Buildroot's AsciiDoc config
As suggested by Thomas: the AsciiDoc options we use ensure we get a sane
output of the document. We want that configuration to be applied to
other documents as well.
Up until now, it was implicit that the configuration was applied to
our manual, becasue we only supported document-specific configuration,
and the configuration we had was in our manual dir, so we got to use it.
But now, we can render other documents, especially ones from
br2-external, and we want those to also use the default configuration
from Buildroot, but still be able to provide their own customisation.
So, always add Buildroot's configuration first, if available, before we
append the document's configuration.
Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Reviewed-by: Samuel Martin <s.martin49@gmail.com>
Reviewed-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-10-03 19:01:56 +02:00
|
|
|
endif
|
|
|
|
|
|
|
|
|
|
# Then include the document's AsciiDoc configuration:
|
|
|
|
|
# - generic configuration,
|
|
|
|
|
# - then output-specific configuration
|
2014-10-03 19:01:55 +02:00
|
|
|
ifneq ($$(wildcard $$($(2)_ASCIIDOC_CONF)),)
|
package/doc-asciidoc: fix build for out-of-tree documents
The doc-asciidoc infra allows document to define sources and resources,
and those can only be local (there is no download support for documents).
The currently documented way to specify those is to use the $(pkgdir)
macro to point to the document sources and resources when they are along
the .mk.
However, this works only for sources and not for resources.
Indeed, sources are used to generate Makefile dependency rules, so
$(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc),
while resources are expanded and evaluated when the rules are executed,
which always happen after all the parsing has be done, at which point
$(pkgdir) expands to the last Makefile that was parsed, which is always
Buildroot's own manual.
This went unnoticed so far because Buildroot's manual is 1) the last to
be parsed, and 2) not using $(pkgdir) anyway.
Additionally, $(pkgdir) is mostly an internal macro, that is, as this
change demonstrates, difficult to use, and thus should not be used, in
packages or in documents.
We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR),
which points to the document directory. We choose not to name the
variable FOO_PKGDIR, because it semantically is not a package.
As a consequence, the last argument to the doc-asciidoc macro is now
superfluous, so it is removed, which causes a little bit of churn in
the main macro. As a further consequence, the third argument in the
inner macro is no longer needed either, so it too is removed, which
causes a bit more churn yet in the inner macro.
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Cc: Frederic GARDES <frederic.gardes@orange.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
2022-02-01 14:49:44 +01:00
|
|
|
$(2)_$(3)_ASCIIDOC_OPTS += -f $$($(2)_ASCIIDOC_CONF)
|
2014-10-03 19:01:55 +02:00
|
|
|
endif
|
package/doc-asciidoc: fix build for out-of-tree documents
The doc-asciidoc infra allows document to define sources and resources,
and those can only be local (there is no download support for documents).
The currently documented way to specify those is to use the $(pkgdir)
macro to point to the document sources and resources when they are along
the .mk.
However, this works only for sources and not for resources.
Indeed, sources are used to generate Makefile dependency rules, so
$(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc),
while resources are expanded and evaluated when the rules are executed,
which always happen after all the parsing has be done, at which point
$(pkgdir) expands to the last Makefile that was parsed, which is always
Buildroot's own manual.
This went unnoticed so far because Buildroot's manual is 1) the last to
be parsed, and 2) not using $(pkgdir) anyway.
Additionally, $(pkgdir) is mostly an internal macro, that is, as this
change demonstrates, difficult to use, and thus should not be used, in
packages or in documents.
We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR),
which points to the document directory. We choose not to name the
variable FOO_PKGDIR, because it semantically is not a package.
As a consequence, the last argument to the doc-asciidoc macro is now
superfluous, so it is removed, which causes a little bit of churn in
the main macro. As a further consequence, the third argument in the
inner macro is no longer needed either, so it too is removed, which
causes a bit more churn yet in the inner macro.
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Cc: Frederic GARDES <frederic.gardes@orange.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
2022-02-01 14:49:44 +01:00
|
|
|
$(2)_$(3)_ASCIIDOC_CONF = $$($(2)_DOCDIR)/asciidoc-$(3).conf
|
|
|
|
|
ifneq ($$(wildcard $$($(2)_$(3)_ASCIIDOC_CONF)),)
|
|
|
|
|
$(2)_$(3)_ASCIIDOC_OPTS += -f $$($(2)_$(3)_ASCIIDOC_CONF)
|
2014-10-03 19:01:51 +02:00
|
|
|
endif
|
|
|
|
|
|
package/doc-asciidoc: specify TOC depth for all formats
Commit 17feaf00160d (manual: set toc depth to 4 for html outputs) did
not explain why it set the depth of the table of content (TOC) only for
the html and split-html formats.
From memory, but it is a bit fuzzy after all those years, the TOC for
HTML documentation was by default deeper than for the other formats, so
it was really useless to expand it more than one-level deep, while for
other formats, the default was acceptable.
However, it does not make much sense to limit/enforce the depth of the
TOC only for specific formats, and keep the default for the others;
indeed, there is nothing that prevents the default to change with
various versions of asciidoc and the rendering backends.
Render all the formats with the same, explicit level of TOC.
We move the assignment of _A2X_OPTS above the comment, because the
comment does not apply to the TOC setting. Also note that the previous
assignment to an empty value was completely superfluous...
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Signed-off-by: Arnout Vandecappelle <arnout@mind.be>
2023-01-18 08:14:10 +01:00
|
|
|
$(2)_$(3)_A2X_OPTS = \
|
package/doc-asciidoc: allow docs to request a specific TOC depth
For some documents, we may want a terse or deeper TOC depth. For
example, short documents may want just the level-0 in the TOC, while
longer documents may want depth 1 or 2, or even deeper; also, some
documents may not use the document-title levels [0], only section
levels [1], and so may want to increase the TOC depth.
Additionally, allow per-format depth. For example, split-html has a
single page dedicated to the TOC, so there we may want a deeper TOC,
while on the html output, where the TOC is on the same page as the
whole document, a shorter TOC is preferred.
[0] https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#document-header
[1] https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#section-titles
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Signed-off-by: Arnout Vandecappelle <arnout@mind.be>
2023-01-18 08:14:11 +01:00
|
|
|
--xsltproc-opts "--stringparam toc.section.depth $$(or $$($(2)_TOC_DEPTH_$$(call UPPERCASE,$(4))),$$($(2)_TOC_DEPTH))"
|
package/doc-asciidoc: specify TOC depth for all formats
Commit 17feaf00160d (manual: set toc depth to 4 for html outputs) did
not explain why it set the depth of the table of content (TOC) only for
the html and split-html formats.
From memory, but it is a bit fuzzy after all those years, the TOC for
HTML documentation was by default deeper than for the other formats, so
it was really useless to expand it more than one-level deep, while for
other formats, the default was acceptable.
However, it does not make much sense to limit/enforce the depth of the
TOC only for specific formats, and keep the default for the others;
indeed, there is nothing that prevents the default to change with
various versions of asciidoc and the rendering backends.
Render all the formats with the same, explicit level of TOC.
We move the assignment of _A2X_OPTS above the comment, because the
comment does not apply to the TOC setting. Also note that the previous
assignment to an empty value was completely superfluous...
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Signed-off-by: Arnout Vandecappelle <arnout@mind.be>
2023-01-18 08:14:10 +01:00
|
|
|
|
2014-10-03 19:01:51 +02:00
|
|
|
# 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
|
package/doc-asciidoc: fix build for out-of-tree documents
The doc-asciidoc infra allows document to define sources and resources,
and those can only be local (there is no download support for documents).
The currently documented way to specify those is to use the $(pkgdir)
macro to point to the document sources and resources when they are along
the .mk.
However, this works only for sources and not for resources.
Indeed, sources are used to generate Makefile dependency rules, so
$(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc),
while resources are expanded and evaluated when the rules are executed,
which always happen after all the parsing has be done, at which point
$(pkgdir) expands to the last Makefile that was parsed, which is always
Buildroot's own manual.
This went unnoticed so far because Buildroot's manual is 1) the last to
be parsed, and 2) not using $(pkgdir) anyway.
Additionally, $(pkgdir) is mostly an internal macro, that is, as this
change demonstrates, difficult to use, and thus should not be used, in
packages or in documents.
We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR),
which points to the document directory. We choose not to name the
variable FOO_PKGDIR, because it semantically is not a package.
As a consequence, the last argument to the doc-asciidoc macro is now
superfluous, so it is removed, which causes a little bit of churn in
the main macro. As a further consequence, the third argument in the
inner macro is no longer needed either, so it too is removed, which
causes a bit more churn yet in the inner macro.
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Cc: Frederic GARDES <frederic.gardes@orange.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
2022-02-01 14:49:44 +01:00
|
|
|
ifneq ($$(filter $(4),html split-html),)
|
|
|
|
|
$(2)_$(3)_A2X_OPTS += --destination-dir="$$(@D)"
|
2014-10-03 19:01:51 +02:00
|
|
|
else
|
package/doc-asciidoc: fix build for out-of-tree documents
The doc-asciidoc infra allows document to define sources and resources,
and those can only be local (there is no download support for documents).
The currently documented way to specify those is to use the $(pkgdir)
macro to point to the document sources and resources when they are along
the .mk.
However, this works only for sources and not for resources.
Indeed, sources are used to generate Makefile dependency rules, so
$(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc),
while resources are expanded and evaluated when the rules are executed,
which always happen after all the parsing has be done, at which point
$(pkgdir) expands to the last Makefile that was parsed, which is always
Buildroot's own manual.
This went unnoticed so far because Buildroot's manual is 1) the last to
be parsed, and 2) not using $(pkgdir) anyway.
Additionally, $(pkgdir) is mostly an internal macro, that is, as this
change demonstrates, difficult to use, and thus should not be used, in
packages or in documents.
We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR),
which points to the document directory. We choose not to name the
variable FOO_PKGDIR, because it semantically is not a package.
As a consequence, the last argument to the doc-asciidoc macro is now
superfluous, so it is removed, which causes a little bit of churn in
the main macro. As a further consequence, the third argument in the
inner macro is no longer needed either, so it too is removed, which
causes a bit more churn yet in the inner macro.
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Cc: Frederic GARDES <frederic.gardes@orange.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
2022-02-01 14:49:44 +01:00
|
|
|
define $(2)_$(3)_INSTALL_CMDS
|
|
|
|
|
$$(Q)cp -f $$(BUILD_DIR)/docs/$(1)/$(1).$(5) $$(@D)
|
2014-10-03 19:01:51 +02:00
|
|
|
endef
|
|
|
|
|
endif
|
|
|
|
|
|
package/doc-asciidoc: fix build for out-of-tree documents
The doc-asciidoc infra allows document to define sources and resources,
and those can only be local (there is no download support for documents).
The currently documented way to specify those is to use the $(pkgdir)
macro to point to the document sources and resources when they are along
the .mk.
However, this works only for sources and not for resources.
Indeed, sources are used to generate Makefile dependency rules, so
$(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc),
while resources are expanded and evaluated when the rules are executed,
which always happen after all the parsing has be done, at which point
$(pkgdir) expands to the last Makefile that was parsed, which is always
Buildroot's own manual.
This went unnoticed so far because Buildroot's manual is 1) the last to
be parsed, and 2) not using $(pkgdir) anyway.
Additionally, $(pkgdir) is mostly an internal macro, that is, as this
change demonstrates, difficult to use, and thus should not be used, in
packages or in documents.
We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR),
which points to the document directory. We choose not to name the
variable FOO_PKGDIR, because it semantically is not a package.
As a consequence, the last argument to the doc-asciidoc macro is now
superfluous, so it is removed, which causes a little bit of churn in
the main macro. As a further consequence, the third argument in the
inner macro is no longer needed either, so it too is removed, which
causes a bit more churn yet in the inner macro.
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Cc: Frederic GARDES <frederic.gardes@orange.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
2022-02-01 14:49:44 +01:00
|
|
|
$$(O)/docs/$(1)/$(1).$(5): export TZ=UTC
|
doc/asciidoc: always use UTC
Currently, the manual is rendered with the timezone of the user running
the rendering. This timezone can fluctuate, depending on the date, due
to DST (Daylight Saving Time). Currently, the manual is rendered in
either CET or CEST (Central European Time, or its DST variant.)
So, a manual rendered during the summer or the winter would refer to a
non-constant timezone. If the machine and/or user doing the rendering
also changes, there is no guarantee the timezone would still be CET/CEST.
This is not a hard issue, since the user can still deduce the time in
UTC, but is just incoherent.
Just force the timezone to be UTC when doing the rendering of the
manual, so we are not dependent on the machine or user doing the
rendering.
Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Reviewed-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-10-03 19:01:57 +02:00
|
|
|
|
package/doc-asciidoc: fix build for out-of-tree documents
The doc-asciidoc infra allows document to define sources and resources,
and those can only be local (there is no download support for documents).
The currently documented way to specify those is to use the $(pkgdir)
macro to point to the document sources and resources when they are along
the .mk.
However, this works only for sources and not for resources.
Indeed, sources are used to generate Makefile dependency rules, so
$(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc),
while resources are expanded and evaluated when the rules are executed,
which always happen after all the parsing has be done, at which point
$(pkgdir) expands to the last Makefile that was parsed, which is always
Buildroot's own manual.
This went unnoticed so far because Buildroot's manual is 1) the last to
be parsed, and 2) not using $(pkgdir) anyway.
Additionally, $(pkgdir) is mostly an internal macro, that is, as this
change demonstrates, difficult to use, and thus should not be used, in
packages or in documents.
We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR),
which points to the document directory. We choose not to name the
variable FOO_PKGDIR, because it semantically is not a package.
As a consequence, the last argument to the doc-asciidoc macro is now
superfluous, so it is removed, which causes a little bit of churn in
the main macro. As a further consequence, the third argument in the
inner macro is no longer needed either, so it too is removed, which
causes a bit more churn yet in the inner macro.
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Cc: Frederic GARDES <frederic.gardes@orange.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
2022-02-01 14:49:44 +01:00
|
|
|
ifeq ($(5)-$$(GENDOC_XSLTPROC_IS_BROKEN),pdf-y)
|
|
|
|
|
$$(O)/docs/$(1)/$(1).$(5):
|
2014-10-03 19:01:51 +02:00
|
|
|
$$(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.
|
package/doc-asciidoc: fix build for out-of-tree documents
The doc-asciidoc infra allows document to define sources and resources,
and those can only be local (there is no download support for documents).
The currently documented way to specify those is to use the $(pkgdir)
macro to point to the document sources and resources when they are along
the .mk.
However, this works only for sources and not for resources.
Indeed, sources are used to generate Makefile dependency rules, so
$(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc),
while resources are expanded and evaluated when the rules are executed,
which always happen after all the parsing has be done, at which point
$(pkgdir) expands to the last Makefile that was parsed, which is always
Buildroot's own manual.
This went unnoticed so far because Buildroot's manual is 1) the last to
be parsed, and 2) not using $(pkgdir) anyway.
Additionally, $(pkgdir) is mostly an internal macro, that is, as this
change demonstrates, difficult to use, and thus should not be used, in
packages or in documents.
We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR),
which points to the document directory. We choose not to name the
variable FOO_PKGDIR, because it semantically is not a package.
As a consequence, the last argument to the doc-asciidoc macro is now
superfluous, so it is removed, which causes a little bit of churn in
the main macro. As a further consequence, the third argument in the
inner macro is no longer needed either, so it too is removed, which
causes a bit more churn yet in the inner macro.
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Cc: Frederic GARDES <frederic.gardes@orange.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
2022-02-01 14:49:44 +01:00
|
|
|
$$(O)/docs/$(1)/$(1).$(5): $$($(2)_SOURCES) \
|
2014-10-03 19:01:51 +02:00
|
|
|
$(1)-check-dependencies \
|
package/doc-asciidoc: fix build for out-of-tree documents
The doc-asciidoc infra allows document to define sources and resources,
and those can only be local (there is no download support for documents).
The currently documented way to specify those is to use the $(pkgdir)
macro to point to the document sources and resources when they are along
the .mk.
However, this works only for sources and not for resources.
Indeed, sources are used to generate Makefile dependency rules, so
$(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc),
while resources are expanded and evaluated when the rules are executed,
which always happen after all the parsing has be done, at which point
$(pkgdir) expands to the last Makefile that was parsed, which is always
Buildroot's own manual.
This went unnoticed so far because Buildroot's manual is 1) the last to
be parsed, and 2) not using $(pkgdir) anyway.
Additionally, $(pkgdir) is mostly an internal macro, that is, as this
change demonstrates, difficult to use, and thus should not be used, in
packages or in documents.
We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR),
which points to the document directory. We choose not to name the
variable FOO_PKGDIR, because it semantically is not a package.
As a consequence, the last argument to the doc-asciidoc macro is now
superfluous, so it is removed, which causes a little bit of churn in
the main macro. As a further consequence, the third argument in the
inner macro is no longer needed either, so it too is removed, which
causes a bit more churn yet in the inner macro.
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Cc: Frederic GARDES <frederic.gardes@orange.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
2022-02-01 14:49:44 +01:00
|
|
|
$(1)-check-dependencies-$(4) \
|
2014-10-03 19:01:51 +02:00
|
|
|
$(1)-prepare-sources
|
package/doc-asciidoc: fix build for out-of-tree documents
The doc-asciidoc infra allows document to define sources and resources,
and those can only be local (there is no download support for documents).
The currently documented way to specify those is to use the $(pkgdir)
macro to point to the document sources and resources when they are along
the .mk.
However, this works only for sources and not for resources.
Indeed, sources are used to generate Makefile dependency rules, so
$(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc),
while resources are expanded and evaluated when the rules are executed,
which always happen after all the parsing has be done, at which point
$(pkgdir) expands to the last Makefile that was parsed, which is always
Buildroot's own manual.
This went unnoticed so far because Buildroot's manual is 1) the last to
be parsed, and 2) not using $(pkgdir) anyway.
Additionally, $(pkgdir) is mostly an internal macro, that is, as this
change demonstrates, difficult to use, and thus should not be used, in
packages or in documents.
We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR),
which points to the document directory. We choose not to name the
variable FOO_PKGDIR, because it semantically is not a package.
As a consequence, the last argument to the doc-asciidoc macro is now
superfluous, so it is removed, which causes a little bit of churn in
the main macro. As a further consequence, the third argument in the
inner macro is no longer needed either, so it too is removed, which
causes a bit more churn yet in the inner macro.
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Cc: Frederic GARDES <frederic.gardes@orange.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
2022-02-01 14:49:44 +01:00
|
|
|
$$(Q)$$(call MESSAGE,"Generating $(6) $(1)...")
|
2014-10-03 19:01:51 +02:00
|
|
|
$$(Q)mkdir -p $$(@D)
|
package/doc-asciidoc: fix build for out-of-tree documents
The doc-asciidoc infra allows document to define sources and resources,
and those can only be local (there is no download support for documents).
The currently documented way to specify those is to use the $(pkgdir)
macro to point to the document sources and resources when they are along
the .mk.
However, this works only for sources and not for resources.
Indeed, sources are used to generate Makefile dependency rules, so
$(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc),
while resources are expanded and evaluated when the rules are executed,
which always happen after all the parsing has be done, at which point
$(pkgdir) expands to the last Makefile that was parsed, which is always
Buildroot's own manual.
This went unnoticed so far because Buildroot's manual is 1) the last to
be parsed, and 2) not using $(pkgdir) anyway.
Additionally, $(pkgdir) is mostly an internal macro, that is, as this
change demonstrates, difficult to use, and thus should not be used, in
packages or in documents.
We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR),
which points to the document directory. We choose not to name the
variable FOO_PKGDIR, because it semantically is not a package.
As a consequence, the last argument to the doc-asciidoc macro is now
superfluous, so it is removed, which causes a little bit of churn in
the main macro. As a further consequence, the third argument in the
inner macro is no longer needed either, so it too is removed, which
causes a bit more churn yet in the inner macro.
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Cc: Frederic GARDES <frederic.gardes@orange.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
2022-02-01 14:49:44 +01:00
|
|
|
$$(Q)a2x $(7) -f $(3) -d book -L \
|
2016-07-27 20:02:48 +02:00
|
|
|
$$(foreach r,$$($(2)_RESOURCES) $$(@D), \
|
|
|
|
|
--resource="$$(abspath $$(r))") \
|
package/doc-asciidoc: fix build for out-of-tree documents
The doc-asciidoc infra allows document to define sources and resources,
and those can only be local (there is no download support for documents).
The currently documented way to specify those is to use the $(pkgdir)
macro to point to the document sources and resources when they are along
the .mk.
However, this works only for sources and not for resources.
Indeed, sources are used to generate Makefile dependency rules, so
$(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc),
while resources are expanded and evaluated when the rules are executed,
which always happen after all the parsing has be done, at which point
$(pkgdir) expands to the last Makefile that was parsed, which is always
Buildroot's own manual.
This went unnoticed so far because Buildroot's manual is 1) the last to
be parsed, and 2) not using $(pkgdir) anyway.
Additionally, $(pkgdir) is mostly an internal macro, that is, as this
change demonstrates, difficult to use, and thus should not be used, in
packages or in documents.
We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR),
which points to the document directory. We choose not to name the
variable FOO_PKGDIR, because it semantically is not a package.
As a consequence, the last argument to the doc-asciidoc macro is now
superfluous, so it is removed, which causes a little bit of churn in
the main macro. As a further consequence, the third argument in the
inner macro is no longer needed either, so it too is removed, which
causes a bit more churn yet in the inner macro.
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Cc: Frederic GARDES <frederic.gardes@orange.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
2022-02-01 14:49:44 +01:00
|
|
|
$$($(2)_$(3)_A2X_OPTS) \
|
|
|
|
|
--asciidoc-opts="$$($(2)_$(3)_ASCIIDOC_OPTS)" \
|
2023-03-14 19:58:05 +01:00
|
|
|
$$(BUILD_DIR)/docs/$(1)/$(1).adoc
|
2014-10-03 19:01:51 +02:00
|
|
|
# install the generated document
|
package/doc-asciidoc: fix build for out-of-tree documents
The doc-asciidoc infra allows document to define sources and resources,
and those can only be local (there is no download support for documents).
The currently documented way to specify those is to use the $(pkgdir)
macro to point to the document sources and resources when they are along
the .mk.
However, this works only for sources and not for resources.
Indeed, sources are used to generate Makefile dependency rules, so
$(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc),
while resources are expanded and evaluated when the rules are executed,
which always happen after all the parsing has be done, at which point
$(pkgdir) expands to the last Makefile that was parsed, which is always
Buildroot's own manual.
This went unnoticed so far because Buildroot's manual is 1) the last to
be parsed, and 2) not using $(pkgdir) anyway.
Additionally, $(pkgdir) is mostly an internal macro, that is, as this
change demonstrates, difficult to use, and thus should not be used, in
packages or in documents.
We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR),
which points to the document directory. We choose not to name the
variable FOO_PKGDIR, because it semantically is not a package.
As a consequence, the last argument to the doc-asciidoc macro is now
superfluous, so it is removed, which causes a little bit of churn in
the main macro. As a further consequence, the third argument in the
inner macro is no longer needed either, so it too is removed, which
causes a bit more churn yet in the inner macro.
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Cc: Frederic GARDES <frederic.gardes@orange.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
2022-02-01 14:49:44 +01:00
|
|
|
$$($(2)_$(3)_INSTALL_CMDS)
|
2014-10-03 19:01:51 +02:00
|
|
|
endif
|
|
|
|
|
endef
|
|
|
|
|
|
|
|
|
|
################################################################################
|
2014-10-03 19:01:52 +02:00
|
|
|
# ASCIIDOC -- generates the make targets needed to build asciidoc documentation.
|
2014-10-03 19:01:51 +02:00
|
|
|
#
|
2014-10-03 19:01:53 +02:00
|
|
|
# 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
|
|
|
|
|
#
|
2014-10-03 19:01:51 +02:00
|
|
|
# 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.
|
|
|
|
|
################################################################################
|
2014-10-03 19:01:52 +02:00
|
|
|
define ASCIIDOC
|
package/doc-asciidoc: fix build for out-of-tree documents
The doc-asciidoc infra allows document to define sources and resources,
and those can only be local (there is no download support for documents).
The currently documented way to specify those is to use the $(pkgdir)
macro to point to the document sources and resources when they are along
the .mk.
However, this works only for sources and not for resources.
Indeed, sources are used to generate Makefile dependency rules, so
$(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc),
while resources are expanded and evaluated when the rules are executed,
which always happen after all the parsing has be done, at which point
$(pkgdir) expands to the last Makefile that was parsed, which is always
Buildroot's own manual.
This went unnoticed so far because Buildroot's manual is 1) the last to
be parsed, and 2) not using $(pkgdir) anyway.
Additionally, $(pkgdir) is mostly an internal macro, that is, as this
change demonstrates, difficult to use, and thus should not be used, in
packages or in documents.
We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR),
which points to the document directory. We choose not to name the
variable FOO_PKGDIR, because it semantically is not a package.
As a consequence, the last argument to the doc-asciidoc macro is now
superfluous, so it is removed, which causes a little bit of churn in
the main macro. As a further consequence, the third argument in the
inner macro is no longer needed either, so it too is removed, which
causes a bit more churn yet in the inner macro.
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Cc: Frederic GARDES <frederic.gardes@orange.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
2022-02-01 14:49:44 +01:00
|
|
|
$(2)_DOCDIR = $(pkgdir)
|
|
|
|
|
|
2014-10-03 19:01:51 +02:00
|
|
|
# Single line, because splitting a foreach is not easy...
|
2017-06-15 00:11:33 +02:00
|
|
|
.PHONY: $(1)-check-dependencies
|
2016-07-17 12:34:23 +02:00
|
|
|
$(1)-check-dependencies: asciidoc-check-dependencies $$($(2)_DEPENDENCIES)
|
2014-10-03 19:01:53 +02:00
|
|
|
$$(Q)$$(foreach hook,$$($(2)_CHECK_DEPENDENCIES_HOOKS),$$(call $$(hook))$$(sep))
|
2014-10-03 19:01:51 +02:00
|
|
|
|
|
|
|
|
# Single line, because splitting a foreach is not easy...
|
2014-10-03 19:01:54 +02:00
|
|
|
# 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:
|
2014-10-03 19:01:53 +02:00
|
|
|
$$(Q)$$(call MESSAGE,"Preparing the $(1) sources...")
|
2014-10-03 19:01:54 +02:00
|
|
|
$$(Q)mkdir -p $$(@D)
|
package/doc-asciidoc: fix build for out-of-tree documents
The doc-asciidoc infra allows document to define sources and resources,
and those can only be local (there is no download support for documents).
The currently documented way to specify those is to use the $(pkgdir)
macro to point to the document sources and resources when they are along
the .mk.
However, this works only for sources and not for resources.
Indeed, sources are used to generate Makefile dependency rules, so
$(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc),
while resources are expanded and evaluated when the rules are executed,
which always happen after all the parsing has be done, at which point
$(pkgdir) expands to the last Makefile that was parsed, which is always
Buildroot's own manual.
This went unnoticed so far because Buildroot's manual is 1) the last to
be parsed, and 2) not using $(pkgdir) anyway.
Additionally, $(pkgdir) is mostly an internal macro, that is, as this
change demonstrates, difficult to use, and thus should not be used, in
packages or in documents.
We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR),
which points to the document directory. We choose not to name the
variable FOO_PKGDIR, because it semantically is not a package.
As a consequence, the last argument to the doc-asciidoc macro is now
superfluous, so it is removed, which causes a little bit of churn in
the main macro. As a further consequence, the third argument in the
inner macro is no longer needed either, so it too is removed, which
causes a bit more churn yet in the inner macro.
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Cc: Frederic GARDES <frederic.gardes@orange.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
2022-02-01 14:49:44 +01:00
|
|
|
$$(Q)rsync -a $$($(2)_DOCDIR) $$(@D)
|
2014-10-03 19:01:53 +02:00
|
|
|
$$(Q)$$(foreach hook,$$($(2)_POST_RSYNC_HOOKS),$$(call $$(hook))$$(sep))
|
2014-10-03 19:01:51 +02:00
|
|
|
|
2017-06-15 00:11:33 +02:00
|
|
|
.PHONY: $(1)-prepare-sources
|
2014-10-03 19:01:54 +02:00
|
|
|
$(1)-prepare-sources: $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced
|
2014-10-03 19:01:51 +02:00
|
|
|
|
package/doc-asciidoc: allow docs to request a specific TOC depth
For some documents, we may want a terse or deeper TOC depth. For
example, short documents may want just the level-0 in the TOC, while
longer documents may want depth 1 or 2, or even deeper; also, some
documents may not use the document-title levels [0], only section
levels [1], and so may want to increase the TOC depth.
Additionally, allow per-format depth. For example, split-html has a
single page dedicated to the TOC, so there we may want a deeper TOC,
while on the html output, where the TOC is on the same page as the
whole document, a shorter TOC is preferred.
[0] https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#document-header
[1] https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#section-titles
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Signed-off-by: Arnout Vandecappelle <arnout@mind.be>
2023-01-18 08:14:11 +01:00
|
|
|
$(2)_TOC_DEPTH ?= 1
|
package/doc-asciidoc: fix build for out-of-tree documents
The doc-asciidoc infra allows document to define sources and resources,
and those can only be local (there is no download support for documents).
The currently documented way to specify those is to use the $(pkgdir)
macro to point to the document sources and resources when they are along
the .mk.
However, this works only for sources and not for resources.
Indeed, sources are used to generate Makefile dependency rules, so
$(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc),
while resources are expanded and evaluated when the rules are executed,
which always happen after all the parsing has be done, at which point
$(pkgdir) expands to the last Makefile that was parsed, which is always
Buildroot's own manual.
This went unnoticed so far because Buildroot's manual is 1) the last to
be parsed, and 2) not using $(pkgdir) anyway.
Additionally, $(pkgdir) is mostly an internal macro, that is, as this
change demonstrates, difficult to use, and thus should not be used, in
packages or in documents.
We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR),
which points to the document directory. We choose not to name the
variable FOO_PKGDIR, because it semantically is not a package.
As a consequence, the last argument to the doc-asciidoc macro is now
superfluous, so it is removed, which causes a little bit of churn in
the main macro. As a further consequence, the third argument in the
inner macro is no longer needed either, so it too is removed, which
causes a bit more churn yet in the inner macro.
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Cc: Frederic GARDES <frederic.gardes@orange.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
2022-02-01 14:49:44 +01:00
|
|
|
$(2)_ASCIIDOC_CONF = $$($(2)_DOCDIR)/asciidoc.conf
|
2014-10-03 19:01:55 +02:00
|
|
|
|
package/doc-asciidoc: specify TOC depth for all formats
Commit 17feaf00160d (manual: set toc depth to 4 for html outputs) did
not explain why it set the depth of the table of content (TOC) only for
the html and split-html formats.
From memory, but it is a bit fuzzy after all those years, the TOC for
HTML documentation was by default deeper than for the other formats, so
it was really useless to expand it more than one-level deep, while for
other formats, the default was acceptable.
However, it does not make much sense to limit/enforce the depth of the
TOC only for specific formats, and keep the default for the others;
indeed, there is nothing that prevents the default to change with
various versions of asciidoc and the rendering backends.
Render all the formats with the same, explicit level of TOC.
We move the assignment of _A2X_OPTS above the comment, because the
comment does not apply to the TOC setting. Also note that the previous
assignment to an empty value was completely superfluous...
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Signed-off-by: Arnout Vandecappelle <arnout@mind.be>
2023-01-18 08:14:10 +01:00
|
|
|
$(call ASCIIDOC_INNER,$(1),$(2),xhtml,html,html,HTML)
|
2014-10-03 19:01:51 +02:00
|
|
|
|
package/doc-asciidoc: specify TOC depth for all formats
Commit 17feaf00160d (manual: set toc depth to 4 for html outputs) did
not explain why it set the depth of the table of content (TOC) only for
the html and split-html formats.
From memory, but it is a bit fuzzy after all those years, the TOC for
HTML documentation was by default deeper than for the other formats, so
it was really useless to expand it more than one-level deep, while for
other formats, the default was acceptable.
However, it does not make much sense to limit/enforce the depth of the
TOC only for specific formats, and keep the default for the others;
indeed, there is nothing that prevents the default to change with
various versions of asciidoc and the rendering backends.
Render all the formats with the same, explicit level of TOC.
We move the assignment of _A2X_OPTS above the comment, because the
comment does not apply to the TOC setting. Also note that the previous
assignment to an empty value was completely superfluous...
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Signed-off-by: Arnout Vandecappelle <arnout@mind.be>
2023-01-18 08:14:10 +01:00
|
|
|
$(call ASCIIDOC_INNER,$(1),$(2),chunked,split-html,chunked,split HTML)
|
2014-10-03 19:01:51 +02:00
|
|
|
|
|
|
|
|
# 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.
|
package/doc-asciidoc: fix build for out-of-tree documents
The doc-asciidoc infra allows document to define sources and resources,
and those can only be local (there is no download support for documents).
The currently documented way to specify those is to use the $(pkgdir)
macro to point to the document sources and resources when they are along
the .mk.
However, this works only for sources and not for resources.
Indeed, sources are used to generate Makefile dependency rules, so
$(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc),
while resources are expanded and evaluated when the rules are executed,
which always happen after all the parsing has be done, at which point
$(pkgdir) expands to the last Makefile that was parsed, which is always
Buildroot's own manual.
This went unnoticed so far because Buildroot's manual is 1) the last to
be parsed, and 2) not using $(pkgdir) anyway.
Additionally, $(pkgdir) is mostly an internal macro, that is, as this
change demonstrates, difficult to use, and thus should not be used, in
packages or in documents.
We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR),
which points to the document directory. We choose not to name the
variable FOO_PKGDIR, because it semantically is not a package.
As a consequence, the last argument to the doc-asciidoc macro is now
superfluous, so it is removed, which causes a little bit of churn in
the main macro. As a further consequence, the third argument in the
inner macro is no longer needed either, so it too is removed, which
causes a bit more churn yet in the inner macro.
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Cc: Frederic GARDES <frederic.gardes@orange.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
2022-02-01 14:49:44 +01:00
|
|
|
$(call ASCIIDOC_INNER,$(1),$(2),pdf,pdf,pdf,PDF,\
|
2014-10-03 19:01:51 +02:00
|
|
|
--dblatex-opts "-P latex.output.revhistory=0 -x '--maxvars 100000'")
|
|
|
|
|
|
package/doc-asciidoc: fix build for out-of-tree documents
The doc-asciidoc infra allows document to define sources and resources,
and those can only be local (there is no download support for documents).
The currently documented way to specify those is to use the $(pkgdir)
macro to point to the document sources and resources when they are along
the .mk.
However, this works only for sources and not for resources.
Indeed, sources are used to generate Makefile dependency rules, so
$(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc),
while resources are expanded and evaluated when the rules are executed,
which always happen after all the parsing has be done, at which point
$(pkgdir) expands to the last Makefile that was parsed, which is always
Buildroot's own manual.
This went unnoticed so far because Buildroot's manual is 1) the last to
be parsed, and 2) not using $(pkgdir) anyway.
Additionally, $(pkgdir) is mostly an internal macro, that is, as this
change demonstrates, difficult to use, and thus should not be used, in
packages or in documents.
We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR),
which points to the document directory. We choose not to name the
variable FOO_PKGDIR, because it semantically is not a package.
As a consequence, the last argument to the doc-asciidoc macro is now
superfluous, so it is removed, which causes a little bit of churn in
the main macro. As a further consequence, the third argument in the
inner macro is no longer needed either, so it too is removed, which
causes a bit more churn yet in the inner macro.
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Cc: Frederic GARDES <frederic.gardes@orange.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
2022-02-01 14:49:44 +01:00
|
|
|
$(call ASCIIDOC_INNER,$(1),$(2),text,text,text,text)
|
2014-10-03 19:01:51 +02:00
|
|
|
|
package/doc-asciidoc: fix build for out-of-tree documents
The doc-asciidoc infra allows document to define sources and resources,
and those can only be local (there is no download support for documents).
The currently documented way to specify those is to use the $(pkgdir)
macro to point to the document sources and resources when they are along
the .mk.
However, this works only for sources and not for resources.
Indeed, sources are used to generate Makefile dependency rules, so
$(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc),
while resources are expanded and evaluated when the rules are executed,
which always happen after all the parsing has be done, at which point
$(pkgdir) expands to the last Makefile that was parsed, which is always
Buildroot's own manual.
This went unnoticed so far because Buildroot's manual is 1) the last to
be parsed, and 2) not using $(pkgdir) anyway.
Additionally, $(pkgdir) is mostly an internal macro, that is, as this
change demonstrates, difficult to use, and thus should not be used, in
packages or in documents.
We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR),
which points to the document directory. We choose not to name the
variable FOO_PKGDIR, because it semantically is not a package.
As a consequence, the last argument to the doc-asciidoc macro is now
superfluous, so it is removed, which causes a little bit of churn in
the main macro. As a further consequence, the third argument in the
inner macro is no longer needed either, so it too is removed, which
causes a bit more churn yet in the inner macro.
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Cc: Frederic GARDES <frederic.gardes@orange.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
2022-02-01 14:49:44 +01:00
|
|
|
$(call ASCIIDOC_INNER,$(1),$(2),epub,epub,epub,ePUB)
|
2014-10-03 19:01:51 +02:00
|
|
|
|
2014-10-03 19:01:53 +02:00
|
|
|
clean: $(1)-clean
|
|
|
|
|
$(1)-clean:
|
|
|
|
|
$$(Q)$$(RM) -rf $$(BUILD_DIR)/docs/$(1)
|
|
|
|
|
.PHONY: $(1) $(1)-clean
|
2014-10-03 19:01:51 +02:00
|
|
|
endef
|
2014-10-03 19:01:52 +02:00
|
|
|
|
|
|
|
|
################################################################################
|
|
|
|
|
# asciidoc-document -- the target generator macro for asciidoc documents
|
|
|
|
|
################################################################################
|
|
|
|
|
|
package/doc-asciidoc: fix build for out-of-tree documents
The doc-asciidoc infra allows document to define sources and resources,
and those can only be local (there is no download support for documents).
The currently documented way to specify those is to use the $(pkgdir)
macro to point to the document sources and resources when they are along
the .mk.
However, this works only for sources and not for resources.
Indeed, sources are used to generate Makefile dependency rules, so
$(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc),
while resources are expanded and evaluated when the rules are executed,
which always happen after all the parsing has be done, at which point
$(pkgdir) expands to the last Makefile that was parsed, which is always
Buildroot's own manual.
This went unnoticed so far because Buildroot's manual is 1) the last to
be parsed, and 2) not using $(pkgdir) anyway.
Additionally, $(pkgdir) is mostly an internal macro, that is, as this
change demonstrates, difficult to use, and thus should not be used, in
packages or in documents.
We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR),
which points to the document directory. We choose not to name the
variable FOO_PKGDIR, because it semantically is not a package.
As a consequence, the last argument to the doc-asciidoc macro is now
superfluous, so it is removed, which causes a little bit of churn in
the main macro. As a further consequence, the third argument in the
inner macro is no longer needed either, so it too is removed, which
causes a bit more churn yet in the inner macro.
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Cc: Frederic GARDES <frederic.gardes@orange.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
2022-02-01 14:49:44 +01:00
|
|
|
asciidoc-document = $(call ASCIIDOC,$(pkgname),$(call UPPERCASE,$(pkgname)))
|
