gendoc infra: make it useable for other documents
Hello All!
This series builds up on top of Samuel previous series, and further enhances the GENDOC infrastructure to be useable to generate other documents, and especially documents in br2-external.
The series is articulated as thus:
- patches 1-3: from Samuel, virtually untouched by me, save for the location where the docs are built (patch 1), and the check for xsltproc (patch 3);
- patches 4-13: properly separate our manual defintion from the actual
infrastructure;
- patches 14-15: make the gendoc infra behave more like the pkg
infras, by using hooks rather than extra rules;
- patch 16: workaround asciidoc deficiency when calling filters;
- patches 17-18: move and rename 'gendoc' to 'doc-asciidoc';
- patches 19-20: further tweak the new infra so it looks more like other infras: only call pkgdir and pkgname from the frontend macro, and use stamp files so we can use $(@D);
- patches 21-22: add new locations where to get the AsciiDoc config
files;
- patch 23: always use UTC when generating the manual;
- patch 24: allow using doc-asciidoc from br2-external;
- patch 25: document this new infra in the manual.
Here is an example of using this new infra from a br2-external tree:
http://ymorin.is-a-geek.org/download/tmp/br.config/
http://ymorin.is-a-geek.org/download/tmp/br.config/brsh-manual.html
Changes v5 -> v6:
- change build location (Thomas P.)
- xsltproc check is a warniong only (Thomas DS.)
- do not use unnecessary $$(call)s (Thomas DS.)
- rename hooks (Thomas DS.)
- comment tricky code sections (Thomas DS.)
- more s/manual/document/ (Thomas DS., Samuel)
- typoes (Thomas DS., Samuel)
Changes v4 -> v5:
- cleanup the series
- make it posible to use $(@D) in hooks
- call post-extract hook in the same rule that does the rsync
- rename the extra check dependencies hooks, to look more like real hooks
- document the doc-asciidoc infra in the manual
Changes v3 -> v4:
- only run the xsltproc check once, not for every types of outputs
- add patches 5..18
Regards,
Yann E. MORIN.
The following changes since commit 6f5bffc426f7418c555291450d482a0ceede0865:
qemu-ppc: update kernel to latest for g3beige emulation (2014-09-27 09:53:12 +0200)
are available in the git repository at:
git://gitorious.org/buildroot/buildroot.git yem/manual
for you to fetch changes up to b0043d14369f4ce8fe60762c8b48c85a72a55894:
docs/manual: document the asciidoc infra (2014-09-27 12:15:17 +0200)
----------------------------------------------------------------
Samuel Martin (3):
gendoc infra: move manual build location into $(BUILD_DIR)/manual gendoc infra: avoid a2x warning
gendoc infra: disable pdf manual generation if xsltproc is buggy
Yann E. MORIN (22):
docs/manual: get rid of legacy comment in GENDOC docs/manual: copying the manual sources is a common action docs/manual: simplify generation dependencies docs/manual: manual-update-lists is not a generic GENDOC rule docs/manual: move manual-prepare-sources rule into GENDOC docs/manual: do not hardcode name of the generated document docs/manual: allow a document to declare where its resources are docs/manual: last pass at removing hard-coded path in GENDOC_INNER docs/manual: properly separate rules specific for our manual docs/manual: rename the generic dependency rules docs/manual: allow documents to define some hooks, as for a package docs/manual: use the new hooks instead of gendoc rules docs/manual: always look for resources in destination directory
docs: separate the GENDOC infra from our manual definition
docs: rename the GENDOC infrastructure
docs/asciidoc: call $(pkgname) and $(pkgdir) in a single place docs/asciidoc: make it possible to use $(@D) in hooks doc/asciidoc: allow documents to pass a global asciidoc configuration doc/asciidoc: always apply Buildroot's AsciiDoc config doc/asciidoc: always use UTC
Makefile: enable generating documents from br2-external docs/manual: document the asciidoc infra
Makefile | 2 +
docs/{manual => conf}/asciidoc-text.conf | 0
docs/manual/adding-packages-asciidoc.txt | 119 ++++++++++++++++++++
docs/manual/adding-packages.txt | 2 +
docs/manual/manual.mk | 105 +++---------------
package/doc-asciidoc.mk | 181 +++++++++++++++++++++++++++++++
6 files changed, 320 insertions(+), 89 deletions(-)
rename docs/{manual => conf}/asciidoc-text.conf (100%)
create mode 100644 docs/manual/adding-packages-asciidoc.txt
create mode 100644 package/doc-asciidoc.mkSignature · 6 lines
.-----------------.--------------------.------------------.--------------------. | Yann E. MORIN | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: | | +33 662 376 056 | Software Designer | \ / CAMPAIGN | ___ | | +33 223 225 172 `------------.-------: X AGAINST | \e/ There is no | | http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL | v conspiracy. | '------------------------------^-------^------------------^--------------------'
PATCH v6 1/25 gendoc infra: move manual build location into $(BUILD_DIR)/manual
From: Samuel Martin <[email protected]>
This patch reworks the manual source preparation by:
- moving the build directory under $(BUILD_DIR)/, this keeps consistency with the other Buildroot infrastructures;
- adding a couple of targets: 'manual-rsync' and 'manual-prepare-sources', to deal more efficiently with the manual sources and avoid rsync-ing them on every single manual-* target.
The 'manual-rsync' target only copies the manual sources under git, while the 'manual-prepare-sources' also takes care of the generated ones. These targets are now run only once, and the manual build is no longer cleaned after each manual format generation.
Now, the 'manual-clean' target only remove the manual build directory, but keeps the output one $(O)/output/doc/manual unchanged.
Doing so (moving the manual build directory and keeping it between 2 manual format generation) ensures that all generated sources are taken in account when generating the manual [1].
[1] http://lists.busybox.net/pipermail/buildroot/2014-August/104421.html
[yann.morin.1998 at free.fr: moved into $(BUILD_DIR)/docs/manual as per Thomas P. suggestion]
---
Changes v5 -> v6:
- build in BUILD_DIR/docs/manual, to avoid name-clashing with a package (for when later documents are added) (Thomas P.)
--- docs/manual/manual.mk | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-)
docs/manual/manual.mk +16 -8
@@ -1,11 +1,20 @@ +$(BUILD_DIR)/docs/$(pkgname): + $(Q)mkdir -p $@ + +manual-rsync: $(BUILD_DIR)/docs/$(pkgname) + $(Q)$(call MESSAGE,"Preparing the manual sources...") + $(Q)rsync -a docs/$(pkgname)/ $(BUILD_DIR)/docs/$(pkgname) + # Packages included in BR2_EXTERNAL are not part of buildroot, so they # should not be included in the manual. -manual-update-lists: manual-check-dependencies-lists +manual-update-lists: manual-check-dependencies-lists $(BUILD_DIR)/docs/$(pkgname) $(Q)$(call MESSAGE,"Updating the manual lists...") - $(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(O)/docs/manual/.build \ + $(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(BUILD_DIR)/docs/$(pkgname) \ BR2_EXTERNAL=$(TOPDIR)/support/dummy-external \ python -B $(TOPDIR)/support/scripts/gen-manual-lists.py +manual-prepare-sources: manual-rsync manual-update-lists + # we can't use suitable-host-package here because that's not available in # the context of 'make release' manual-check-dependencies:
@@ -65,14 +74,13 @@ $$(O)/docs/$(1)/$(1).$(4): docs/$(1)/$(1).txt \ $$($$(call UPPERCASE,$(1))_SOURCES) \ manual-check-dependencies \ manual-check-dependencies-$(3) \ - manual-update-lists + manual-prepare-sources $$(Q)$$(call MESSAGE,"Generating $(5) $(1)...") - $$(Q)mkdir -p $$(@D)/.build - $$(Q)rsync -au docs/$(1)/*.txt $$(@D)/.build + $$(Q)mkdir -p $$(@D) $$(Q)a2x $(6) -f $(2) -d book -L -r $$(TOPDIR)/docs/images \ --asciidoc-opts="$$(MANUAL_$(2)_ASCIIDOC_OPTS)" \ - -D $$(@D) $$(@D)/.build/$(1).txt - -$$(Q)rm -rf $$(@D)/.build + -D $$(@D) \ + $$(BUILD_DIR)/docs/$(1)/$(1).txt endef ################################################################################
@@ -94,7 +102,7 @@ $(call GENDOC_INNER,$(pkgname),text,text,text,text) $(call GENDOC_INNER,$(pkgname),epub,epub,epub,ePUB) clean: $(pkgname)-clean $(pkgname)-clean: - $$(Q)$$(RM) -rf $$(O)/docs/$(pkgname) + $$(Q)$$(RM) -rf $$(BUILD_DIR)/docs/$(pkgname) .PHONY: $(pkgname) $(pkgname)-clean manual-update-lists endef
Signature · 1 line
1.9.1
PATCH v6 2/25 gendoc infra: avoid a2x warning
In reply to Yann E. MORINFrom: Samuel Martin <[email protected]>
Though the --destination-dir option works as expected, a2x displays the following message when generating the pdf and text manual:
a2x: WARNING: --destination-dir option is only applicable to HTML based outputs
To avoid this warning, we now just build the manual in its build location, then move the generated files into $(O)/docs/manual.
--- docs/manual/manual.mk | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-)
docs/manual/manual.mk +16 -1
@@ -70,6 +70,19 @@ ifneq ($$(wildcard $$(MANUAL_$(2)_ASCIIDOC_CONF)),) MANUAL_$(2)_ASCIIDOC_OPTS += -f $$(MANUAL_$(2)_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 manual to the output directory +MANUAL_$(2)_A2X_OPTS = +ifneq ($$(filter $(3),html split-html),) +MANUAL_$(2)_A2X_OPTS += --destination-dir="$$(@D)" +else +define MANUAL_$(2)_INSTALL_CMDS + $$(Q)cp -f $$(BUILD_DIR)/docs/$(1)/$(1).$(4) $$(@D) +endef +endif + $$(O)/docs/$(1)/$(1).$(4): docs/$(1)/$(1).txt \ $$($$(call UPPERCASE,$(1))_SOURCES) \ manual-check-dependencies \
@@ -78,9 +91,11 @@ $$(O)/docs/$(1)/$(1).$(4): docs/$(1)/$(1).txt \ $$(Q)$$(call MESSAGE,"Generating $(5) $(1)...") $$(Q)mkdir -p $$(@D) $$(Q)a2x $(6) -f $(2) -d book -L -r $$(TOPDIR)/docs/images \ + $$(MANUAL_$(2)_A2X_OPTS) \ --asciidoc-opts="$$(MANUAL_$(2)_ASCIIDOC_OPTS)" \ - -D $$(@D) \ $$(BUILD_DIR)/docs/$(1)/$(1).txt +# install the generated manual + $$(MANUAL_$(2)_INSTALL_CMDS) endef ################################################################################
Signature · 1 line
1.9.1
PATCH v6 3/25 gendoc infra: disable pdf manual generation if xsltproc is buggy
In reply to Yann E. MORINFrom: Samuel Martin <[email protected]>
The PDF manual generation reaches the default xsltproc's template recursion limit when processing the target package list; this makes the PDF manual generation fail [1-3].
This limit can be raised with the '--maxvars' option. Unfortunately, this option is not correctly handled in the latest xsltproc/libxslt release (1.1.28), but this bug is already fixed in the libxslt repository [4].
This patch disables the PDF manual generation (makes it warn with a meaningful error message) when the xsltproc program found in the PATH does not support the --maxvars option.
So, one can still generate the PDF manual if he/she extends PATH with the location of a working xsltproc, by running:
$ PATH=/path/to/custom-xsltproc/bin:${PATH} make manual-pdf[1] http://lists.busybox.net/pipermail/buildroot/2014-August/104390.html
[2] http://lists.busybox.net/pipermail/buildroot/2014-August/104418.html
[3] http://lists.busybox.net/pipermail/buildroot/2014-August/104421.html
[4] https://gitorious.org/libxslt/libxslt/commit/5af7ad745323004984287e48b42712e7305de35c
[yann.morin.1998 at free.fr: move the assignment block out of GENDOC_INNER, no
need to retest for each type of each document: it's always the same answer; make it a warning as per Thomas DS. suggestion]
---
Changes v5 -> v6:
- make it a warning, not an error (Thomas DS)
--- docs/manual/manual.mk | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-)
docs/manual/manual.mk +27 -1
@@ -41,6 +41,20 @@ manual-check-dependencies-lists: exit 1; \ fi +# PDF manual 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 the pdf manual using a buggy version of the +# xsltproc program. +# +# So, to overcome this issue and being able to build the pdf manual, you can +# build xsltproc from it source repository, then run: +# $ PATH=/path/to/custom-xsltproc/bin:${PATH} make manual +MANUAL_XSLTPROC_IS_BROKEN = \ + $(shell xsltproc --maxvars 0 >/dev/null 2>/dev/null || echo y) + ################################################################################ # GENDOC_INNER -- generates the make targets needed to build a specific type of # asciidoc documentation.
@@ -83,6 +97,14 @@ define MANUAL_$(2)_INSTALL_CMDS endef endif +ifeq ($(4)-$$(MANUAL_XSLTPROC_IS_BROKEN),pdf-y) +$$(O)/docs/$(1)/$(1).$(4): + $$(warning PDF manual generation is disabled because of a bug in \ + xsltproc. To be able to generate the PDF manual, 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 manual-pdf') +else $$(O)/docs/$(1)/$(1).$(4): docs/$(1)/$(1).txt \ $$($$(call UPPERCASE,$(1))_SOURCES) \ manual-check-dependencies \
@@ -96,6 +118,7 @@ $$(O)/docs/$(1)/$(1).$(4): docs/$(1)/$(1).txt \ $$(BUILD_DIR)/docs/$(1)/$(1).txt # install the generated manual $$(MANUAL_$(2)_INSTALL_CMDS) +endif endef ################################################################################
@@ -111,8 +134,11 @@ $(call GENDOC_INNER,$(pkgname),xhtml,html,html,HTML,\ --xsltproc-opts "--stringparam toc.section.depth 1") $(call GENDOC_INNER,$(pkgname),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 GENDOC_INNER,$(pkgname),pdf,pdf,pdf,PDF,\ - --dblatex-opts "-P latex.output.revhistory=0") + --dblatex-opts "-P latex.output.revhistory=0 -x '--maxvars 100000'") $(call GENDOC_INNER,$(pkgname),text,text,text,text) $(call GENDOC_INNER,$(pkgname),epub,epub,epub,ePUB) clean: $(pkgname)-clean
Signature · 1 line
1.9.1
PATCH v6 4/25 docs/manual: get rid of legacy comment in GENDOC
In reply to Yann E. MORINSince dd935d6 (gendoc infra: use $(pkgname) instead of explicitly passing 'manual', the GENDOC infra no longer expect any argument.
Remove the stray comment.
--- docs/manual/manual.mk | 3 --- 1 file changed, 3 deletions(-)
docs/manual/manual.mk +0 -3
@@ -124,9 +124,6 @@ endef ################################################################################ # GENDOC -- generates the make targets needed to build asciidoc documentation. # -# argument 1 is the name of the document and must be a subdirectory of docs/; -# the top-level asciidoc file must have the same name -# # The variable <DOCUMENT_NAME>_SOURCES defines the dependencies. ################################################################################ define GENDOC
Signature · 1 line
1.9.1
PATCH v6 5/25 docs/manual: copying the manual sources is a common action
In reply to Yann E. MORINMove the creation of $(BUILD_DIR)/manual and the rsyncing of the sources into GENDOC.
This is is needed so that GENDOC can be easily used to generate another document, without requiring that document to duplicate the copying rules.
--- docs/manual/manual.mk | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-)
docs/manual/manual.mk +7 -7
@@ -1,10 +1,3 @@ -$(BUILD_DIR)/docs/$(pkgname): - $(Q)mkdir -p $@ - -manual-rsync: $(BUILD_DIR)/docs/$(pkgname) - $(Q)$(call MESSAGE,"Preparing the manual sources...") - $(Q)rsync -a docs/$(pkgname)/ $(BUILD_DIR)/docs/$(pkgname) - # Packages included in BR2_EXTERNAL are not part of buildroot, so they # should not be included in the manual. manual-update-lists: manual-check-dependencies-lists $(BUILD_DIR)/docs/$(pkgname)
@@ -127,6 +120,13 @@ endef # The variable <DOCUMENT_NAME>_SOURCES defines the dependencies. ################################################################################ define GENDOC +$$(BUILD_DIR)/docs/$(pkgname): + $$(Q)mkdir -p $$@ + +$(pkgname)-rsync: $$(BUILD_DIR)/docs/$(pkgname) + $$(Q)$$(call MESSAGE,"Preparing the $(pkgname) sources...") + $$(Q)rsync -a docs/$(pkgname)/ $$^ + $(call GENDOC_INNER,$(pkgname),xhtml,html,html,HTML,\ --xsltproc-opts "--stringparam toc.section.depth 1") $(call GENDOC_INNER,$(pkgname),chunked,split-html,chunked,split HTML,\
Signature · 1 line
1.9.1
PATCH v6 6/25 docs/manual: simplify generation dependencies
In reply to Yann E. MORINThe document's main file is already part of MANUAL_SOURCES, so no need to explicitly depend on it.
--- docs/manual/manual.mk | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-)
docs/manual/manual.mk +1 -2
@@ -98,8 +98,7 @@ $$(O)/docs/$(1)/$(1).$(4): to make through the command line: \ 'PATH=/path/to/custom-xsltproc/bin:$$$${PATH} make manual-pdf') else -$$(O)/docs/$(1)/$(1).$(4): docs/$(1)/$(1).txt \ - $$($$(call UPPERCASE,$(1))_SOURCES) \ +$$(O)/docs/$(1)/$(1).$(4): $$($$(call UPPERCASE,$(1))_SOURCES) \ manual-check-dependencies \ manual-check-dependencies-$(3) \ manual-prepare-sources
Signature · 1 line
1.9.1
PATCH v6 7/25 docs/manual: manual-update-lists is not a generic GENDOC rule
In reply to Yann E. MORINMove the manual-update-lists .PHONY declaration out of GENDOC, since not all the documents may have an -update-lists rule.
--- docs/manual/manual.mk | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
docs/manual/manual.mk +2 -1
@@ -1,5 +1,6 @@ # Packages included in BR2_EXTERNAL are not part of buildroot, so they # should not be included in the manual. +.PHONY: manual-update-lists manual-update-lists: manual-check-dependencies-lists $(BUILD_DIR)/docs/$(pkgname) $(Q)$(call MESSAGE,"Updating the manual lists...") $(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(BUILD_DIR)/docs/$(pkgname) \
@@ -140,7 +141,7 @@ $(call GENDOC_INNER,$(pkgname),epub,epub,epub,ePUB) clean: $(pkgname)-clean $(pkgname)-clean: $$(Q)$$(RM) -rf $$(BUILD_DIR)/docs/$(pkgname) -.PHONY: $(pkgname) $(pkgname)-clean manual-update-lists +.PHONY: $(pkgname) $(pkgname)-clean endef MANUAL_SOURCES = $(sort $(wildcard docs/manual/*.txt) $(wildcard docs/images/*))
Signature · 1 line
1.9.1
PATCH v6 8/25 docs/manual: move manual-prepare-sources rule into GENDOC
In reply to Yann E. MORINCopying the document's source files is a generic GENDOC action, that will be common to all documents, so the dependency rule should be handled in GENDOC, rather than letting all documents duplicate it.
--- docs/manual/manual.mk | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)
docs/manual/manual.mk +3 -1
@@ -7,7 +7,7 @@ manual-update-lists: manual-check-dependencies-lists $(BUILD_DIR)/docs/$(pkgname BR2_EXTERNAL=$(TOPDIR)/support/dummy-external \ python -B $(TOPDIR)/support/scripts/gen-manual-lists.py -manual-prepare-sources: manual-rsync manual-update-lists +manual-prepare-sources: manual-update-lists # we can't use suitable-host-package here because that's not available in # the context of 'make release'
@@ -127,6 +127,8 @@ $(pkgname)-rsync: $$(BUILD_DIR)/docs/$(pkgname) $$(Q)$$(call MESSAGE,"Preparing the $(pkgname) sources...") $$(Q)rsync -a docs/$(pkgname)/ $$^ +$(pkgname)-prepare-sources: $(pkgname)-rsync + $(call GENDOC_INNER,$(pkgname),xhtml,html,html,HTML,\ --xsltproc-opts "--stringparam toc.section.depth 1") $(call GENDOC_INNER,$(pkgname),chunked,split-html,chunked,split HTML,\
Signature · 1 line
1.9.1
PATCH v6 9/25 docs/manual: do not hardcode name of the generated document
In reply to Yann E. MORINCurrently, GENDOC_INNER hard-codes some variables to have the name of the document in them:
MANUAL_$(2)_ASCIIDOC_CONF
MANUAL_$(2)_ASCIIDOC_OPTS
MANUAL_$(2)_A2X_OPTS
MANUAL_$(2)_INSTALL_CMDS
...Also, it defines some dependency on the generation rule, onto:
manual-check-dependencies
manual-check-dependencies-$(3)
manual-prepare-sourcesThis is problematic, as it is not possible to have another document generated with the GENDOC infra, or it would trigger the rules, and use the variables for our own document, 'manual'.
Add a new argument to GENDOC_INNER to be the uppercase name of the document, much like it is done for the PKG_*_INNER functions. Replace any reference to 'manual' with the currently passed named of the current document, $(1).
The remaining references to 'manual' are on purpose, as they really pertain to our manual.
---
Changes v5 -> v6:
- do not use $$ when calling UPPERCASE (Thomas DS)
- also rename the variable with the xsltproc check (Samuel)
- s/manual/document/g in the comments, too (Thomas DS)
- typo in commit log (Samuel)
--- docs/manual/manual.mk | 93 ++++++++++++++++++++++++++------------------------- 1 file changed, 47 insertions(+), 46 deletions(-)
docs/manual/manual.mk +47 -46
@@ -14,17 +14,17 @@ manual-prepare-sources: manual-update-lists manual-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 the manual"; \ + "to generate a document"; \ exit 1; \ fi $(Q)if [ -z "`which w3m 2>/dev/null`" ]; then \ - echo "You need w3m on your host to generate the manual"; \ + echo "You need w3m on your host to generate a document"; \ exit 1; \ fi manual-check-dependencies-pdf: $(Q)if [ -z "`which dblatex 2>/dev/null`" ]; then \ - echo "You need dblatex on your host to generate the pdf manual"; \ + echo "You need dblatex on your host to generate a PDF document"; \ exit 1; \ fi
@@ -35,18 +35,18 @@ manual-check-dependencies-lists: exit 1; \ fi -# PDF manual generation is broken because of a bug in xsltproc program provided +# 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 the pdf manual using a buggy version of the +# 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 the pdf manual, you can -# build xsltproc from it source repository, then run: +# 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 -MANUAL_XSLTPROC_IS_BROKEN = \ +GENDOC_XSLTPROC_IS_BROKEN = \ $(shell xsltproc --maxvars 0 >/dev/null 2>/dev/null || echo y) ################################################################################
@@ -55,11 +55,12 @@ MANUAL_XSLTPROC_IS_BROKEN = \ # # argument 1 is the name of the document and must be a subdirectory of docs/; # the top-level asciidoc file must have the same name -# argument 2 is the type of document to generate (-f argument of a2x) -# argument 3 is the document type as used in the make target -# argument 4 is the output file extension for the document type -# argument 5 is the human text for the document type -# argument 6 (optional) are extra arguments for a2x +# argument 2 is the uppercase name of the document +# 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 # # The variable <DOCUMENT_NAME>_SOURCES defines the dependencies. #
@@ -67,50 +68,50 @@ MANUAL_XSLTPROC_IS_BROKEN = \ # all variable references except the arguments must be $$-quoted. ################################################################################ define GENDOC_INNER -$(1): $(1)-$(3) -.PHONY: $(1)-$(3) -$(1)-$(3): $$(O)/docs/$(1)/$(1).$(4) +$(1): $(1)-$(4) +.PHONY: $(1)-$(4) +$(1)-$(4): $$(O)/docs/$(1)/$(1).$(5) -manual-check-dependencies-$(3): +$(1)-check-dependencies-$(4): -MANUAL_$(2)_ASCIIDOC_CONF = docs/$(1)/asciidoc-$(2).conf -ifneq ($$(wildcard $$(MANUAL_$(2)_ASCIIDOC_CONF)),) -MANUAL_$(2)_ASCIIDOC_OPTS += -f $$(MANUAL_$(2)_ASCIIDOC_CONF) +$(2)_$(3)_ASCIIDOC_CONF = docs/$(1)/asciidoc-$(3).conf +ifneq ($$(wildcard $$($(2)_$(3)_ASCIIDOC_CONF)),) +$(2)_$(3)_ASCIIDOC_OPTS += -f $$($(2)_$(3)_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 manual to the output directory -MANUAL_$(2)_A2X_OPTS = -ifneq ($$(filter $(3),html split-html),) -MANUAL_$(2)_A2X_OPTS += --destination-dir="$$(@D)" +# - otherwise copy the generated document to the output directory +$(2)_$(3)_A2X_OPTS = +ifneq ($$(filter $(4),html split-html),) +$(2)_$(3)_A2X_OPTS += --destination-dir="$$(@D)" else -define MANUAL_$(2)_INSTALL_CMDS - $$(Q)cp -f $$(BUILD_DIR)/docs/$(1)/$(1).$(4) $$(@D) +define $(2)_$(3)_INSTALL_CMDS + $$(Q)cp -f $$(BUILD_DIR)/docs/$(1)/$(1).$(5) $$(@D) endef endif -ifeq ($(4)-$$(MANUAL_XSLTPROC_IS_BROKEN),pdf-y) -$$(O)/docs/$(1)/$(1).$(4): - $$(warning PDF manual generation is disabled because of a bug in \ - xsltproc. To be able to generate the PDF manual, you should \ +ifeq ($(5)-$$(GENDOC_XSLTPROC_IS_BROKEN),pdf-y) +$$(O)/docs/$(1)/$(1).$(5): + $$(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 manual-pdf') + 'PATH=/path/to/custom-xsltproc/bin:$$$${PATH} make $(1)-pdf') else -$$(O)/docs/$(1)/$(1).$(4): $$($$(call UPPERCASE,$(1))_SOURCES) \ - manual-check-dependencies \ - manual-check-dependencies-$(3) \ - manual-prepare-sources - $$(Q)$$(call MESSAGE,"Generating $(5) $(1)...") +$$(O)/docs/$(1)/$(1).$(5): $$($(call UPPERCASE,$(1))_SOURCES) \ + $(1)-check-dependencies \ + $(1)-check-dependencies-$(4) \ + $(1)-prepare-sources + $$(Q)$$(call MESSAGE,"Generating $(6) $(1)...") $$(Q)mkdir -p $$(@D) - $$(Q)a2x $(6) -f $(2) -d book -L -r $$(TOPDIR)/docs/images \ - $$(MANUAL_$(2)_A2X_OPTS) \ - --asciidoc-opts="$$(MANUAL_$(2)_ASCIIDOC_OPTS)" \ + $$(Q)a2x $(7) -f $(3) -d book -L -r $$(TOPDIR)/docs/images \ + $$($(2)_$(3)_A2X_OPTS) \ + --asciidoc-opts="$$($(2)_$(3)_ASCIIDOC_OPTS)" \ $$(BUILD_DIR)/docs/$(1)/$(1).txt -# install the generated manual - $$(MANUAL_$(2)_INSTALL_CMDS) +# install the generated document + $$($(2)_$(3)_INSTALL_CMDS) endif endef
@@ -129,17 +130,17 @@ $(pkgname)-rsync: $$(BUILD_DIR)/docs/$(pkgname) $(pkgname)-prepare-sources: $(pkgname)-rsync -$(call GENDOC_INNER,$(pkgname),xhtml,html,html,HTML,\ +$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),xhtml,html,html,HTML,\ --xsltproc-opts "--stringparam toc.section.depth 1") -$(call GENDOC_INNER,$(pkgname),chunked,split-html,chunked,split HTML,\ +$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),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 GENDOC_INNER,$(pkgname),pdf,pdf,pdf,PDF,\ +$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),pdf,pdf,pdf,PDF,\ --dblatex-opts "-P latex.output.revhistory=0 -x '--maxvars 100000'") -$(call GENDOC_INNER,$(pkgname),text,text,text,text) -$(call GENDOC_INNER,$(pkgname),epub,epub,epub,ePUB) +$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),text,text,text,text) +$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),epub,epub,epub,ePUB) clean: $(pkgname)-clean $(pkgname)-clean: $$(Q)$$(RM) -rf $$(BUILD_DIR)/docs/$(pkgname)
Signature · 1 line
1.9.1
PATCH v6 9/25 docs/manual: do not hardcode name of the generated document
Hi Yann,
Quoted 45 lines · Yann E. MORIN
Currently,
GENDOC_INNERhard-codes some variables to have the name of the document in them:MANUAL_$(2)_ASCIIDOC_CONF MANUAL_$(2)_ASCIIDOC_OPTS MANUAL_$(2)_A2X_OPTS MANUAL_$(2)_INSTALL_CMDS ...Also, it defines some dependency on the generation rule, onto:
manual-check-dependencies manual-check-dependencies-$(3) manual-prepare-sourcesThis is problematic, as it is not possible to have another document generated with the GENDOC infra, or it would trigger the rules, and use the variables for our own document, 'manual'.
Add a new argument to
GENDOC_INNERto be the uppercase name of the document, much like it is done for the PKG_*_INNER functions. Replace any reference to 'manual' with the currently passed named of the current document, $(1).The remaining references to 'manual' are on purpose, as they really pertain to our manual.
Signed-off-by "Yann E. MORIN" <[email protected]>Cc Samuel Martin <[email protected]>Cc Thomas De Schampheleire <[email protected]>Reviewed-by Samuel Martin <[email protected]>---
Changes v5 -> v6:
- do not use $$ when calling UPPERCASE (Thomas DS)
- also rename the variable with the xsltproc check (Samuel)
- s/manual/document/g in the comments, too (Thomas DS)
- typo in commit log (Samuel)--- docs/manual/manual.mk | 93 ++++++++++++++++++++++++++------------------------- 1 file changed, 47 insertions(+), 46 deletions(-)docs/manual/manual.mk +0
-0
docs/manual/manual.mk manual-prepare-sources: manual-update-lists · line 17
Quoted 5 lines
docs/manual/manual.mk +1
-1@@ -14,17 +14,17 @@ manual-prepare-sources: manual-update-lists manual-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 the manual"; \ + "to generate a document"; \
Nit: I would write 'to generate documents' here.
docs/manual/manual.mk manual-prepare-sources: manual-update-lists · line 21
Quoted 5 lines
docs/manual/manual.mk +1
-1exit 1; \ fi $(Q)if [ -z "`which w3m 2>/dev/null`" ]; then \ - echo "You need w3m on your host to generate the manual"; \ + echo "You need w3m on your host to generate a document"; \
Same here.
docs/manual/manual.mk manual-prepare-sources: manual-update-lists · line 27
Quoted 7 lines
docs/manual/manual.mk +1
-1exit 1; \ fi manual-check-dependencies-pdf: $(Q)if [ -z "`which dblatex 2>/dev/null`" ]; then \ - echo "You need dblatex on your host to generate the pdf manual"; \ + echo "You need dblatex on your host to generate a PDF document"; \
This would become 'to generate PDF documents'
Quoted 95 lines
docs/manual/manual.mk +28
-27exit 1; \ fi@@ -35,18 +35,18 @@ manual-check-dependencies-lists: exit 1; \ fi -# PDF manual generation is broken because of a bug in xsltproc program provided +# 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 the pdf manual using a buggy version of the +# 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 the pdf manual, you can -# build xsltproc from it source repository, then run: +# 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 -MANUAL_XSLTPROC_IS_BROKEN = \ +GENDOC_XSLTPROC_IS_BROKEN = \ $(shell xsltproc --maxvars 0 >/dev/null 2>/dev/null || echo y) ################################################################################@@ -55,11 +55,12 @@ MANUAL_XSLTPROC_IS_BROKEN = \ # # argument 1 is the name of the document and must be a subdirectory of docs/; # the top-level asciidoc file must have the same name -# argument 2 is the type of document to generate (-f argument of a2x) -# argument 3 is the document type as used in the make target -# argument 4 is the output file extension for the document type -# argument 5 is the human text for the document type -# argument 6 (optional) are extra arguments for a2x +# argument 2 is the uppercase name of the document +# 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 # # The variable <DOCUMENT_NAME>_SOURCES defines the dependencies. #@@ -67,50 +68,50 @@ MANUAL_XSLTPROC_IS_BROKEN = \ # all variable references except the arguments must be $$-quoted. ################################################################################ define GENDOC_INNER -$(1): $(1)-$(3) -.PHONY: $(1)-$(3) -$(1)-$(3): $$(O)/docs/$(1)/$(1).$(4) +$(1): $(1)-$(4) +.PHONY: $(1)-$(4) +$(1)-$(4): $$(O)/docs/$(1)/$(1).$(5) -manual-check-dependencies-$(3): +$(1)-check-dependencies-$(4): -MANUAL_$(2)_ASCIIDOC_CONF = docs/$(1)/asciidoc-$(2).conf -ifneq ($$(wildcard $$(MANUAL_$(2)_ASCIIDOC_CONF)),) -MANUAL_$(2)_ASCIIDOC_OPTS += -f $$(MANUAL_$(2)_ASCIIDOC_CONF) +$(2)_$(3)_ASCIIDOC_CONF = docs/$(1)/asciidoc-$(3).conf +ifneq ($$(wildcard $$($(2)_$(3)_ASCIIDOC_CONF)),) +$(2)_$(3)_ASCIIDOC_OPTS += -f $$($(2)_$(3)_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 manual to the output directory -MANUAL_$(2)_A2X_OPTS = -ifneq ($$(filter $(3),html split-html),) -MANUAL_$(2)_A2X_OPTS += --destination-dir="$$(@D)" +# - otherwise copy the generated document to the output directory +$(2)_$(3)_A2X_OPTS = +ifneq ($$(filter $(4),html split-html),) +$(2)_$(3)_A2X_OPTS += --destination-dir="$$(@D)" else -define MANUAL_$(2)_INSTALL_CMDS - $$(Q)cp -f $$(BUILD_DIR)/docs/$(1)/$(1).$(4) $$(@D) +define $(2)_$(3)_INSTALL_CMDS + $$(Q)cp -f $$(BUILD_DIR)/docs/$(1)/$(1).$(5) $$(@D) endef endif -ifeq ($(4)-$$(MANUAL_XSLTPROC_IS_BROKEN),pdf-y) -$$(O)/docs/$(1)/$(1).$(4): - $$(warning PDF manual generation is disabled because of a bug in \ - xsltproc. To be able to generate the PDF manual, you should \ +ifeq ($(5)-$$(GENDOC_XSLTPROC_IS_BROKEN),pdf-y) +$$(O)/docs/$(1)/$(1).$(5): + $$(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 \
docs/manual/manual.mk MANUAL_XSLTPROC_IS_BROKEN = \ · line 103
Quoted 10 lines
docs/manual/manual.mk +2
-6to make through the command line: \ - 'PATH=/path/to/custom-xsltproc/bin:$$$${PATH} make manual-pdf') + 'PATH=/path/to/custom-xsltproc/bin:$$$${PATH} make $(1)-pdf') else -$$(O)/docs/$(1)/$(1).$(4): $$($$(call UPPERCASE,$(1))_SOURCES) \ - manual-check-dependencies \ - manual-check-dependencies-$(3) \ - manual-prepare-sources - $$(Q)$$(call MESSAGE,"Generating $(5) $(1)...") +$$(O)/docs/$(1)/$(1).$(5): $$($(call UPPERCASE,$(1))_SOURCES) \
I didn't mean to also change this uppercase call from $$ to $. The 'exception' is until now only made when calling the inner infra from the outer one. On this line, we are already in the inner infra so one would use $$.
docs/manual/manual.mk MANUAL_XSLTPROC_IS_BROKEN = \ · line 107
Quoted 4 lines
docs/manual/manual.mk +4
-0+ $(1)-check-dependencies \ + $(1)-check-dependencies-$(4) \ + $(1)-prepare-sources + $$(Q)$$(call MESSAGE,"Generating $(6) $(1)...")
What is the purpose of the quotes here, given your recent commit of qstrip in MESSAGE ?
Best regards,
Thomas
PATCH v6 9/25 docs/manual: do not hardcode name of the generated document
Thomas, All,
On 2014-09-29 21:33 +0200, Thomas De Schampheleire spake thusly:
Quoted 1 line · Yann E. MORIN
[--SNIp--]
Quoted 9 lines
docs/manual/manual.mk manual-prepare-sources: manual-update-lists · line 17
Quoted 2 lines
docs/manual/manual.mk +1
-1- "to generate the manual"; \ + "to generate a document"; \Nit: I would write 'to generate documents' here.
docs/manual/manual.mk manual-prepare-sources: manual-update-lists · line 21
Quoted 2 lines
docs/manual/manual.mk +1
-1- echo "You need w3m on your host to generate the manual"; \ + echo "You need w3m on your host to generate a document"; \Same here.
docs/manual/manual.mk manual-prepare-sources: manual-update-lists · line 27
Quoted 2 lines
docs/manual/manual.mk +1
-1- echo "You need dblatex on your host to generate the pdf manual"; \ + echo "You need dblatex on your host to generate a PDF document"; \This would become 'to generate PDF documents'
OK, I don;t mind. Will do.
Quoted 6 lines
Quoted 1 line
+$$(O)/docs/$(1)/$(1).$(5): $$($(call UPPERCASE,$(1))_SOURCES) \
I didn't mean to also change this uppercase call from $$ to $. The 'exception' is until now only made when calling the inner infra from the outer one. On this line, we are already in the inner infra so one would use $$.
But that does not matter, does it?
The expansion of $(call UPPERCASE) is done on a parameter, so we might as well expand it right at call time, rather than at evaluation time, no?
Quoted 7 lines
docs/manual/manual.mk MANUAL_XSLTPROC_IS_BROKEN = \ · line 107
Quoted 4 lines
docs/manual/manual.mk +4
-0+ $(1)-check-dependencies \ + $(1)-check-dependencies-$(4) \ + $(1)-prepare-sources + $$(Q)$$(call MESSAGE,"Generating $(6) $(1)...")What is the purpose of the quotes here, given your recent commit of qstrip in MESSAGE ?
Because I looked at what was done in pkg-generic or some such, and mimicked. At which point someone noticed on the ML (or IRC) about the quoting issue, and I did not adapt my code.
But it does not really matter: we can quote messages, now. Or not.
Regards,
Yann E. MORIN.
Signature · 6 lines
.-----------------.--------------------.------------------.--------------------. | Yann E. MORIN | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: | | +33 662 376 056 | Software Designer | \ / CAMPAIGN | ___ | | +33 223 225 172 `------------.-------: X AGAINST | \e/ There is no | | http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL | v conspiracy. | '------------------------------^-------^------------------^--------------------'
PATCH v6 9/25 docs/manual: do not hardcode name of the generated document
"Yann E. MORIN" <[email protected]> schreef:
Quoted 24 lines
Thomas, All,
On 2014-09-29 21:33 +0200, Thomas De Schampheleire spake thusly:
Quoted 1 line · Yann E. MORIN
[--SNIp--]
Quoted 9 lines
docs/manual/manual.mk manual-prepare-sources: manual-update-lists · line 17
Quoted 2 lines
docs/manual/manual.mk +1
-1- "to generate the manual"; \ + "to generate a document"; \Nit: I would write 'to generate documents' here.
docs/manual/manual.mk manual-prepare-sources: manual-update-lists · line 21
Quoted 2 lines
docs/manual/manual.mk +1
-1- echo "You need w3m on your host to generate the manual"; \ + echo "You need w3m on your host to generate a document"; \Same here.
docs/manual/manual.mk manual-prepare-sources: manual-update-lists · line 27
Quoted 2 lines
docs/manual/manual.mk +1
-1- echo "You need dblatex on your host to generate the pdf manual"; \ + echo "You need dblatex on your host to generate a PDF document"; \This would become 'to generate PDF documents'
OK, I don;t mind. Will do.
Quoted 6 lines
Quoted 1 line
+$$(O)/docs/$(1)/$(1).$(5): $$($(call UPPERCASE,$(1))_SOURCES) \
I didn't mean to also change this uppercase call from $$ to $. The 'exception' is until now only made when calling the inner infra from the outer one. On this line, we are already in the inner infra so one would use $$.
Quoted 5 lines
But that does not matter, does it?
The expansion of $(call UPPERCASE) is done on a parameter, so we might as well expand it right at call time, rather than at evaluation time, no?
Technically you're right. However, in the discussion
on the dollars we realized that the matter is sufficiently non-obvious that we better use clear cut rules. That rule says that everything should be $$ except for parameters, pkgname/pkgdir and the uppercase call from outer to inner.
In this case, you understand the issue and judge that
a single $ suffices, but tomorrow someone else will change the value and forget to reevaluate the dollars.
Quoted 6 lines
Quoted 6 lines
Quoted 5 lines
docs/manual/manual.mk +4
-0+ $(1)-check-dependencies \ + $(1)-check-dependencies-$(4) \ + $(1)-prepare-sources + $$(Q)$$(call MESSAGE,"Generating $(6) $(1)...")
Quoted 8 lines
Quoted 2 lines
What is the purpose of the quotes here, given your recent commit of qstrip in MESSAGE ?
Because I looked at what was done in pkg-generic or some such, and mimicked. At which point someone noticed on the ML (or IRC) about the quoting issue, and I did not adapt my code.
But it does not really matter: we can quote messages, now. Or not.
True. I don't understand though why we wouldn't
change all unnecessary quoting in the quest for symmetry and simplicity.
Best regards,
Thomas
PATCH v6 9/25 docs/manual: do not hardcode name of the generated document
Thomas, All,
On 2014-09-29 22:09 +0200, Thomas De Schampheleire spake thusly:
Quoted 3 lines
"Yann E. MORIN" <[email protected]> schreef:
Quoted 2 lines
On 2014-09-29 21:33 +0200, Thomas De Schampheleire spake thusly:
Quoted 1 line · Yann E. MORIN
[--SNIP--]
Quoted 20 lines
Quoted 7 lines
Quoted 6 lines
Quoted 1 line
+$$(O)/docs/$(1)/$(1).$(5): $$($(call UPPERCASE,$(1))_SOURCES) \
I didn't mean to also change this uppercase call from $$ to $. The 'exception' is until now only made when calling the inner infra from the outer one. On this line, we are already in the inner infra so one would use $$.
Quoted 5 lines
But that does not matter, does it?
The expansion of $(call UPPERCASE) is done on a parameter, so we might as well expand it right at call time, rather than at evaluation time, no?
Technically you're right. However, in the discussion
on the dollars we realized that the matter is sufficiently non-obvious that we better use clear cut rules. That rule says that everything should be $$ except for parameters, pkgname/pkgdir and the uppercase call from outer to inner.
Quoted 3 lines
In this case, you understand the issue and judge that
a single $ suffices, but tomorrow someone else will change the value and forget to reevaluate the dollars.
Agreed, that's fair. I will change.
Quoted 8 lines
Quoted 8 lines
Quoted 7 lines
docs/manual/manual.mk MANUAL_XSLTPROC_IS_BROKEN = \ · line 107
Quoted 4 lines
docs/manual/manual.mk +4
-0+ $(1)-check-dependencies \ + $(1)-check-dependencies-$(4) \ + $(1)-prepare-sources + $$(Q)$$(call MESSAGE,"Generating $(6) $(1)...")What is the purpose of the quotes here, given your recent commit of qstrip in MESSAGE ?
Quoted 8 lines
Quoted 5 lines
Because I looked at what was done in pkg-generic or some such, and mimicked. At which point someone noticed on the ML (or IRC) about the quoting issue, and I did not adapt my code.
But it does not really matter: we can quote messages, now. Or not.
True. I don't understand though why we wouldn't
change all unnecessary quoting in the quest for symmetry and simplicity.
If at all, we should change to always quote messages.
The problem is two-fold:
- no quoting: we can not have a comma in the message, otherwise make
would split on it: $(call MESSAGE,This, and that, should foo)
- always quoting: the MESSAGE definition already does the quoting to ensure it does not break on a semi-colon (which you noticed):
$(call MESSAGE,"; echo shellshock")
(He, shellshock is all the hype nowadays. Even superseeds heartbleed!)
If MESSAGE would not do the quoting, and rely on the caller to do it, we'd be vulnerable to: $(call MESSAGE,; echo shellshock)
So: we want MESSAGE to always quote its arguments (and no, single quotes do not cut it either, because a message might have single quotes too), while still allowing callers to do the quoting. Or not.
Regards,
Yann E. MORIN.
Signature · 6 lines
.-----------------.--------------------.------------------.--------------------. | Yann E. MORIN | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: | | +33 662 376 056 | Software Designer | \ / CAMPAIGN | ___ | | +33 223 225 172 `------------.-------: X AGAINST | \e/ There is no | | http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL | v conspiracy. | '------------------------------^-------^------------------^--------------------'
PATCH v6 9/25 docs/manual: do not hardcode name of the generated document
Quoted 1 line · Yann E. MORIN
Thomas, All,
[snip]
Quoted 11 lines
Quoted 4 lines
Quoted 1 line
But it does not really matter: we can quote messages, now. Or not.
True. I don't understand though why we wouldn't
change all unnecessary quoting in the quest for symmetry and simplicity.If at all, we should change to always quote messages.
The problem is two-fold:
- no quoting: we can not have a comma in the message, otherwise make
would split on it: $(call MESSAGE,This, and that, should foo)
"-quotes are completely transparent for make, so quoting doesn't help for
commas. You need $(call MESSAGE,This$(comma) and that$(comma) should foo).
Regards,
Arnout
Quoted 16 lines
- always quoting: the MESSAGE definition already does the quoting to ensure it does not break on a semi-colon (which you noticed):
$(call MESSAGE,"; echo shellshock")(He, shellshock is all the hype nowadays. Even superseeds heartbleed!)
If MESSAGE would not do the quoting, and rely on the caller to do it, we'd be vulnerable to: $(call MESSAGE,; echo shellshock)
So: we want MESSAGE to always quote its arguments (and no, single quotes do not cut it either, because a message might have single quotes too), while still allowing callers to do the quoting. Or not.
Regards,
Yann E. MORIN.
Signature · 6 lines
Arnout Vandecappelle arnout at mind be Senior Embedded Software Architect +32-16-286500 Essensium/Mind http://www.mind.be G.Geenslaan 9, 3001 Leuven, Belgium BE 872 984 063 RPR Leuven LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle GPG fingerprint: 7CB5 E4CC 6C2E EFD4 6E3D A754 F963 ECAB 2450 2F1F
PATCH v6 10/25 docs/manual: allow a document to declare where its resources are
In reply to Yann E. MORINAvoids hard-coding document's resources in GENDOC_INNER, so we can generate another document with different resources (if any).
---
Changes v5 -> v6:
- s/ressources/resources/g (Thomas DS, Samuel)
--- docs/manual/manual.mk | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-)
docs/manual/manual.mk +5 -1
@@ -106,7 +106,8 @@ $$(O)/docs/$(1)/$(1).$(5): $$($(call UPPERCASE,$(1))_SOURCES) \ $(1)-prepare-sources $$(Q)$$(call MESSAGE,"Generating $(6) $(1)...") $$(Q)mkdir -p $$(@D) - $$(Q)a2x $(7) -f $(3) -d book -L -r $$(TOPDIR)/docs/images \ + $$(Q)a2x $(7) -f $(3) -d book -L \ + $$(foreach r,$$($(2)_RESOURCES),-r $$(r)) \ $$($(2)_$(3)_A2X_OPTS) \ --asciidoc-opts="$$($(2)_$(3)_ASCIIDOC_OPTS)" \ $$(BUILD_DIR)/docs/$(1)/$(1).txt
@@ -119,6 +120,8 @@ endef # GENDOC -- generates the make targets needed to build asciidoc documentation. # # 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 GENDOC $$(BUILD_DIR)/docs/$(pkgname):
@@ -148,4 +151,5 @@ $(pkgname)-clean: endef MANUAL_SOURCES = $(sort $(wildcard docs/manual/*.txt) $(wildcard docs/images/*)) +MANUAL_RESOURCES = $(TOPDIR)/docs/images $(eval $(call GENDOC))
Signature · 1 line
1.9.1
PATCH v6 10/25 docs/manual: allow a document to declare where its resources are
Quoted 6 lines · Yann E. MORIN
Avoids hard-coding document's resources in
GENDOC_INNER, so we can generate another document with different resources (if any).Signed-off-by "Yann E. MORIN" <[email protected]>Cc Samuel Martin <[email protected]>Cc Thomas De Schampheleire <[email protected]>
Signature · 1 line
Samuel
PATCH v6 10/25 docs/manual: allow a document to declare where its resources are
In reply to Yann E. MORINQuoted 6 lines · Yann E. MORIN
Avoids hard-coding document's resources in
GENDOC_INNER, so we can generate another document with different resources (if any).Signed-off-by "Yann E. MORIN" <[email protected]>Cc Samuel Martin <[email protected]>Cc Thomas De Schampheleire <[email protected]>
PATCH v6 11/25 docs/manual: last pass at removing hard-coded path in GENDOC_INNER
In reply to Yann E. MORINGENDOC_INNER still has one hard-coded path to the document's directory:
the asciidoc .conf files.
Add a new argument to GENDOC_INNER to pass the directory of the document.
Notes:
- this makes for overly-long lines, but splitting is not possible, otherwise the first argument on the continuation line would get (at least) a leading space or tab, and that would break either or all of the variables names, the dependency rules, or the filenames we look for. A future patch will further clean this up (see: docs/asciidoc: call $(pkgname) and $(pkgdir) in a single place.)
- this means that another document would be missing our tweaks from asciidoc-text.conf to not render images and sanely render hyperlinks. But that was already the case anyway, since we were using docs/$(1)/ to search for that file. A further patch will allow us to have such configuration in a common place.
--- docs/manual/manual.mk | 74 ++++++++++++++++++++++++++++----------------------- 1 file changed, 40 insertions(+), 34 deletions(-)
docs/manual/manual.mk +40 -34
@@ -53,14 +53,15 @@ GENDOC_XSLTPROC_IS_BROKEN = \ # GENDOC_INNER -- generates the make targets needed to build a specific type of # asciidoc documentation. # -# argument 1 is the name of the document and must be a subdirectory of docs/; -# the top-level asciidoc file must have the same name +# 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 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 +# 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. #
@@ -68,51 +69,51 @@ GENDOC_XSLTPROC_IS_BROKEN = \ # all variable references except the arguments must be $$-quoted. ################################################################################ define GENDOC_INNER -$(1): $(1)-$(4) -.PHONY: $(1)-$(4) -$(1)-$(4): $$(O)/docs/$(1)/$(1).$(5) +$(1): $(1)-$(5) +.PHONY: $(1)-$(5) +$(1)-$(5): $$(O)/docs/$(1)/$(1).$(6) -$(1)-check-dependencies-$(4): +$(1)-check-dependencies-$(5): -$(2)_$(3)_ASCIIDOC_CONF = docs/$(1)/asciidoc-$(3).conf -ifneq ($$(wildcard $$($(2)_$(3)_ASCIIDOC_CONF)),) -$(2)_$(3)_ASCIIDOC_OPTS += -f $$($(2)_$(3)_ASCIIDOC_CONF) +$(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)_$(3)_A2X_OPTS = -ifneq ($$(filter $(4),html split-html),) -$(2)_$(3)_A2X_OPTS += --destination-dir="$$(@D)" +$(2)_$(4)_A2X_OPTS = +ifneq ($$(filter $(5),html split-html),) +$(2)_$(4)_A2X_OPTS += --destination-dir="$$(@D)" else -define $(2)_$(3)_INSTALL_CMDS - $$(Q)cp -f $$(BUILD_DIR)/docs/$(1)/$(1).$(5) $$(@D) +define $(2)_$(4)_INSTALL_CMDS + $$(Q)cp -f $$(BUILD_DIR)/docs/$(1)/$(1).$(6) $$(@D) endef endif -ifeq ($(5)-$$(GENDOC_XSLTPROC_IS_BROKEN),pdf-y) -$$(O)/docs/$(1)/$(1).$(5): +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 -$$(O)/docs/$(1)/$(1).$(5): $$($(call UPPERCASE,$(1))_SOURCES) \ +$$(O)/docs/$(1)/$(1).$(6): $$($(call UPPERCASE,$(1))_SOURCES) \ $(1)-check-dependencies \ - $(1)-check-dependencies-$(4) \ + $(1)-check-dependencies-$(5) \ $(1)-prepare-sources - $$(Q)$$(call MESSAGE,"Generating $(6) $(1)...") + $$(Q)$$(call MESSAGE,"Generating $(7) $(1)...") $$(Q)mkdir -p $$(@D) - $$(Q)a2x $(7) -f $(3) -d book -L \ + $$(Q)a2x $(8) -f $(4) -d book -L \ $$(foreach r,$$($(2)_RESOURCES),-r $$(r)) \ - $$($(2)_$(3)_A2X_OPTS) \ - --asciidoc-opts="$$($(2)_$(3)_ASCIIDOC_OPTS)" \ + $$($(2)_$(4)_A2X_OPTS) \ + --asciidoc-opts="$$($(2)_$(4)_ASCIIDOC_OPTS)" \ $$(BUILD_DIR)/docs/$(1)/$(1).txt # install the generated document - $$($(2)_$(3)_INSTALL_CMDS) + $$($(2)_$(4)_INSTALL_CMDS) endif endef
@@ -129,21 +130,26 @@ $$(BUILD_DIR)/docs/$(pkgname): $(pkgname)-rsync: $$(BUILD_DIR)/docs/$(pkgname) $$(Q)$$(call MESSAGE,"Preparing the $(pkgname) sources...") - $$(Q)rsync -a docs/$(pkgname)/ $$^ + $$(Q)rsync -a $(pkgdir) $$^ $(pkgname)-prepare-sources: $(pkgname)-rsync -$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),xhtml,html,html,HTML,\ +$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),xhtml,html,html,HTML,\ --xsltproc-opts "--stringparam toc.section.depth 1") -$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),chunked,split-html,chunked,split HTML,\ + +$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),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 GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),pdf,pdf,pdf,PDF,\ +$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),pdf,pdf,pdf,PDF,\ --dblatex-opts "-P latex.output.revhistory=0 -x '--maxvars 100000'") -$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),text,text,text,text) -$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),epub,epub,epub,ePUB) + +$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),text,text,text,text) + +$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),epub,epub,epub,ePUB) + clean: $(pkgname)-clean $(pkgname)-clean: $$(Q)$$(RM) -rf $$(BUILD_DIR)/docs/$(pkgname)
Signature · 1 line
1.9.1
PATCH v6 11/25 docs/manual: last pass at removing hard-coded path in GENDOC_INNER
Quoted 21 lines · Yann E. MORIN
GENDOC_INNERstill has one hard-coded path to the document's directory:
the asciidoc .conf files.Add a new argument to
GENDOC_INNERto pass the directory of the document.Notes:
- this makes for overly-long lines, but splitting is not possible, otherwise the first argument on the continuation line would get (at least) a leading space or tab, and that would break either or all of the variables names, the dependency rules, or the filenames we look for. A future patch will further clean this up (see: docs/asciidoc: call $(pkgname) and $(pkgdir) in a single place.)
- this means that another document would be missing our tweaks from asciidoc-text.conf to not render images and sanely render hyperlinks. But that was already the case anyway, since we were using docs/$(1)/ to search for that file. A further patch will allow us to have such configuration in a common place.
Quoted 3 lines
Signed-off-by "Yann E. MORIN" <[email protected]>Cc Samuel Martin <[email protected]>Cc Thomas De Schampheleire <[email protected]>
Signature · 1 line
Samuel
PATCH v6 12/25 docs/manual: properly separate rules specific for our manual
In reply to Yann E. MORINMove the rules specific to our own manual, so that they do not interfere with the generic rules of GENDOC.
Separate them with a shiny header. ;-)
--- docs/manual/manual.mk | 41 +++++++++++++++++++++++------------------ 1 file changed, 23 insertions(+), 18 deletions(-)
docs/manual/manual.mk +23 -18
@@ -1,14 +1,3 @@ -# Packages included in BR2_EXTERNAL are not part of buildroot, so they -# should not be included in the manual. -.PHONY: manual-update-lists -manual-update-lists: manual-check-dependencies-lists $(BUILD_DIR)/docs/$(pkgname) - $(Q)$(call MESSAGE,"Updating the manual lists...") - $(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(BUILD_DIR)/docs/$(pkgname) \ - BR2_EXTERNAL=$(TOPDIR)/support/dummy-external \ - python -B $(TOPDIR)/support/scripts/gen-manual-lists.py - -manual-prepare-sources: manual-update-lists - # we can't use suitable-host-package here because that's not available in # the context of 'make release' manual-check-dependencies:
@@ -28,13 +17,6 @@ manual-check-dependencies-pdf: exit 1; \ fi -manual-check-dependencies-lists: - $(Q)if ! python -c "import argparse" >/dev/null 2>&1 ; then \ - echo "You need python with argparse on your host to generate" \ - "the list of packages in the manual"; \ - 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:
@@ -156,6 +138,29 @@ $(pkgname)-clean: .PHONY: $(pkgname) $(pkgname)-clean endef +################################################################################ +# The Buildroot manual +################################################################################ + +# Our manual needs to generate lists +manual-prepare-sources: manual-update-lists + +# Packages included in BR2_EXTERNAL are not part of buildroot, so they +# should not be included in the manual. +.PHONY: manual-update-lists +manual-update-lists: manual-check-dependencies-lists $(BUILD_DIR)/docs/$(pkgname) + $(Q)$(call MESSAGE,"Updating the manual lists...") + $(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(BUILD_DIR)/docs/$(pkgname) \ + BR2_EXTERNAL=$(TOPDIR)/support/dummy-external \ + python -B $(TOPDIR)/support/scripts/gen-manual-lists.py + +manual-check-dependencies-lists: + $(Q)if ! python -c "import argparse" >/dev/null 2>&1 ; then \ + echo "You need python with argparse on your host to generate" \ + "the list of packages in the manual"; \ + exit 1; \ + fi + MANUAL_SOURCES = $(sort $(wildcard docs/manual/*.txt) $(wildcard docs/images/*)) MANUAL_RESOURCES = $(TOPDIR)/docs/images $(eval $(call GENDOC))
Signature · 1 line
1.9.1
PATCH v6 12/25 docs/manual: properly separate rules specific for our manual
Quoted 9 lines · Yann E. MORIN
Move the rules specific to our own manual, so that they do not interfere with the generic rules of GENDOC.
Separate them with a shiny header. ;-)
Signed-off-by "Yann E. MORIN" <[email protected]>Cc Samuel Martin <[email protected]>Cc Thomas De Schampheleire <[email protected]>
Signature · 1 line
Samuel
PATCH v6 13/25 docs/manual: rename the generic dependency rules
In reply to Yann E. MORINThose rules are generic, and not specific to our manual, we want them always called:
- manual-check-dependencies
- manual-check-dependencies-pdf
So, rename them to be generic to gendoc.
Cascade the document's dependency checking to call those rules, too.
--- docs/manual/manual.mk | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-)
docs/manual/manual.mk +6 -3
@@ -1,6 +1,6 @@ # we can't use suitable-host-package here because that's not available in # the context of 'make release' -manual-check-dependencies: +gendoc-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 a document"; \
@@ -11,7 +11,7 @@ manual-check-dependencies: exit 1; \ fi -manual-check-dependencies-pdf: +gendoc-check-dependencies-pdf: $(Q)if [ -z "`which dblatex 2>/dev/null`" ]; then \ echo "You need dblatex on your host to generate a PDF document"; \ exit 1; \
@@ -55,7 +55,10 @@ $(1): $(1)-$(5) .PHONY: $(1)-$(5) $(1)-$(5): $$(O)/docs/$(1)/$(1).$(6) -$(1)-check-dependencies-$(5): +$(1)-check-dependencies: gendoc-check-dependencies + +gendoc-check-dependencies-$(5): +$(1)-check-dependencies-$(5): gendoc-check-dependencies-$(5) $(2)_$(4)_ASCIIDOC_CONF = $(3)/asciidoc-$(4).conf ifneq ($$(wildcard $$($(2)_$(4)_ASCIIDOC_CONF)),)
Signature · 1 line
1.9.1
PATCH v6 14/25 docs/manual: allow documents to define some hooks, as for a package
In reply to Yann E. MORINAllow documents to define two hooks:
- DOC_CHECK_EXTRA_DEPENDENCIES_HOOKS
to check for extra dependencies required by this document
- DOC_CHECK_EXTRA_DEPENDENCIES_FMT_HOOKS
ditto, but for the specific format
- DOC_POST_EXTRACT_HOOKS:
to run additional actions to fill-in the build directory
(Replace 'DOC' with the uppercase name of the document, and 'FMT' with the format.)
This is supposed to replace the current use of overloading the internal dependency rules, and makes GENDOC behave yet a bit more like the package infrastructure.
Note that GENDOC_INNER already has the uppercase name as an argument, whereas GENDOC does not, so the two foreach loops are not exactly similar (for now.)
---
Changes v5 -> v6:
- do not use $$ for call to UPPERCASE (Thomas DS)
Changes v1 -> v2:
- call post-extract hook in rsync rule
--- docs/manual/manual.mk | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-)
docs/manual/manual.mk +8 -2
@@ -55,10 +55,10 @@ $(1): $(1)-$(5) .PHONY: $(1)-$(5) $(1)-$(5): $$(O)/docs/$(1)/$(1).$(6) -$(1)-check-dependencies: gendoc-check-dependencies - +# Single line, because splitting a foreach is not easy... gendoc-check-dependencies-$(5): $(1)-check-dependencies-$(5): gendoc-check-dependencies-$(5) + $$(Q)$$(foreach hook,$$($(2)_CHECK_DEPENDENCIES_$(call UPPERCASE,$(5))_HOOKS),$$(call $$(hook))$$(sep)) $(2)_$(4)_ASCIIDOC_CONF = $(3)/asciidoc-$(4).conf ifneq ($$(wildcard $$($(2)_$(4)_ASCIIDOC_CONF)),)
@@ -110,12 +110,18 @@ endef # resources, such as images, are located; must be an absolute path. ################################################################################ define GENDOC +# Single line, because splitting a foreach is not easy... +$(pkgname)-check-dependencies: gendoc-check-dependencies + $$(Q)$$(foreach hook,$$($(call UPPERCASE,$(pkgname))_CHECK_DEPENDENCIES_HOOKS),$$(call $$(hook))$$(sep)) + $$(BUILD_DIR)/docs/$(pkgname): $$(Q)mkdir -p $$@ +# Single line, because splitting a foreach is not easy... $(pkgname)-rsync: $$(BUILD_DIR)/docs/$(pkgname) $$(Q)$$(call MESSAGE,"Preparing the $(pkgname) sources...") $$(Q)rsync -a $(pkgdir) $$^ + $$(Q)$$(foreach hook,$$($(call UPPERCASE,$(pkgname))_POST_RSYNC_HOOKS),$$(call $$(hook))$$(sep)) $(pkgname)-prepare-sources: $(pkgname)-rsync
Signature · 1 line
1.9.1
PATCH v6 14/25 docs/manual: allow documents to define some hooks, as for a package
Quoted 19 lines · Yann E. MORIN
Allow documents to define two hooks:
-DOC_CHECK_EXTRA_DEPENDENCIES_HOOKS
to check for extra dependencies required by this document
-DOC_CHECK_EXTRA_DEPENDENCIES_FMT_HOOKS
ditto, but for the specific format
-DOC_POST_EXTRACT_HOOKS:
to run additional actions to fill-in the build directory(Replace 'DOC' with the uppercase name of the document, and 'FMT' with the format.)
This is supposed to replace the current use of overloading the internal dependency rules, and makes GENDOC behave yet a bit more like the package infrastructure.
Note that
GENDOC_INNERalready has the uppercase name as an argument, whereas GENDOC does not, so the two foreach loops are not exactly similar (for now.)
Quoted 9 lines
Signed-off-by "Yann E. MORIN" <[email protected]>Cc Samuel Martin <[email protected]>Cc Thomas De Schampheleire <[email protected]>Reviewed-by Samuel Martin <[email protected]>---
Changes v5 -> v6:
- do not use $$ for call to UPPERCASE (Thomas DS)
Here the same misunderstanding occurred. In these cases, I do think $$ should be used.
If the resulting patch is the same as v5, my Ack on that still counts.
PATCH v6 15/25 docs/manual: use the new hooks instead of gendoc rules
In reply to Yann E. MORINAlso reorder a bit the definition of the variables, to more resemble a package. Yet a bit more...
---
Changes v5 -> v6:
- hooks were renamed (Thomas DS)
- typo (Thomas DS)
--- docs/manual/manual.mk | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-)
docs/manual/manual.mk +10 -7
@@ -151,25 +151,28 @@ endef # The Buildroot manual ################################################################################ -# Our manual needs to generate lists -manual-prepare-sources: manual-update-lists +MANUAL_SOURCES = $(sort $(wildcard docs/manual/*.txt) $(wildcard docs/images/*)) +MANUAL_RESOURCES = $(TOPDIR)/docs/images +# Our manual needs to generate lists # Packages included in BR2_EXTERNAL are not part of buildroot, so they # should not be included in the manual. -.PHONY: manual-update-lists -manual-update-lists: manual-check-dependencies-lists $(BUILD_DIR)/docs/$(pkgname) +define MANUAL_GEN_LISTS $(Q)$(call MESSAGE,"Updating the manual lists...") $(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(BUILD_DIR)/docs/$(pkgname) \ BR2_EXTERNAL=$(TOPDIR)/support/dummy-external \ python -B $(TOPDIR)/support/scripts/gen-manual-lists.py +endef +MANUAL_POST_RSYNC_HOOKS += MANUAL_GEN_LISTS -manual-check-dependencies-lists: +# Our list-generating script requires argparse +define MANUAL_CHECK_LISTS_DEPS $(Q)if ! python -c "import argparse" >/dev/null 2>&1 ; then \ echo "You need python with argparse on your host to generate" \ "the list of packages in the manual"; \ exit 1; \ fi +endef +MANUAL_CHECK_DEPENDENCIES_HOOKS += MANUAL_CHECK_LISTS_DEPS -MANUAL_SOURCES = $(sort $(wildcard docs/manual/*.txt) $(wildcard docs/images/*)) -MANUAL_RESOURCES = $(TOPDIR)/docs/images $(eval $(call GENDOC))
Signature · 1 line
1.9.1
PATCH v6 15/25 docs/manual: use the new hooks instead of gendoc rules
Quoted 57 lines · Yann E. MORIN
Also reorder a bit the definition of the variables, to more resemble a package. Yet a bit more...
Signed-off-by "Yann E. MORIN" <[email protected]>Cc Samuel Martin <[email protected]>Cc Thomas De Schampheleire <[email protected]>Reviewed-by Samuel Martin <[email protected]>---
Changes v5 -> v6:
- hooks were renamed (Thomas DS)
- typo (Thomas DS)--- docs/manual/manual.mk | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-)docs/manual/manual.mk +10
-8@@ -151,25 +151,28 @@ endef # The Buildroot manual ################################################################################ -# Our manual needs to generate lists -manual-prepare-sources: manual-update-lists +MANUAL_SOURCES = $(sort $(wildcard docs/manual/*.txt) $(wildcard docs/images/*)) +MANUAL_RESOURCES = $(TOPDIR)/docs/images +# Our manual needs to generate lists # Packages included in BR2_EXTERNAL are not part of buildroot, so they # should not be included in the manual. -.PHONY: manual-update-lists -manual-update-lists: manual-check-dependencies-lists $(BUILD_DIR)/docs/$(pkgname) +define MANUAL_GEN_LISTS $(Q)$(call MESSAGE,"Updating the manual lists...") $(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(BUILD_DIR)/docs/$(pkgname) \ BR2_EXTERNAL=$(TOPDIR)/support/dummy-external \ python -B $(TOPDIR)/support/scripts/gen-manual-lists.py +endef +MANUAL_POST_RSYNC_HOOKS += MANUAL_GEN_LISTS -manual-check-dependencies-lists: +# Our list-generating script requires argparse +define MANUAL_CHECK_LISTS_DEPS $(Q)if ! python -c "import argparse" >/dev/null 2>&1 ; then \ echo "You need python with argparse on your host to generate" \ "the list of packages in the manual"; \ exit 1; \ fi +endef +MANUAL_CHECK_DEPENDENCIES_HOOKS += MANUAL_CHECK_LISTS_DEPS -MANUAL_SOURCES = $(sort $(wildcard docs/manual/*.txt) $(wildcard docs/images/*)) -MANUAL_RESOURCES = $(TOPDIR)/docs/images $(eval $(call GENDOC)) --
Quoted 2 lines
1.9.1
PATCH v6 16/25 docs/manual: always look for resources in destination directory
In reply to Yann E. MORINOur manual does not use external filters in asciidoc, so we are happy with just looking for resources from our source tree.
However, other documents (like ones in br2-external) may use such filters, to generate diagrams, graphs...
External filters generate their output files in the output directory, so we must also look for resources in there.
Note: external filters in asccidoc are used thus:
["filter-name"]
----
Text to be rendered
----In the future, our own manual may even make use of filters to include some of the graphs we generate, to store in the documentation.
---
Changes v5 -> v6:
- comment in the code the reason for -r (Thomas DS)
---
Note: this is to work around a deficiency (bug?) in asccidoc. Asciidoc actually tells the filter where to put the output files, but forgets to look in there when it needs to link to those files...
--- docs/manual/manual.mk | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)
docs/manual/manual.mk +3 -1
@@ -86,6 +86,8 @@ $$(O)/docs/$(1)/$(1).$(6): 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): $$($(call UPPERCASE,$(1))_SOURCES) \ $(1)-check-dependencies \ $(1)-check-dependencies-$(5) \
@@ -93,7 +95,7 @@ $$(O)/docs/$(1)/$(1).$(6): $$($(call UPPERCASE,$(1))_SOURCES) \ $$(Q)$$(call MESSAGE,"Generating $(7) $(1)...") $$(Q)mkdir -p $$(@D) $$(Q)a2x $(8) -f $(4) -d book -L \ - $$(foreach r,$$($(2)_RESOURCES),-r $$(r)) \ + $$(foreach r,$$($(2)_RESOURCES),-r $$(r)) -r $$(@D) \ $$($(2)_$(4)_A2X_OPTS) \ --asciidoc-opts="$$($(2)_$(4)_ASCIIDOC_OPTS)" \ $$(BUILD_DIR)/docs/$(1)/$(1).txt
Signature · 1 line
1.9.1
PATCH v6 16/25 docs/manual: always look for resources in destination directory
Quoted 15 lines · Yann E. MORIN
Our manual does not use external filters in asciidoc, so we are happy with just looking for resources from our source tree.
However, other documents (like ones in br2-external) may use such filters, to generate diagrams, graphs...
External filters generate their output files in the output directory, so we must also look for resources in there.
Note: external filters in asccidoc are used thus:
["filter-name"] ---- Text to be rendered ----
Quoted 8 lines
In the future, our own manual may even make use of filters to include some of the graphs we generate, to store in the documentation.
Signed-off-by "Yann E. MORIN" <[email protected]>Cc Samuel Martin <[email protected]>Cc Thomas De Schampheleire <[email protected]>Reviewed-by Samuel Martin <[email protected]>
PATCH v6 17/25 docs: separate the GENDOC infra from our manual definition
In reply to Yann E. MORINMove the GENDOC infra to its own file, so it is even less tied to our manual document, so that it is more obvious that GENDOC is an infra like our packages infras, and 'manual' is a document like we have packages.
Ideally, this new file should better go in docs/ rather than in package/ . However, docs/ is already full of our website stuff, so adding it in there would just serve to clutter the website.
So, let's just put alongside the other infrastructures, in package/ .
--- Makefile | 1 + docs/manual/manual.mk | 151 -------------------------------------------------- package/gendoc.mk | 150 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 151 insertions(+), 151 deletions(-) create mode 100644 package/gendoc.mk
Makefile +1 -0
@@ -272,6 +272,7 @@ unexport DESTDIR unexport RUBYOPT include package/pkg-utils.mk +include package/gendoc.mk ifeq ($(BR2_HAVE_DOT_CONFIG),y)
docs/manual/manual.mk +0 -151
154 lines not on this page · raw message
package/gendoc.mk new file +150 -0
150 lines not on this page · raw message
Signature · 1 line
1.9.1
PATCH v6 17/25 docs: separate the GENDOC infra from our manual definition
Quoted 8 lines · Yann E. MORIN
Move the GENDOC infra to its own file, so it is even less tied to our manual document, so that it is more obvious that GENDOC is an infra like our packages infras, and 'manual' is a document like we have packages.
Ideally, this new file should better go in docs/ rather than in package/ . However, docs/ is already full of our website stuff, so adding it in there would just serve to clutter the website.
Quoted 6 lines
So, let's just put alongside the other infrastructures, in package/ .
Signed-off-by "Yann E. MORIN" <[email protected]>Cc Samuel Martin <[email protected]>Cc Thomas De Schampheleire <[email protected]>
Signature · 1 line
Samuel
PATCH v6 18/25 docs: rename the GENDOC infrastructure
In reply to Yann E. MORINRename the GENDOC infrastructure so that it more closely matches the way we handle the packages infras.
---
Chamges v5 -> v6:
- fix typo: s/asiciidoc/asciidoc/
---
Makefile | 2 +-
docs/manual/manual.mk | 2 +-
package/{gendoc.mk => doc-asciidoc.mk} | 36 ++++++++++++++++++++--------------
3 files changed, 23 insertions(+), 17 deletions(-)
rename package/{gendoc.mk => doc-asciidoc.mk} (81%)Makefile +1 -1
@@ -272,7 +272,7 @@ unexport DESTDIR unexport RUBYOPT include package/pkg-utils.mk -include package/gendoc.mk +include package/doc-asciidoc.mk ifeq ($(BR2_HAVE_DOT_CONFIG),y)
docs/manual/manual.mk +1 -1
@@ -26,4 +26,4 @@ define MANUAL_CHECK_LISTS_DEPS endef MANUAL_CHECK_DEPENDENCIES_HOOKS += MANUAL_CHECK_LISTS_DEPS -$(eval $(call GENDOC)) +$(eval $(call asciidoc-document))
package/doc-asciidoc.mk renamed from package/gendoc.mk +21 -15
@@ -1,6 +1,6 @@ # we can't use suitable-host-package here because that's not available in # the context of 'make release' -gendoc-check-dependencies: +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 a document"; \
@@ -11,7 +11,7 @@ gendoc-check-dependencies: exit 1; \ fi -gendoc-check-dependencies-pdf: +asciidoc-check-dependencies-pdf: $(Q)if [ -z "`which dblatex 2>/dev/null`" ]; then \ echo "You need dblatex on your host to generate a PDF document"; \ exit 1; \
@@ -32,8 +32,8 @@ GENDOC_XSLTPROC_IS_BROKEN = \ $(shell xsltproc --maxvars 0 >/dev/null 2>/dev/null || echo y) ################################################################################ -# GENDOC_INNER -- generates the make targets needed to build a specific type of -# asciidoc documentation. +# 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
@@ -50,14 +50,14 @@ GENDOC_XSLTPROC_IS_BROKEN = \ # Since this function will be called from within an $(eval ...) # all variable references except the arguments must be $$-quoted. ################################################################################ -define GENDOC_INNER +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... -gendoc-check-dependencies-$(5): -$(1)-check-dependencies-$(5): gendoc-check-dependencies-$(5) +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)) $(2)_$(4)_ASCIIDOC_CONF = $(3)/asciidoc-$(4).conf
@@ -105,15 +105,15 @@ endif endef ################################################################################ -# GENDOC -- generates the make targets needed to build asciidoc documentation. +# ASCIIDOC -- generates the make targets needed to build asciidoc documentation. # # 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 GENDOC +define ASCIIDOC # Single line, because splitting a foreach is not easy... -$(pkgname)-check-dependencies: gendoc-check-dependencies +$(pkgname)-check-dependencies: asciidoc-check-dependencies $$(Q)$$(foreach hook,$$($(call UPPERCASE,$(pkgname))_CHECK_DEPENDENCIES_HOOKS),$$(call $$(hook))$$(sep)) $$(BUILD_DIR)/docs/$(pkgname):
@@ -127,24 +127,30 @@ $(pkgname)-rsync: $$(BUILD_DIR)/docs/$(pkgname) $(pkgname)-prepare-sources: $(pkgname)-rsync -$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),xhtml,html,html,HTML,\ +$(call ASCIIDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),xhtml,html,html,HTML,\ --xsltproc-opts "--stringparam toc.section.depth 1") -$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),chunked,split-html,chunked,split HTML,\ +$(call ASCIIDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),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 GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),pdf,pdf,pdf,PDF,\ +$(call ASCIIDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),pdf,pdf,pdf,PDF,\ --dblatex-opts "-P latex.output.revhistory=0 -x '--maxvars 100000'") -$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),text,text,text,text) +$(call ASCIIDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),text,text,text,text) -$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),epub,epub,epub,ePUB) +$(call ASCIIDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),epub,epub,epub,ePUB) clean: $(pkgname)-clean $(pkgname)-clean: $$(Q)$$(RM) -rf $$(BUILD_DIR)/docs/$(pkgname) .PHONY: $(pkgname) $(pkgname)-clean endef + +################################################################################ +# asciidoc-document -- the target generator macro for asciidoc documents +################################################################################ + +asciidoc-document = $(call ASCIIDOC)
Signature · 1 line
1.9.1
PATCH v6 18/25 docs: rename the GENDOC infrastructure
Quoted 7 lines · Yann E. MORIN
Rename the GENDOC infrastructure so that it more closely matches the way we handle the packages infras.
Signed-off-by "Yann E. MORIN" <[email protected]>Cc Samuel Martin <[email protected]>Cc Thomas De Schampheleire <[email protected]>Reviewed-by Samuel Martin <[email protected]>
PATCH v6 19/25 docs/asciidoc: call $(pkgname) and $(pkgdir) in a single place
In reply to Yann E. MORINLike for all the package infrastructures, retrieve the package name and directory in the front-end macro-variable, rather than everywhere in the backend macro.
This allows us to clean up the ASCIIDOC macro, by removing all the calls to $(pkgname) and $(pkgdir), and to UPPERCASE (which made the macro a bit difficult to read.)
---
Chamges v5 -> v6:
- convert forgotten occurence of $(pkgname) (Thomas DS)
--- package/doc-asciidoc.mk | 41 +++++++++++++++++++++++------------------ 1 file changed, 23 insertions(+), 18 deletions(-)
package/doc-asciidoc.mk +23 -18
@@ -107,50 +107,55 @@ 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... -$(pkgname)-check-dependencies: asciidoc-check-dependencies - $$(Q)$$(foreach hook,$$($(call UPPERCASE,$(pkgname))_CHECK_DEPENDENCIES_HOOKS),$$(call $$(hook))$$(sep)) +$(1)-check-dependencies: asciidoc-check-dependencies + $$(Q)$$(foreach hook,$$($(2)_CHECK_DEPENDENCIES_HOOKS),$$(call $$(hook))$$(sep)) -$$(BUILD_DIR)/docs/$(pkgname): +$$(BUILD_DIR)/docs/$(1): $$(Q)mkdir -p $$@ # Single line, because splitting a foreach is not easy... -$(pkgname)-rsync: $$(BUILD_DIR)/docs/$(pkgname) - $$(Q)$$(call MESSAGE,"Preparing the $(pkgname) sources...") - $$(Q)rsync -a $(pkgdir) $$^ - $$(Q)$$(foreach hook,$$($(call UPPERCASE,$(pkgname))_POST_RSYNC_HOOKS),$$(call $$(hook))$$(sep)) +$(1)-rsync: $$(BUILD_DIR)/docs/$(1) + $$(Q)$$(call MESSAGE,"Preparing the $(1) sources...") + $$(Q)rsync -a $(3) $$^ + $$(Q)$$(foreach hook,$$($(2)_POST_RSYNC_HOOKS),$$(call $$(hook))$$(sep)) -$(pkgname)-prepare-sources: $(pkgname)-rsync +$(1)-prepare-sources: $(1)-rsync -$(call ASCIIDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),xhtml,html,html,HTML,\ +$(call ASCIIDOC_INNER,$(1),$(2),$(3),xhtml,html,html,HTML,\ --xsltproc-opts "--stringparam toc.section.depth 1") -$(call ASCIIDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),chunked,split-html,chunked,split HTML,\ +$(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,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),pdf,pdf,pdf,PDF,\ +$(call ASCIIDOC_INNER,$(1),$(2),$(3),pdf,pdf,pdf,PDF,\ --dblatex-opts "-P latex.output.revhistory=0 -x '--maxvars 100000'") -$(call ASCIIDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),text,text,text,text) +$(call ASCIIDOC_INNER,$(1),$(2),$(3),text,text,text,text) -$(call ASCIIDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),epub,epub,epub,ePUB) +$(call ASCIIDOC_INNER,$(1),$(2),$(3),epub,epub,epub,ePUB) -clean: $(pkgname)-clean -$(pkgname)-clean: - $$(Q)$$(RM) -rf $$(BUILD_DIR)/docs/$(pkgname) -.PHONY: $(pkgname) $(pkgname)-clean +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) +asciidoc-document = $(call ASCIIDOC,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir))
Signature · 1 line
1.9.1
PATCH v6 19/25 docs/asciidoc: call $(pkgname) and $(pkgdir) in a single place
Quoted 4 lines · Yann E. MORIN
Like for all the package infrastructures, retrieve the package name and directory in the front-end macro-variable, rather than everywhere in the backend macro.
Quoted 9 lines
This allows us to clean up the ASCIIDOC macro, by removing all the calls to $(pkgname) and $(pkgdir), and to UPPERCASE (which made the macro a bit difficult to read.)
Signed-off-by "Yann E. MORIN" <[email protected]>Cc Samuel Martin <[email protected]>Cc Thomas De Schampheleire <[email protected]>Reviewed-by Samuel Martin <[email protected]>
PATCH v6 20/25 docs/asciidoc: make it possible to use $(@D) in hooks
In reply to Yann E. MORINCurrently, it is not possible to use $(@D) in documents' hooks, because there is no actual target file for the copying rule.
So, use the same mechanism as for generic-package.
We do not touch the target file, so it is easy to regenerate the manual without calling the -clean rule first.
--- docs/manual/manual.mk | 2 +- package/doc-asciidoc.mk | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-)
docs/manual/manual.mk +1 -1
@@ -10,7 +10,7 @@ MANUAL_RESOURCES = $(TOPDIR)/docs/images # should not be included in the manual. define MANUAL_GEN_LISTS $(Q)$(call MESSAGE,"Updating the manual lists...") - $(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(BUILD_DIR)/docs/$(pkgname) \ + $(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(@D) \ BR2_EXTERNAL=$(TOPDIR)/support/dummy-external \ python -B $(TOPDIR)/support/scripts/gen-manual-lists.py endef
package/doc-asciidoc.mk +6 -6
@@ -121,16 +121,16 @@ define ASCIIDOC $(1)-check-dependencies: asciidoc-check-dependencies $$(Q)$$(foreach hook,$$($(2)_CHECK_DEPENDENCIES_HOOKS),$$(call $$(hook))$$(sep)) -$$(BUILD_DIR)/docs/$(1): - $$(Q)mkdir -p $$@ - # Single line, because splitting a foreach is not easy... -$(1)-rsync: $$(BUILD_DIR)/docs/$(1) +# 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)rsync -a $(3) $$^ + $$(Q)mkdir -p $$(@D) + $$(Q)rsync -a $(3) $$(@D) $$(Q)$$(foreach hook,$$($(2)_POST_RSYNC_HOOKS),$$(call $$(hook))$$(sep)) -$(1)-prepare-sources: $(1)-rsync +$(1)-prepare-sources: $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced $(call ASCIIDOC_INNER,$(1),$(2),$(3),xhtml,html,html,HTML,\ --xsltproc-opts "--stringparam toc.section.depth 1")
Signature · 1 line
1.9.1
PATCH v6 20/25 docs/asciidoc: make it possible to use $(@D) in hooks
Quoted 5 lines · Yann E. MORIN
Currently, it is not possible to use $(@D) in documents' hooks, because there is no actual target file for the copying rule.
So, use the same mechanism as for generic-package.
Quoted 7 lines
We do not touch the target file, so it is easy to regenerate the manual without calling the -clean rule first.
Signed-off-by "Yann E. MORIN" <[email protected]>Cc Samuel Martin <[email protected]>Cc Thomas De Schampheleire <[email protected]>Reviewed-by Samuel Martin <[email protected]>
PATCH v6 21/25 doc/asciidoc: allow documents to pass a global asciidoc configuration
In reply to Yann E. MORINCurrently, a document can specify an output-specific configuration, like the text output, that hides images references, and formats hyperlinks.
But sometime it is required that a specific configuration is used for all the output formats, to always apply the same markup rules in all documents (like using the [specialwords] section.)
Also look for a file named 'asciidoc.conf' in the document's directory. If that file exists, add it to the asciidoc options (before the output-specific config, so the former takes precedence over the latter.)
--- package/doc-asciidoc.mk | 6 ++++++ 1 file changed, 6 insertions(+)
package/doc-asciidoc.mk +6 -0
@@ -60,6 +60,10 @@ 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)) +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)
@@ -132,6 +136,8 @@ $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced: $(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")
Signature · 1 line
1.9.1
PATCH v6 21/25 doc/asciidoc: allow documents to pass a global asciidoc configuration
Yann,
Quoted 10 lines · Yann E. MORIN
Currently, a document can specify an output-specific configuration, like the text output, that hides images references, and formats hyperlinks.
But sometime it is required that a specific configuration is used for all the output formats, to always apply the same markup rules in all documents (like using the [specialwords] section.)
Also look for a file named 'asciidoc.conf' in the document's directory. If that file exists, add it to the asciidoc options (before the output-specific config, so the former takes precedence over the latter.)
It is the other way around, no?
(the output-specific config taking precedence over/overriding the sections defined in the global one)
Quoted 33 lines
Signed-off-by "Yann E. MORIN" <[email protected]>Cc Samuel Martin <[email protected]>Cc Thomas De Schampheleire <[email protected]>--- package/doc-asciidoc.mk | 6 ++++++ 1 file changed, 6 insertions(+)package/doc-asciidoc.mk +6
-1@@ -60,6 +60,10 @@ 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)) +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)@@ -132,6 +136,8 @@ $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced: $(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") --
Quoted 2 lines
1.9.1
Regards,
Signature · 1 line
Samuel
PATCH v6 21/25 doc/asciidoc: allow documents to pass a global asciidoc configuration
Samuel, All,
On 2014-09-27 13:20 +0200, Samuel Martin spake thusly:
Quoted 8 lines · Yann E. MORIN
Quoted 7 lines
Currently, a document can specify an output-specific configuration, like the text output, that hides images references, and formats hyperlinks.
But sometime it is required that a specific configuration is used for all the output formats, to always apply the same markup rules in all documents (like using the [specialwords] section.)
Quoted 7 lines
Quoted 3 lines
Also look for a file named 'asciidoc.conf' in the document's directory. If that file exists, add it to the asciidoc options (before the output-specific config, so the former takes precedence over the latter.)
It is the other way around, no?
(the output-specific config taking precedence over/overriding the sections defined in the global one)
Yes indeed; the commit log is backward. Fixed.
Thanks.
Regards,
Yann E. MORIN.
Signature · 6 lines
.-----------------.--------------------.------------------.--------------------. | Yann E. MORIN | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: | | +33 662 376 056 | Software Designer | \ / CAMPAIGN | ___ | | +33 223 225 172 `------------.-------: X AGAINST | \e/ There is no | | http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL | v conspiracy. | '------------------------------^-------^------------------^--------------------'
PATCH v6 21/25 doc/asciidoc: allow documents to pass a global asciidoc configuration
In reply to Yann E. MORINQuoted 4 lines · Yann E. MORIN
Currently, a document can specify an output-specific configuration, like the text output, that hides images references, and formats hyperlinks.
But sometime it is required that a specific configuration is used for
sometimes
Quoted 10 lines
all the output formats, to always apply the same markup rules in all documents (like using the [specialwords] section.)
Also look for a file named 'asciidoc.conf' in the document's directory. If that file exists, add it to the asciidoc options (before the output-specific config, so the former takes precedence over the latter.)
Signed-off-by "Yann E. MORIN" <[email protected]>Cc Samuel Martin <[email protected]>Cc Thomas De Schampheleire <[email protected]>
Aside from the above commit message change + the commit message change indicated by Samuel:
PATCH v6 22/25 doc/asciidoc: always apply Buildroot's AsciiDoc config
In reply to Yann E. MORINAs 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.
---
docs/{manual => conf}/asciidoc-text.conf | 0
package/doc-asciidoc.mk | 12 ++++++++++++
2 files changed, 12 insertions(+)
rename docs/{manual => conf}/asciidoc-text.conf (100%)docs/conf/asciidoc-text.conf renamed from docs/manual/asciidoc-text.conf +0 -0
package/doc-asciidoc.mk +12 -0
@@ -60,10 +60,21 @@ 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 output-specific Asciidoc configuration: first, Buildroot's +# configuration, then the document's configuration +ifneq ($$(wildcard $$($(2)_ASCIIDOC_BR_CONF)),) +$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_ASCIIDOC_BR_CONF) +endif ifneq ($$(wildcard $$($(2)_ASCIIDOC_CONF)),) $(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_ASCIIDOC_CONF) endif +# Include output-specific Asciidoc configuration: first, Buildroot's +# configuration, then the document's configuration +$(2)_$(4)_ASCIIDOC_BR_CONF = docs/conf/asciidoc-$(4).conf +ifneq ($$(wildcard $$($(2)_$(4)_ASCIIDOC_BR_CONF)),) +$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_$(4)_ASCIIDOC_BR_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)
@@ -136,6 +147,7 @@ $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced: $(1)-prepare-sources: $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced +$(2)_ASCIIDOC_BR_CONF = docs/conf/asciidoc.conf $(2)_ASCIIDOC_CONF = $(3)/asciidoc.conf $(call ASCIIDOC_INNER,$(1),$(2),$(3),xhtml,html,html,HTML,\
Signature · 1 line
1.9.1
PATCH v6 22/25 doc/asciidoc: always apply Buildroot's AsciiDoc config
Yann,
Quoted 55 lines · Yann E. MORIN
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" <[email protected]>Cc Samuel Martin <[email protected]>Cc Thomas De Schampheleire <[email protected]>--- docs/{manual => conf}/asciidoc-text.conf | 0 package/doc-asciidoc.mk | 12 ++++++++++++ 2 files changed, 12 insertions(+) rename docs/{manual => conf}/asciidoc-text.conf (100%)docs/conf/asciidoc-text.conf renamed from docs/manual/asciidoc-text.conf +0
-0package/doc-asciidoc.mk +11
-0@@ -60,10 +60,21 @@ 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 output-specific Asciidoc configuration: first, Buildroot's +# configuration, then the document's configuration +ifneq ($$(wildcard $$($(2)_ASCIIDOC_BR_CONF)),) +$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_ASCIIDOC_BR_CONF) +endif ifneq ($$(wildcard $$($(2)_ASCIIDOC_CONF)),) $(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_ASCIIDOC_CONF) endif +# Include output-specific Asciidoc configuration: first, Buildroot's +# configuration, then the document's configuration +$(2)_$(4)_ASCIIDOC_BR_CONF = docs/conf/asciidoc-$(4).conf +ifneq ($$(wildcard $$($(2)_$(4)_ASCIIDOC_BR_CONF)),) +$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_$(4)_ASCIIDOC_BR_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)
package/doc-asciidoc.mk $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced: · line 151
Quoted 5 lines
package/doc-asciidoc.mk +1
-0@@ -136,6 +147,7 @@ $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced: $(1)-prepare-sources: $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced +$(2)_ASCIIDOC_BR_CONF = docs/conf/asciidoc.conf $(2)_ASCIIDOC_CONF = $(3)/asciidoc.conf
It's a bit odd to have *_ASCIIDOC{,_BR}_CONF definitions after using them, whereas teh output-specific config file is defined just before using it.
Anyway, it has no impact on the behavior of the infra, so:
Signature · 1 line
Samuel
PATCH v6 22/25 doc/asciidoc: always apply Buildroot's AsciiDoc config
Samuel, All,
On 2014-09-27 13:21 +0200, Samuel Martin spake thusly:
Quoted 1 line · Yann E. MORIN
[--SNIP--]
Quoted 20 lines
Quoted 20 lines
package/doc-asciidoc.mk +11
-0+# Include output-specific Asciidoc configuration: first, Buildroot's +# configuration, then the document's configuration +ifneq ($$(wildcard $$($(2)_ASCIIDOC_BR_CONF)),) +$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_ASCIIDOC_BR_CONF) +endif ifneq ($$(wildcard $$($(2)_ASCIIDOC_CONF)),) $(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_ASCIIDOC_CONF) endif +# Include output-specific Asciidoc configuration: first, Buildroot's +# configuration, then the document's configuration +$(2)_$(4)_ASCIIDOC_BR_CONF = docs/conf/asciidoc-$(4).conf +ifneq ($$(wildcard $$($(2)_$(4)_ASCIIDOC_BR_CONF)),) +$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_$(4)_ASCIIDOC_BR_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)@@ -136,6 +147,7 @@ $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced:
Quoted 8 lines
package/doc-asciidoc.mk $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced: · line 151
Quoted 4 lines
package/doc-asciidoc.mk +1
-0$(1)-prepare-sources: $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced +$(2)_ASCIIDOC_BR_CONF = docs/conf/asciidoc.conf $(2)_ASCIIDOC_CONF = $(3)/asciidoc.confIt's a bit odd to have *_ASCIIDOC{,_BR}_CONF definitions after using them, whereas teh output-specific config file is defined just before using it.
That's because the definitions of $(2)_ASCIIDOC_CONF and $(2)_ASCIIDOC_BR_CONF are common to all of that document, so we define them in ASCIIDOC, not _INNER, or they'd be redefined every time _INNER is expanded.
OTOH, the $(2)_$(4)_ASCIIDOC_CONF and $(2)_$(4)_ASCIIDOC_BR_CONF are different for each output type, so they only get defined in _INNER.
Quoted 1 line
Anyway, it has no impact on the behavior of the infra, so:
No impact on the behaviour, indeed, but no need to redefine the same variable to the same value over-and-over again (well, just 5 times, but still.)
Quoted 1 line
Reviewed-by Samuel Martin <[email protected]>
Thanks! :-)
Regards,
Yann E. MORIN.
Signature · 6 lines
.-----------------.--------------------.------------------.--------------------. | Yann E. MORIN | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: | | +33 662 376 056 | Software Designer | \ / CAMPAIGN | ___ | | +33 223 225 172 `------------.-------: X AGAINST | \e/ There is no | | http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL | v conspiracy. | '------------------------------^-------^------------------^--------------------'
PATCH v6 22/25 doc/asciidoc: always apply Buildroot's AsciiDoc config
In reply to Yann E. MORINHi Yann,
Quoted 41 lines · Yann E. MORIN
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" <[email protected]>Cc Samuel Martin <[email protected]>Cc Thomas De Schampheleire <[email protected]>--- docs/{manual => conf}/asciidoc-text.conf | 0 package/doc-asciidoc.mk | 12 ++++++++++++ 2 files changed, 12 insertions(+) rename docs/{manual => conf}/asciidoc-text.conf (100%)docs/conf/asciidoc-text.conf renamed from docs/manual/asciidoc-text.conf +0
-0package/doc-asciidoc.mk +5
-0@@ -60,10 +60,21 @@ 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 output-specific Asciidoc configuration: first, Buildroot's +# configuration, then the document's configuration +ifneq ($$(wildcard $$($(2)_ASCIIDOC_BR_CONF)),) +$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_ASCIIDOC_BR_CONF) +endif
package/doc-asciidoc.mk asciidoc-check-dependencies-$(5): · line 77
Quoted 10 lines
package/doc-asciidoc.mk +6
-0ifneq ($$(wildcard $$($(2)_ASCIIDOC_CONF)),) $(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_ASCIIDOC_CONF) endif +# Include output-specific Asciidoc configuration: first, Buildroot's +# configuration, then the document's configuration +$(2)_$(4)_ASCIIDOC_BR_CONF = docs/conf/asciidoc-$(4).conf +ifneq ($$(wildcard $$($(2)_$(4)_ASCIIDOC_BR_CONF)),) +$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_$(4)_ASCIIDOC_BR_CONF) +endif
The above two snippets almost are the same and at first I thought this was a merge/rebase issue.
In fact, one of the comments should change.
Moreover, I have been staring at this patch for several minutes to verify if I misunderstood something. The confusing thing is that variable $(2)_ASCIIDOC_BR_CONF, which can expand to MANUAL_ASCIIDOC_BR_CONF or SOMEDOC_ASCIIDOC_BR_CONF will both contain the same common value docs/conf/asciidoc.conf, while the name of the variable suggests that it is document-specific.
Strictly speaking, you have following levels:
- buildroot conf for all formats
- buildroot conf for a specific format
- <doc> conf for all formats
- <doc> conf for a specific format
Currently, the variables mapped on this are (respectively)
$(2)_ASCIIDOC_BR_CONF
$(2)_$(4)_ASCIIDOC_BR_CONF
$(2)_ASCIIDOC_CONF
$(2)_$(4)_ASCIIDOC_CONF
while I would find it more logical to have:
BR_ASCIIDOC_CONF
BR_$(4)_ASCIIDOC_CONF
$(2)_ASCIIDOC_CONF
$(2)_$(4)_ASCIIDOC_CONF
Best regards,
Thomas
PATCH v6 22/25 doc/asciidoc: always apply Buildroot's AsciiDoc config
Thomas, All,
On 2014-10-02 12:17 +0200, Thomas De Schampheleire spake thusly:
Quoted 4 lines · Yann E. MORIN
Quoted 3 lines
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.
[--SNIP--]
Quoted 9 lines
Quoted 9 lines
package/doc-asciidoc.mk +5
-0+# Include output-specific Asciidoc configuration: first, Buildroot's +# configuration, then the document's configuration +ifneq ($$(wildcard $$($(2)_ASCIIDOC_BR_CONF)),) +$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_ASCIIDOC_BR_CONF) +endif ifneq ($$(wildcard $$($(2)_ASCIIDOC_CONF)),) $(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_ASCIIDOC_CONF) endif
Quoted 10 lines
package/doc-asciidoc.mk asciidoc-check-dependencies-$(5): · line 77
Quoted 6 lines
package/doc-asciidoc.mk +6
-0+# Include output-specific Asciidoc configuration: first, Buildroot's +# configuration, then the document's configuration +$(2)_$(4)_ASCIIDOC_BR_CONF = docs/conf/asciidoc-$(4).conf +ifneq ($$(wildcard $$($(2)_$(4)_ASCIIDOC_BR_CONF)),) +$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_$(4)_ASCIIDOC_BR_CONF) +endifThe above two snippets almost are the same and at first I thought this was a merge/rebase issue.
In fact, one of the comments should change.
Yup, 'output-specifc' is superfluous in first comment.
Quoted 21 lines
Moreover, I have been staring at this patch for several minutes to verify if I misunderstood something. The confusing thing is that variable $(2)_ASCIIDOC_BR_CONF, which can expand to
MANUAL_ASCIIDOC_BR_CONForSOMEDOC_ASCIIDOC_BR_CONFwill both contain the same common valuedocs/conf/asciidoc.conf, while the name of the variable suggests that it is document-specific.Strictly speaking, you have following levels:
- buildroot conf for all formats
- buildroot conf for a specific format
- <doc> conf for all formats
- <doc> conf for a specific formatCurrently, the variables mapped on this are (respectively)
$(2)_ASCIIDOC_BR_CONF
$(2)_$(4)_ASCIIDOC_BR_CONF
$(2)_ASCIIDOC_CONF
$(2)_$(4)_ASCIIDOC_CONF
Quoted 6 lines
while I would find it more logical to have:
BR_ASCIIDOC_CONF
BR_$(4)_ASCIIDOC_CONF
$(2)_ASCIIDOC_CONF
$(2)_$(4)_ASCIIDOC_CONF
I've reworked that patch to account for your comments, and include the configuration filers in the order you suggest above.
It is indeed much better. Thank you!
Regards,
Yann E. MORIN.
Signature · 6 lines
.-----------------.--------------------.------------------.--------------------. | Yann E. MORIN | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: | | +33 662 376 056 | Software Designer | \ / CAMPAIGN | ___ | | +33 223 225 172 `------------.-------: X AGAINST | \e/ There is no | | http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL | v conspiracy. | '------------------------------^-------^------------------^--------------------'
PATCH v6 23/25 doc/asciidoc: always use UTC
In reply to Yann E. MORINCurrently, 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 doign the rendering.
--- package/doc-asciidoc.mk | 2 ++ 1 file changed, 2 insertions(+)
package/doc-asciidoc.mk +2 -0
@@ -93,6 +93,8 @@ define $(2)_$(4)_INSTALL_CMDS 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 \
Signature · 1 line
1.9.1
PATCH v6 23/25 doc/asciidoc: always use UTC
Quoted 5 lines · Yann E. MORIN
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.)
Quoted 8 lines
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 doign the
doing
Quoted 23 lines
rendering.
Signed-off-by "Yann E. MORIN" <[email protected]>Cc Samuel Martin <[email protected]>Cc Thomas De Schampheleire <[email protected]>--- package/doc-asciidoc.mk | 2 ++ 1 file changed, 2 insertions(+)package/doc-asciidoc.mk +2
-1@@ -93,6 +93,8 @@ define $(2)_$(4)_INSTALL_CMDS 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 \ --
Quoted 2 lines
1.9.1
Although I don't mind such a change, I fail to understand the use case here. Is this only regarding the printed date at the beginning of the manual?
With the typo in the commit msg fixed:
PATCH v6 23/25 doc/asciidoc: always use UTC
Thomas, All,
On 2014-10-02 12:21 +0200, Thomas De Schampheleire spake thusly:
Quoted 1 line · Yann E. MORIN
[--SNIP--]
Quoted 4 lines
Quoted 2 lines
Just force the timezone to be UTC when doing the rendering of the manual, so we are not dependent on the machine or user doign the
doing
Fixed.
Quoted 17 lines
Quoted 17 lines
rendering.
Signed-off-by "Yann E. MORIN" <[email protected]>Cc Samuel Martin <[email protected]>Cc Thomas De Schampheleire <[email protected]>--- package/doc-asciidoc.mk | 2 ++ 1 file changed, 2 insertions(+)package/doc-asciidoc.mk +0
-0@@ -93,6 +93,8 @@ define $(2)_$(4)_INSTALL_CMDS endef endif
Quoted 12 lines
Quoted 8 lines
package/doc-asciidoc.mk +2
-1+$$(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 \ --1.9.1
Although I don't mind such a change, I fail to understand the use case here. Is this only regarding the printed date at the beginning of the manual?
Yes, that's about that. What bothers me is potential for inconsistency. Also, for something that is world-readable, I usually prefer to read dates that are not tainted by any local, user-specific timezone. UTC is a the reference time, so I believe it is better lookign to see UTC than any other timezone.
Indeed, it's just a trivial (as in: not important) change.
Thanks! :-)
Regards,
Yann E. MORIN.
Signature · 6 lines
.-----------------.--------------------.------------------.--------------------. | Yann E. MORIN | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: | | +33 662 376 056 | Software Designer | \ / CAMPAIGN | ___ | | +33 223 225 172 `------------.-------: X AGAINST | \e/ There is no | | http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL | v conspiracy. | '------------------------------^-------^------------------^--------------------'
PATCH v6 24/25 Makefile: enable generating documents from br2-external
In reply to Yann E. MORINCurrently, the only way br2-external may generate a document is by including that document's recipe from within external.mk.
But external.mk is only parsed when the tree is configured.
This is unlike our internal document (the manual) which can be generated from within an unconfigured tree.
So, include the documents from br2-external at the same time we include our own document:
- expect the same layout as we have: docs/DOC_NAME/doc-name.mk
- do not fail if there is no document: use "-include", not "include"
--- Makefile | 1 + 1 file changed, 1 insertion(+)
Makefile +1 -0
@@ -934,5 +934,6 @@ print-version: @echo $(BR2_VERSION_FULL) include docs/manual/manual.mk +-include $(BR2_EXTERNAL)/docs/*/*.mk .PHONY: $(noconfig_targets)
Signature · 1 line
1.9.1
PATCH v6 25/25 docs/manual: document the asciidoc infra
In reply to Yann E. MORIN---
Chamges v5 -> v6:
- fix names of hooks
- remove trailing spaces
--- docs/manual/adding-packages-asciidoc.txt | 119 +++++++++++++++++++++++++++++++ docs/manual/adding-packages.txt | 2 + 2 files changed, 121 insertions(+) create mode 100644 docs/manual/adding-packages-asciidoc.txt
docs/manual/adding-packages-asciidoc.txt new file +119 -0
@@ -0,0 +1,119 @@ +// -*- mode:doc; -*- +// vim: syntax=asciidoc + +=== Infrastructure for asciidoc documents + +[[asciidoc-documents-tutorial]] + +The Buildroot manual, which you are currently reading, is entirely written +using the http://asciidoc.org/[AsciiDoc] mark-up syntax. The manual is then +rendered to many formats: + +* html +* split-html +* pdf +* epub +* text + +Although Buildroot only contains one document written in AsciiDoc, there +is, as for packages, an infrastructure for rendering documents using the +AsciiDoc syntax. + +Also as for packages, the AsciiDoc infrastructure is available from +xref:outside-br-custom[BR2_EXTERNAL]. This allows documentation for a +BR2_EXTERNAL tree to match the Buildroot documentation, as it will be +rendered to the same formats and use the same layout and theme. + +==== +asciidoc-document+ tutorial + +Whereas package infrastructures are suffixed with +-package+, the document +infrastructures are suffixed with +-document+. So, the AsciiDoc infrastructure +is named +asciidoc-document+. + +Here is an example to render a simple AsciiDoc document. + +---- +01: ################################################################################ +02: # +03: # foo-document +04: # +05: ################################################################################ +06: +07: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*)) +08: $(eval $(call asciidoc-document)) +---- + +On line 7, the Makefile declares what the sources of the document are. +Currently, it is expected that the document's sources are only local; +Buildroot will not attempt to download anything to render a document. +Thus, you must indicate where the sources are. Usually, the string +above is sufficient for a document with no sub-directory structure. + +Finally, on line 8, we call the +asciidoc-document+ function, which +generates all the Makefile code necessary to render the document. + +==== +asciidoc-document+ reference + +The list of variables that can be set in a +.mk+ file to give metadata +information is (assuming the document name is +foo+) : + +* +FOO_SOURCES+, mandatory, defines the source files for the document. + +* +FOO_RESOURCES+, optional, may contain a space-separated list of paths + to one or more directories containing so-called resources (CSS, + images...) By default, empty. + +There are also additional hooks (see xref:hooks[] for general information +on hooks), that a document may set to define extra actions to be done at +various steps: + +* +FOO_POST_RSYNC_HOOKS+ to run additional commands after the sources + have been copied by Buildroot. This can be used for, for example, + generating part of the manual with information extracted from the + tree. As an example, Buildroot uses this hook to generate the tables + in the appendices. + +* +FOO_CHECK_DEPENDENCIES_HOOKS+ to run additional tests on required + components to generate the document. In AsciiDoc, it is possible to + call filters, that is, programs that will parse an AsciiDoc block and + render it appropriately (e.g. http://ditaa.sourceforge.net/[ditaa] or + https://pythonhosted.org/aafigure/[aafigure].) + +* +FOO_CHECK_DEPENDENCIES_<FMT>_HOOKS+, to run additional tests for + the specified format +<FMT>+ (see the list of rendered formats, above.) + +Here is a complete example that uses all variables and all hooks: + +---- +01: ################################################################################ +02: # +03: # foo-document +04: # +05: ################################################################################ +06: +07: FOO_SOURCES = $(sort $(widcard $(pkgdir)/*)) +08: FOO_RESOURCES = $(sort $(wildcard $(pkgdir)/ressources)) +09: +10: define FOO_GEN_EXTRA_DOC +11: /path/to/generate-script --outdir=$(@D) +12: endef +13: FOO_POST_RSYNC_HOOKS += FOO_GEN_EXTRA_DOC +14: +15: define FOO_CHECK_MY_PROG +16: if ! which my-prog >/dev/null 2>&1; then \ +17: echo "You need my-prog to generate the foo document"; \ +18: exit 1; \ +19: fi +20: endef +21: FOO_CHECK_DEPENDENCIES_HOOKS += FOO_CHECK_MY_PROG +22: +23: define FOO_CHECK_MY_OTHER_PROG +24: if ! which my-other-prog >/dev/null 2>&1; then \ +25: echo "You need my-other-prog to generate the foo document as PDF"; \ +26: exit 1; \ +27: fi +28: endef +29: FOO_CHECK_DEPENDENCIES_PDF_HOOKS += FOO_CHECK_MY_OTHER_PROG +30: +31: $(eval $(call asciidoc-document)) +----
docs/manual/adding-packages.txt +2 -0
@@ -27,6 +27,8 @@ include::adding-packages-virtual.txt[] include::adding-packages-kconfig.txt[] +include::adding-packages-asciidoc.txt[] + include::adding-packages-hooks.txt[] include::adding-packages-gettext.txt[]
Signature · 1 line
1.9.1
PATCH v6 25/25 docs/manual: document the asciidoc infra
Yann,
Quoted 104 lines · Yann E. MORIN
Signed-off-by "Yann E. MORIN" <[email protected]>Cc Samuel Martin <[email protected]>Cc Thomas De Schampheleire <[email protected]>---
Chamges v5 -> v6:
- fix names of hooks
- remove trailing spaces--- docs/manual/adding-packages-asciidoc.txt | 119 +++++++++++++++++++++++++++++++ docs/manual/adding-packages.txt | 2 + 2 files changed, 121 insertions(+) create mode 100644 docs/manual/adding-packages-asciidoc.txtdocs/manual/adding-packages-asciidoc.txt new file +84
-0@@ -0,0 +1,119 @@ +// -*- mode:doc; -*- +// vim: syntax=asciidoc + +=== Infrastructure for asciidoc documents + +[[asciidoc-documents-tutorial]] + +The Buildroot manual, which you are currently reading, is entirely written +using the http://asciidoc.org/[AsciiDoc] mark-up syntax. The manual is then +rendered to many formats: + +* html +* split-html +* pdf +* epub +* text + +Although Buildroot only contains one document written in AsciiDoc, there +is, as for packages, an infrastructure for rendering documents using the +AsciiDoc syntax. + +Also as for packages, the AsciiDoc infrastructure is available from +xref:outside-br-custom[BR2_EXTERNAL]. This allows documentation for a +BR2_EXTERNAL tree to match the Buildroot documentation, as it will be +rendered to the same formats and use the same layout and theme. + +==== +asciidoc-document+ tutorial + +Whereas package infrastructures are suffixed with +-package+, the document +infrastructures are suffixed with +-document+. So, the AsciiDoc infrastructure +is named +asciidoc-document+. + +Here is an example to render a simple AsciiDoc document. + +---- +01: ################################################################################ +02: # +03: # foo-document +04: # +05: ################################################################################ +06: +07: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*)) +08: $(eval $(call asciidoc-document)) +---- + +On line 7, the Makefile declares what the sources of the document are. +Currently, it is expected that the document's sources are only local; +Buildroot will not attempt to download anything to render a document. +Thus, you must indicate where the sources are. Usually, the string +above is sufficient for a document with no sub-directory structure. + +Finally, on line 8, we call the +asciidoc-document+ function, which +generates all the Makefile code necessary to render the document. + +==== +asciidoc-document+ reference + +The list of variables that can be set in a +.mk+ file to give metadata +information is (assuming the document name is +foo+) : + +* +FOO_SOURCES+, mandatory, defines the source files for the document. + +* +FOO_RESOURCES+, optional, may contain a space-separated list of paths + to one or more directories containing so-called resources (CSS, + images...) By default, empty. + +There are also additional hooks (see xref:hooks[] for general information +on hooks), that a document may set to define extra actions to be done at +various steps: + +* +FOO_POST_RSYNC_HOOKS+ to run additional commands after the sources + have been copied by Buildroot. This can be used for, for example, + generating part of the manual with information extracted from the + tree. As an example, Buildroot uses this hook to generate the tables + in the appendices. + +* +FOO_CHECK_DEPENDENCIES_HOOKS+ to run additional tests on required + components to generate the document. In AsciiDoc, it is possible to + call filters, that is, programs that will parse an AsciiDoc block and + render it appropriately (e.g. http://ditaa.sourceforge.net/[ditaa] or + https://pythonhosted.org/aafigure/[aafigure].) + +* +FOO_CHECK_DEPENDENCIES_<FMT>_HOOKS+, to run additional tests for + the specified format +<FMT>+ (see the list of rendered formats, above.) +
docs/manual/adding-packages-asciidoc.txt line 94
Quoted 10 lines
docs/manual/adding-packages-asciidoc.txt new file +10
-0+Here is a complete example that uses all variables and all hooks: + +---- +01: ################################################################################ +02: # +03: # foo-document +04: # +05: ################################################################################ +06: +07: FOO_SOURCES = $(sort $(widcard $(pkgdir)/*))
s/widcard/wildcard/
Quoted 39 lines
docs/manual/adding-packages-asciidoc.txt new file +25
-0+08: FOO_RESOURCES = $(sort $(wildcard $(pkgdir)/ressources)) +09: +10: define FOO_GEN_EXTRA_DOC +11: /path/to/generate-script --outdir=$(@D) +12: endef +13: FOO_POST_RSYNC_HOOKS += FOO_GEN_EXTRA_DOC +14: +15: define FOO_CHECK_MY_PROG +16: if ! which my-prog >/dev/null 2>&1; then \ +17: echo "You need my-prog to generate the foo document"; \ +18: exit 1; \ +19: fi +20: endef +21: FOO_CHECK_DEPENDENCIES_HOOKS += FOO_CHECK_MY_PROG +22: +23: define FOO_CHECK_MY_OTHER_PROG +24: if ! which my-other-prog >/dev/null 2>&1; then \ +25: echo "You need my-other-prog to generate the foo document as PDF"; \ +26: exit 1; \ +27: fi +28: endef +29: FOO_CHECK_DEPENDENCIES_PDF_HOOKS += FOO_CHECK_MY_OTHER_PROG +30: +31: $(eval $(call asciidoc-document)) +----docs/manual/adding-packages.txt +2
-1@@ -27,6 +27,8 @@ include::adding-packages-virtual.txt[] include::adding-packages-kconfig.txt[] +include::adding-packages-asciidoc.txt[] + include::adding-packages-hooks.txt[] include::adding-packages-gettext.txt[] --
Quoted 2 lines
1.9.1
With the aformentioned typo fixed:
Regards,
Signature · 1 line
Samuel
PATCH v6 25/25 docs/manual: document the asciidoc infra
Samuel, All,
On 2014-09-27 13:21 +0200, Samuel Martin spake thusly:
Quoted 1 line · Yann E. MORIN
[--SNIP--]
Quoted 9 lines
Quoted 7 lines
+01: ################################################################################ +02: #
+03: # foo-document
+04: #
+05: ################################################################################ +06:
+07:FOO_SOURCES= $(sort $(widcard $(pkgdir)/*))s/widcard/wildcard/
Gah... I fixed the other one Thomas pointed out in the previous review, and did not even think of looking if I borked that one too... :-/
[--SNIP--]
Quoted 2 lines
With the aformentioned typo fixed:
Reviewed-by Samuel Martin <[email protected]>
Thanks! :-)
Regards,
Yann E. MORIN.
Signature · 6 lines
.-----------------.--------------------.------------------.--------------------. | Yann E. MORIN | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: | | +33 662 376 056 | Software Designer | \ / CAMPAIGN | ___ | | +33 223 225 172 `------------.-------: X AGAINST | \e/ There is no | | http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL | v conspiracy. | '------------------------------^-------^------------------^--------------------'
PATCH v6 25/25 docs/manual: document the asciidoc infra
In reply to Yann E. MORINHi Yann,
Quoted 9 lines · Yann E. MORIN
Signed-off-by "Yann E. MORIN" <[email protected]>Cc Samuel Martin <[email protected]>Cc Thomas De Schampheleire <[email protected]>---
Chamges v5 -> v6:
- fix names of hooks
- remove trailing spaces
---
Found some other comments below:
Quoted 6 lines
docs/manual/adding-packages-asciidoc.txt | 119 +++++++++++++++++++++++++++++++ docs/manual/adding-packages.txt | 2 + 2 files changed, 121 insertions(+) create mode 100644 docs/manual/adding-packages-asciidoc.txtdocs/manual/adding-packages-asciidoc.txt +0
-0
[..]
Quoted 18 lines
docs/manual/adding-packages-asciidoc.txt +18
-0+ +==== +asciidoc-document+ tutorial + +Whereas package infrastructures are suffixed with +-package+, the document +infrastructures are suffixed with +-document+. So, the AsciiDoc infrastructure +is named +asciidoc-document+. + +Here is an example to render a simple AsciiDoc document. + +---- +01: ################################################################################ +02: # +03: # foo-document +04: # +05: ################################################################################ +06: +07: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*)) +08: $(eval $(call asciidoc-document))
docs/manual/adding-packages-asciidoc.txt line 53
Quoted 10 lines
docs/manual/adding-packages-asciidoc.txt +10
-0+---- + +On line 7, the Makefile declares what the sources of the document are. +Currently, it is expected that the document's sources are only local; +Buildroot will not attempt to download anything to render a document. +Thus, you must indicate where the sources are. Usually, the string +above is sufficient for a document with no sub-directory structure. + +Finally, on line 8, we call the +asciidoc-document+ function, which +generates all the Makefile code necessary to render the document.
'Finally' is a bit an exaggeration here, as there was only one described line above it :)
docs/manual/adding-packages-asciidoc.txt line 64
Quoted 11 lines
docs/manual/adding-packages-asciidoc.txt +11
-0+ +==== +asciidoc-document+ reference + +The list of variables that can be set in a +.mk+ file to give metadata +information is (assuming the document name is +foo+) : + +* +FOO_SOURCES+, mandatory, defines the source files for the document. + +* +FOO_RESOURCES+, optional, may contain a space-separated list of paths + to one or more directories containing so-called resources (CSS, + images...) By default, empty.
Shouldn't there be a dot after the closing parentheses, to finish the sentence?
docs/manual/adding-packages-asciidoc.txt line 72
Quoted 8 lines
docs/manual/adding-packages-asciidoc.txt +8
-0+ +There are also additional hooks (see xref:hooks[] for general information +on hooks), that a document may set to define extra actions to be done at +various steps: + +* +FOO_POST_RSYNC_HOOKS+ to run additional commands after the sources + have been copied by Buildroot. This can be used for, for example, + generating part of the manual with information extracted from the
I would write:
This can for example be used for ...
Best regards,
Thomas
PATCH v6 25/25 docs/manual: document the asciidoc infra
Thomas, All,
On 2014-10-02 12:27 +0200, Thomas De Schampheleire spake thusly:
[--SNIP--]
Quoted 5 lines
docs/manual/adding-packages-asciidoc.txt line 53
Quoted 2 lines
docs/manual/adding-packages-asciidoc.txt new file +2
-0+Finally, on line 8, we call the +asciidoc-document+ function, which +generates all the Makefile code necessary to render the document.'Finally' is a bit an exaggeration here, as there was only one described line above it :)
I just mimicked what was done in the other package infras, to get as consistent as possible. I'll rephrase.
Quoted 5 lines
docs/manual/adding-packages-asciidoc.txt line 64
Quoted 3 lines
docs/manual/adding-packages-asciidoc.txt new file +3
-0+* +FOO_RESOURCES+, optional, may contain a space-separated list of paths + to one or more directories containing so-called resources (CSS, + images...) By default, empty.Shouldn't there be a dot after the closing parentheses, to finish the sentence?
I was under the impression that a closing parenthses at the end of a sentence would goble the punctuation mark.
So I checked a few on-line ressources.
It seems that (once not making it a rule), I was mislaid.
Quoted 10 lines
docs/manual/adding-packages-asciidoc.txt line 72
Quoted 7 lines
docs/manual/adding-packages-asciidoc.txt new file +7
-0+There are also additional hooks (see xref:hooks[] for general information +on hooks), that a document may set to define extra actions to be done at +various steps: + +* +FOO_POST_RSYNC_HOOKS+ to run additional commands after the sources + have been copied by Buildroot. This can be used for, for example, + generating part of the manual with information extracted from theI would write:
This can for example be used for ...
OK.
Thanks! :-)
Regards,
Yann E. MORIN.
Signature · 6 lines
.-----------------.--------------------.------------------.--------------------. | Yann E. MORIN | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: | | +33 662 376 056 | Software Designer | \ / CAMPAIGN | ___ | | +33 223 225 172 `------------.-------: X AGAINST | \e/ There is no | | http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL | v conspiracy. | '------------------------------^-------^------------------^--------------------'