[Buildroot] [PATCH 01/25 v7] gendoc infra: move manual build location into $(BUILD_DIR)/docs/manual

[Buildroot] [PATCH 01/25 v7] gendoc infra: move manual build location into $(BUILD_DIR)/docs/manual

[Yann E. MORIN]

From: Samuel Martin <s.martin49@gmail.com>

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

Cc: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
[yann.morin.1998 at free.fr: moved into $(BUILD_DIR)/docs/manual as per
Thomas P. suggestion]
Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>

---
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(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index 136f725..cdc4c73 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -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
 
-- 
1.9.1

[Buildroot] [PATCH 02/25 v7] gendoc infra: avoid a2x warning

[Yann E. MORIN]

From: Samuel Martin <s.martin49@gmail.com>

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.

Reported-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
Cc: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
[yann.morin.1998 at free.fr: tested all but PDF]
Tested-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Reviewed-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
---
 docs/manual/manual.mk | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index cdc4c73..03e3a0b 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -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
 
 ################################################################################
-- 
1.9.1

[Buildroot] [PATCH 03/25 v7] gendoc infra: disable pdf manual generation if xsltproc is buggy

[Yann E. MORIN]

From: Samuel Martin <s.martin49@gmail.com>

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

Reported-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
Cc: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
[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]
Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>

---
Changes v5 -> v6:
  - make it a warning, not an error  (Thomas DS)
---
 docs/manual/manual.mk | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index 03e3a0b..e9078f1 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -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
-- 
1.9.1

[Buildroot] [PATCH 04/25 v7] docs/manual: get rid of legacy comment in GENDOC

[Yann E. MORIN]

Since dd935d6 (gendoc infra: use $(pkgname) instead of explicitly
passing 'manual', the GENDOC infra no longer expect any argument.

Remove the stray comment.

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Acked-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Acked-by: Samuel Martin <s.martin49@gmail.com>
---
 docs/manual/manual.mk | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index e9078f1..69113e3 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -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
-- 
1.9.1

[Buildroot] [PATCH 05/25 v7] docs/manual: copying the manual sources is a common action

[Yann E. MORIN]

Move 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.

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Reviewed-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Reviewed-by: Samuel Martin <s.martin49@gmail.com>
---
 docs/manual/manual.mk | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index 69113e3..dd6f0ea 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -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,\
-- 
1.9.1

[Buildroot] [PATCH 06/25 v7] docs/manual: simplify generation dependencies

[Yann E. MORIN]

The document's main file is already part of MANUAL_SOURCES, so no need
to explicitly depend on it.

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Acked-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Acked-by: Samuel Martin <s.martin49@gmail.com>
---
 docs/manual/manual.mk | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index dd6f0ea..56dff56 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -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
-- 
1.9.1

[Buildroot] [PATCH 07/25 v7] docs/manual: manual-update-lists is not a generic GENDOC rule

[Yann E. MORIN]

Move the manual-update-lists .PHONY declaration out of GENDOC, since not
all the documents may have an -update-lists rule.

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Acked-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Reviewed-by: Samuel Martin <s.martin49@gmail.com>
---
 docs/manual/manual.mk | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index 56dff56..3b79716 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -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/*))
-- 
1.9.1

[Buildroot] [PATCH 08/25 v7] docs/manual: move manual-prepare-sources rule into GENDOC

[Yann E. MORIN]

Copying 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.

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Acked-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Reviewed-by: Samuel Martin <s.martin49@gmail.com>
---
 docs/manual/manual.mk | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index 3b79716..c40f371 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -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,\
-- 
1.9.1

[Buildroot] [PATCH 09/25 v7] docs/manual: do not hardcode name of the generated document

[Yann E. MORIN]

Currently, 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-sources

This 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.

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Reviewed-by: Samuel Martin <s.martin49@gmail.com>

---
Changes v6-> v7:
  - restore $$ when calling UPPERCASE  (Thomas DS, me)
  - use $(2) (uppercase name, now that we have it as an arg), instead
    of $(call UPPERCASE,$(1)) in _INNER

Note: we restored the use of $$, as GENDOC will eventually be an inner
macro itself, to be added later in the series. Thomas DS and I discussed
this on IRC, and concluded it was better to get it straight right now,
even if it only makes sense later, because: (1) it works as-is right
now, (2) making it a $$ only when really needed would make for a complex
patch. So, $$ it is from the start.

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(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index c40f371..40bb1b1 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -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 documents"; \
 		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 documents"; \
 		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 PDF documents"; \
 		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): $$($(2)_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)
-- 
1.9.1

[Buildroot] [PATCH 10/25 v7] docs/manual: allow a document to declare where its resources are

[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" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Reviewed-by: Samuel Martin <s.martin49@gmail.com>
Reviewed-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
Changes v5 -> v6:
  - s/ressources/resources/g  (Thomas DS, Samuel)
---
 docs/manual/manual.mk | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index 40bb1b1..7b06d47 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -106,7 +106,8 @@ $$(O)/docs/$(1)/$(1).$(5): $$($(2)_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))
-- 
1.9.1

[Buildroot] [PATCH 11/25 v7] docs/manual: last pass at removing hard-coded path in GENDOC_INNER

[Yann E. MORIN]

GENDOC_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.

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Reviewed-by: Samuel Martin <s.martin49@gmail.com>
---
 docs/manual/manual.mk | 74 ++++++++++++++++++++++++++++-----------------------
 1 file changed, 40 insertions(+), 34 deletions(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index 7b06d47..cf6f33c 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -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): $$($(2)_SOURCES) \
+$$(O)/docs/$(1)/$(1).$(6): $$($(2)_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)
-- 
1.9.1

[Buildroot] [PATCH 12/25 v7] docs/manual: properly separate rules specific for our manual

[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" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Acked-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Acked-by: Samuel Martin <s.martin49@gmail.com>
---
 docs/manual/manual.mk | 41 +++++++++++++++++++++++------------------
 1 file changed, 23 insertions(+), 18 deletions(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index cf6f33c..536f939 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -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))
-- 
1.9.1

[Buildroot] [PATCH 13/25 v7] docs/manual: rename the generic dependency rules

[Yann E. MORIN]

Those 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.

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Reviewed-by: Samuel Martin <s.martin49@gmail.com>
Acked-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
---
 docs/manual/manual.mk | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index 536f939..f6ef71e 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -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 documents"; \
@@ -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 PDF documents"; \
 		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)),)
-- 
1.9.1

[Buildroot] [PATCH 14/25 v7] docs/manual: allow documents to define some hooks, as for a package

[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_INNER already has the uppercase name as an argument,
whereas GENDOC does not, so the two foreach loops are not exactly
similar (for now.)

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Reviewed-by: Samuel Martin <s.martin49@gmail.com>
Acked-by: Thomas De Schampheleire <patrickdepinguin@gmail.com>

---
Changes v6 -> v7:
  - reinstate $$ when calling UPPERCASE  (Thomas DS)

Changes v5 -> v6:
  - do not use $$ when calling 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(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index f6ef71e..ee7887c 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -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
 
-- 
1.9.1

[Buildroot] [PATCH 15/25 v7] docs/manual: use the new hooks instead of gendoc rules

[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" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Reviewed-by: Samuel Martin <s.martin49@gmail.com>
Reviewed-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
Changes v5 -> v6:
  - hooks were renamed  (Thomas DS)
  - typo  (Thomas DS)
---
 docs/manual/manual.mk | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index ee7887c..e9e0516 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -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))
-- 
1.9.1

[Buildroot] [PATCH 16/25 v7] docs/manual: always look for resources in destination directory

[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
    ----

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" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Reviewed-by: Samuel Martin <s.martin49@gmail.com>
Reviewed-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
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(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index e9e0516..0b88fd8 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -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): $$($(2)_SOURCES) \
 			   $(1)-check-dependencies \
 			   $(1)-check-dependencies-$(5) \
@@ -93,7 +95,7 @@ $$(O)/docs/$(1)/$(1).$(6): $$($(2)_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
-- 
1.9.1

[Buildroot] [PATCH 17/25 v7] docs: separate the GENDOC infra from our manual definition

[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.

So, let's just put alongside the other infrastructures, in package/ .

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Acked-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Acked-by: Samuel Martin <s.martin49@gmail.com>

---
Changes v6 -> v7:
  - use more traditional header (like for a package)
---
 Makefile              |   1 +
 docs/manual/manual.mk | 151 +-------------------------------------------------
 package/gendoc.mk     | 150 +++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 152 insertions(+), 150 deletions(-)
 create mode 100644 package/gendoc.mk

diff --git a/Makefile b/Makefile
index 53f8ad5..5a1bbbd 100644
--- a/Makefile
+++ b/Makefile
@@ -272,6 +272,7 @@ unexport DESTDIR
 unexport RUBYOPT
 
 include package/pkg-utils.mk
+include package/gendoc.mk
 
 ifeq ($(BR2_HAVE_DOT_CONFIG),y)
 
diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index 0b88fd8..a896119 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -1,156 +1,7 @@
-# we can't use suitable-host-package here because that's not available in
-# the context of 'make release'
-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 documents"; \
-		exit 1; \
-	fi
-	$(Q)if [ -z "`which w3m 2>/dev/null`" ]; then \
-		echo "You need w3m on your host to generate documents"; \
-		exit 1; \
-	fi
-
-gendoc-check-dependencies-pdf:
-	$(Q)if [ -z "`which dblatex 2>/dev/null`" ]; then \
-		echo "You need dblatex on your host to generate PDF documents"; \
-		exit 1; \
-	fi
-
-# PDF generation is broken because of a bug in xsltproc program provided
-# by libxslt <=1.1.28, which does not honor an option we need to set.
-# Fortunately, this bug is already fixed upstream:
-#   https://gitorious.org/libxslt/libxslt/commit/5af7ad745323004984287e48b42712e7305de35c
-#
-# So, bail out when trying to build a PDF using a buggy version of the
-# xsltproc program.
-#
-# So, to overcome this issue and being able to build a PDF, you can
-# build xsltproc from its source repository, then run:
-#   $ PATH=/path/to/custom-xsltproc/bin:${PATH} make manual
-GENDOC_XSLTPROC_IS_BROKEN = \
-	$(shell xsltproc --maxvars 0 >/dev/null 2>/dev/null || echo y)
-
 ################################################################################
-# GENDOC_INNER -- generates the make targets needed to build a specific type of
-#                 asciidoc documentation.
-#
-#  argument 1 is the name of the document and the top-level asciidoc file must
-#             have the same name
-#  argument 2 is the uppercase name of the document
-#  argument 3 is the directory containing the document
-#  argument 4 is the type of document to generate (-f argument of a2x)
-#  argument 5 is the document type as used in the make target
-#  argument 6 is the output file extension for the document type
-#  argument 7 is the human text for the document type
-#  argument 8 (optional) are extra arguments for a2x
-#
-# The variable <DOCUMENT_NAME>_SOURCES defines the dependencies.
 #
-# Since this function will be called from within an $(eval ...)
-# all variable references except the arguments must be $$-quoted.
-################################################################################
-define GENDOC_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)
-	$$(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)),)
-$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_$(4)_ASCIIDOC_CONF)
-endif
-
-# Handle a2x warning about --destination-dir option only applicable to HTML
-# based outputs. So:
-# - use the --destination-dir option if possible (html and split-html),
-# - otherwise copy the generated document to the output directory
-$(2)_$(4)_A2X_OPTS =
-ifneq ($$(filter $(5),html split-html),)
-$(2)_$(4)_A2X_OPTS += --destination-dir="$$(@D)"
-else
-define $(2)_$(4)_INSTALL_CMDS
-	$$(Q)cp -f $$(BUILD_DIR)/docs/$(1)/$(1).$(6) $$(@D)
-endef
-endif
-
-ifeq ($(6)-$$(GENDOC_XSLTPROC_IS_BROKEN),pdf-y)
-$$(O)/docs/$(1)/$(1).$(6):
-	$$(warning PDF generation is disabled because of a bug in \
-		xsltproc. To be able to generate a PDF, you should \
-		build xsltproc from the libxslt sources >=1.1.29 and pass it \
-		to make through the command line: \
-		'PATH=/path/to/custom-xsltproc/bin:$$$${PATH} make $(1)-pdf')
-else
-# -r $(@D) is there for documents that use external filters; those filters
-# generate code at the same location it finds the document's source files.
-$$(O)/docs/$(1)/$(1).$(6): $$($(2)_SOURCES) \
-			   $(1)-check-dependencies \
-			   $(1)-check-dependencies-$(5) \
-			   $(1)-prepare-sources
-	$$(Q)$$(call MESSAGE,"Generating $(7) $(1)...")
-	$$(Q)mkdir -p $$(@D)
-	$$(Q)a2x $(8) -f $(4) -d book -L \
-		$$(foreach r,$$($(2)_RESOURCES),-r $$(r)) -r $$(@D) \
-		$$($(2)_$(4)_A2X_OPTS) \
-		--asciidoc-opts="$$($(2)_$(4)_ASCIIDOC_OPTS)" \
-		$$(BUILD_DIR)/docs/$(1)/$(1).txt
-# install the generated document
-	$$($(2)_$(4)_INSTALL_CMDS)
-endif
-endef
-
-################################################################################
-# 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
-# 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
-
-$(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)),$(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,\
-	--dblatex-opts "-P latex.output.revhistory=0 -x '--maxvars 100000'")
-
-$(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)
-.PHONY: $(pkgname) $(pkgname)-clean
-endef
-
-################################################################################
 # The Buildroot manual
+#
 ################################################################################
 
 MANUAL_SOURCES = $(sort $(wildcard docs/manual/*.txt) $(wildcard docs/images/*))
diff --git a/package/gendoc.mk b/package/gendoc.mk
new file mode 100644
index 0000000..d7c85cb
--- /dev/null
+++ b/package/gendoc.mk
@@ -0,0 +1,150 @@
+# we can't use suitable-host-package here because that's not available in
+# the context of 'make release'
+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 documents"; \
+		exit 1; \
+	fi
+	$(Q)if [ -z "`which w3m 2>/dev/null`" ]; then \
+		echo "You need w3m on your host to generate documents"; \
+		exit 1; \
+	fi
+
+gendoc-check-dependencies-pdf:
+	$(Q)if [ -z "`which dblatex 2>/dev/null`" ]; then \
+		echo "You need dblatex on your host to generate PDF documents"; \
+		exit 1; \
+	fi
+
+# PDF generation is broken because of a bug in xsltproc program provided
+# by libxslt <=1.1.28, which does not honor an option we need to set.
+# Fortunately, this bug is already fixed upstream:
+#   https://gitorious.org/libxslt/libxslt/commit/5af7ad745323004984287e48b42712e7305de35c
+#
+# So, bail out when trying to build a PDF using a buggy version of the
+# xsltproc program.
+#
+# So, to overcome this issue and being able to build a PDF, you can
+# build xsltproc from its source repository, then run:
+#   $ PATH=/path/to/custom-xsltproc/bin:${PATH} make manual
+GENDOC_XSLTPROC_IS_BROKEN = \
+	$(shell xsltproc --maxvars 0 >/dev/null 2>/dev/null || echo y)
+
+################################################################################
+# GENDOC_INNER -- generates the make targets needed to build a specific type of
+#                 asciidoc documentation.
+#
+#  argument 1 is the name of the document and the top-level asciidoc file must
+#             have the same name
+#  argument 2 is the uppercase name of the document
+#  argument 3 is the directory containing the document
+#  argument 4 is the type of document to generate (-f argument of a2x)
+#  argument 5 is the document type as used in the make target
+#  argument 6 is the output file extension for the document type
+#  argument 7 is the human text for the document type
+#  argument 8 (optional) are extra arguments for a2x
+#
+# The variable <DOCUMENT_NAME>_SOURCES defines the dependencies.
+#
+# Since this function will be called from within an $(eval ...)
+# all variable references except the arguments must be $$-quoted.
+################################################################################
+define GENDOC_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)
+	$$(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)),)
+$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_$(4)_ASCIIDOC_CONF)
+endif
+
+# Handle a2x warning about --destination-dir option only applicable to HTML
+# based outputs. So:
+# - use the --destination-dir option if possible (html and split-html),
+# - otherwise copy the generated document to the output directory
+$(2)_$(4)_A2X_OPTS =
+ifneq ($$(filter $(5),html split-html),)
+$(2)_$(4)_A2X_OPTS += --destination-dir="$$(@D)"
+else
+define $(2)_$(4)_INSTALL_CMDS
+	$$(Q)cp -f $$(BUILD_DIR)/docs/$(1)/$(1).$(6) $$(@D)
+endef
+endif
+
+ifeq ($(6)-$$(GENDOC_XSLTPROC_IS_BROKEN),pdf-y)
+$$(O)/docs/$(1)/$(1).$(6):
+	$$(warning PDF generation is disabled because of a bug in \
+		xsltproc. To be able to generate a PDF, you should \
+		build xsltproc from the libxslt sources >=1.1.29 and pass it \
+		to make through the command line: \
+		'PATH=/path/to/custom-xsltproc/bin:$$$${PATH} make $(1)-pdf')
+else
+# -r $(@D) is there for documents that use external filters; those filters
+# generate code at the same location it finds the document's source files.
+$$(O)/docs/$(1)/$(1).$(6): $$($(2)_SOURCES) \
+			   $(1)-check-dependencies \
+			   $(1)-check-dependencies-$(5) \
+			   $(1)-prepare-sources
+	$$(Q)$$(call MESSAGE,"Generating $(7) $(1)...")
+	$$(Q)mkdir -p $$(@D)
+	$$(Q)a2x $(8) -f $(4) -d book -L \
+		$$(foreach r,$$($(2)_RESOURCES),-r $$(r)) -r $$(@D) \
+		$$($(2)_$(4)_A2X_OPTS) \
+		--asciidoc-opts="$$($(2)_$(4)_ASCIIDOC_OPTS)" \
+		$$(BUILD_DIR)/docs/$(1)/$(1).txt
+# install the generated document
+	$$($(2)_$(4)_INSTALL_CMDS)
+endif
+endef
+
+################################################################################
+# 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
+# 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
+
+$(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)),$(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,\
+	--dblatex-opts "-P latex.output.revhistory=0 -x '--maxvars 100000'")
+
+$(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)
+.PHONY: $(pkgname) $(pkgname)-clean
+endef
-- 
1.9.1

[Buildroot] [PATCH 18/25 v7] docs: rename the GENDOC infrastructure

[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" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Reviewed-by: Samuel Martin <s.martin49@gmail.com>
Reviewed-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
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%)

diff --git a/Makefile b/Makefile
index 5a1bbbd..3146525 100644
--- a/Makefile
+++ b/Makefile
@@ -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)
 
diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index a896119..a3011c6 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -28,4 +28,4 @@ define MANUAL_CHECK_LISTS_DEPS
 endef
 MANUAL_CHECK_DEPENDENCIES_HOOKS += MANUAL_CHECK_LISTS_DEPS
 
-$(eval $(call GENDOC))
+$(eval $(call asciidoc-document))
diff --git a/package/gendoc.mk b/package/doc-asciidoc.mk
similarity index 81%
rename from package/gendoc.mk
rename to package/doc-asciidoc.mk
index d7c85cb..fb9a62e 100644
--- a/package/gendoc.mk
+++ b/package/doc-asciidoc.mk
@@ -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 documents"; \
@@ -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 PDF documents"; \
 		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)
-- 
1.9.1

[Buildroot] [PATCH 19/25 v7] docs/asciidoc: call $(pkgname) and $(pkgdir) in a single place

[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.

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" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Reviewed-by: Samuel Martin <s.martin49@gmail.com>
Reviewed-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
Chamges v5 -> v6:
  - convert forgotten occurence of $(pkgname)  (Thomas DS)
---
 package/doc-asciidoc.mk | 41 +++++++++++++++++++++++------------------
 1 file changed, 23 insertions(+), 18 deletions(-)

diff --git a/package/doc-asciidoc.mk b/package/doc-asciidoc.mk
index fb9a62e..6b5b2b7 100644
--- a/package/doc-asciidoc.mk
+++ b/package/doc-asciidoc.mk
@@ -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))
-- 
1.9.1

[Buildroot] [PATCH 20/25 v7] docs/asciidoc: make it possible to use $(@D) in hooks

[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.

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" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Reviewed-by: Samuel Martin <s.martin49@gmail.com>
Reviewed-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
---
 docs/manual/manual.mk   |  2 +-
 package/doc-asciidoc.mk | 12 ++++++------
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index a3011c6..d5db2c2 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -12,7 +12,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
diff --git a/package/doc-asciidoc.mk b/package/doc-asciidoc.mk
index 6b5b2b7..9a18270 100644
--- a/package/doc-asciidoc.mk
+++ b/package/doc-asciidoc.mk
@@ -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")
-- 
1.9.1

[Buildroot] [PATCH 0/25 v7] gendoc infra: make it useable for other documents (branch yem/manual)

[Yann E. MORIN]

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 v6 -> v7:
  - restore $$ when calling UPPERCASE  (Thomas DS)
  - clarifications in commit logs  (Samuel, Thomas DS)
  - typoes  (Samuel, Thomas DS)

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 7b6304af9d69d44ee3040c00b0670f19c02de7d2:

  protobuf: bump version to 2.6.0 (2014-10-02 22:54:37 +0200)

are available in the git repository at:

  git://git.busybox.net/~ymorin/git/buildroot yem/manual

for you to fetch changes up to dda88aca0a62478ffc5be7e7fd9635376be4e3a8:

  docs/manual: document the asciidoc infra (2014-10-02 23:48:13 +0200)

----------------------------------------------------------------
Samuel Martin (3):
      gendoc infra: move manual build location into $(BUILD_DIR)/docs/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                    | 107 +++---------------
 package/doc-asciidoc.mk                  | 185 +++++++++++++++++++++++++++++++
 6 files changed, 326 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.mk

-- 
.-----------------.--------------------.------------------.--------------------.
|  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.  |
'------------------------------^-------^------------------^--------------------'

[Buildroot] [PATCH 21/25 v7] doc/asciidoc: allow documents to pass a global asciidoc configuration

[Yann E. MORIN]

Currently, a document can specify an output-specific configuration, like
the text output, that hides images references, and formats hyperlinks.

But sometimes 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 latter takes precedence over the former.)

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Reviewed-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
Change v6 -> v7:
  - fix commit log about config file precedence  (Samuel)
  - 'sometimes' typo  (Thomas DS)
---
 package/doc-asciidoc.mk | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/package/doc-asciidoc.mk b/package/doc-asciidoc.mk
index 9a18270..649ee69 100644
--- a/package/doc-asciidoc.mk
+++ b/package/doc-asciidoc.mk
@@ -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")
 
-- 
1.9.1

[Buildroot] [PATCH 22/25 v7] doc/asciidoc: always apply Buildroot's AsciiDoc config

[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" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Reviewed-by: Samuel Martin <s.martin49@gmail.com>
---
 docs/{manual => conf}/asciidoc-text.conf |  0
 package/doc-asciidoc.mk                  | 18 +++++++++++++++++-
 2 files changed, 17 insertions(+), 1 deletion(-)
 rename docs/{manual => conf}/asciidoc-text.conf (100%)

diff --git a/docs/manual/asciidoc-text.conf b/docs/conf/asciidoc-text.conf
similarity index 100%
rename from docs/manual/asciidoc-text.conf
rename to docs/conf/asciidoc-text.conf
diff --git a/package/doc-asciidoc.mk b/package/doc-asciidoc.mk
index 649ee69..f59f9fa 100644
--- a/package/doc-asciidoc.mk
+++ b/package/doc-asciidoc.mk
@@ -31,6 +31,9 @@ asciidoc-check-dependencies-pdf:
 GENDOC_XSLTPROC_IS_BROKEN = \
 	$(shell xsltproc --maxvars 0 >/dev/null 2>/dev/null || echo y)
 
+# Apply this configuration to all documents
+BR_ASCIIDOC_CONF = docs/conf/asciidoc.conf
+
 ################################################################################
 # ASCIIDOC_INNER -- generates the make targets needed to build a specific type of
 #                   asciidoc documentation.
@@ -60,10 +63,23 @@ asciidoc-check-dependencies-$(5):
 $(1)-check-dependencies-$(5): asciidoc-check-dependencies-$(5)
 	$$(Q)$$(foreach hook,$$($(2)_CHECK_DEPENDENCIES_$$(call UPPERCASE,$(5))_HOOKS),$$(call $$(hook))$$(sep))
 
+# Include Buildroot's AsciiDoc configuration first:
+#  - generic configuration,
+#  - then output-specific configuration
+ifneq ($$(wildcard $$(BR_ASCIIDOC_CONF)),)
+$(2)_$(4)_ASCIIDOC_OPTS += -f $$(BR_ASCIIDOC_CONF)
+endif
+BR_$(4)_ASCIIDOC_CONF = docs/conf/asciidoc-$(4).conf
+ifneq ($$(wildcard $$(BR_$(4)_ASCIIDOC_CONF)),)
+$(2)_$(4)_ASCIIDOC_OPTS += -f $$(BR_$(4)_ASCIIDOC_CONF)
+endif
+
+# Then include the document's AsciiDoc configuration:
+#  - generic configuration,
+#  - then output-specific configuration
 ifneq ($$(wildcard $$($(2)_ASCIIDOC_CONF)),)
 $(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_ASCIIDOC_CONF)
 endif
-
 $(2)_$(4)_ASCIIDOC_CONF = $(3)/asciidoc-$(4).conf
 ifneq ($$(wildcard $$($(2)_$(4)_ASCIIDOC_CONF)),)
 $(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_$(4)_ASCIIDOC_CONF)
-- 
1.9.1

[Buildroot] [PATCH 23/25 v7] doc/asciidoc: always use UTC

[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.)

So, a manual rendered during the summer or the winter would refer to a
non-constant timezone. If the machine and/or user doing the rendering
also changes, there is no guarantee the timezone would still be CET/CEST.
This is not a hard issue, since the user can still deduce the time in
UTC, but is just incoherent.

Just force the timezone to be UTC when doing the rendering of the
manual, so we are not dependent on the machine or user doing the
rendering.

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Reviewed-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
Changes v6 -> v7:
  - typo in commit log  (Thomas DS)
---
 package/doc-asciidoc.mk | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/package/doc-asciidoc.mk b/package/doc-asciidoc.mk
index f59f9fa..6ab5ad2 100644
--- a/package/doc-asciidoc.mk
+++ b/package/doc-asciidoc.mk
@@ -98,6 +98,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 \
-- 
1.9.1

[Buildroot] [PATCH 24/25 v7] Makefile: enable generating documents from br2-external

[Yann E. MORIN]

Currently, 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"

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Reviewed-by: Samuel Martin <s.martin49@gmail.com>
Reviewed-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
---
 Makefile | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Makefile b/Makefile
index 3146525..4f41235 100644
--- a/Makefile
+++ b/Makefile
@@ -934,5 +934,6 @@ print-version:
 	@echo $(BR2_VERSION_FULL)
 
 include docs/manual/manual.mk
+-include $(BR2_EXTERNAL)/docs/*/*.mk
 
 .PHONY: $(noconfig_targets)
-- 
1.9.1

[Buildroot] [PATCH 25/25 v7] docs/manual: document the asciidoc infra

[Yann E. MORIN]

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Reviewed-by: Samuel Martin <s.martin49@gmail.com>

---
Changes v6 -> v7:
  - typo  (Samuel)
  - some rephrasing  (Thomas DS)

Chamges v5 -> v6:
  - fix names of hooks  (Thomas DS)
  - remove trailing spaces
  - typo  (Thomas DS)
---
 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

diff --git a/docs/manual/adding-packages-asciidoc.txt b/docs/manual/adding-packages-asciidoc.txt
new file mode 100644
index 0000000..6f925a0
--- /dev/null
+++ b/docs/manual/adding-packages-asciidoc.txt
@@ -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.
+
+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 (like CSS or
+  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 for example be used to
+  generate 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 $(wildcard $(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))
+----
diff --git a/docs/manual/adding-packages.txt b/docs/manual/adding-packages.txt
index 9c97128..feb0d13 100644
--- a/docs/manual/adding-packages.txt
+++ b/docs/manual/adding-packages.txt
@@ -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[]
-- 
1.9.1

[Buildroot] [PATCH 09/25 v7] docs/manual: do not hardcode name of the generated document

[Thomas De Schampheleire]

On Fri, Oct 3, 2014 at 7:01 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Currently, 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-sources
>
> This 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.
>
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> Cc: Samuel Martin <s.martin49@gmail.com>
> Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
> Reviewed-by: Samuel Martin <s.martin49@gmail.com>

Reviewed-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

[Buildroot] [PATCH 22/25 v7] doc/asciidoc: always apply Buildroot's AsciiDoc config

[Thomas De Schampheleire]

On Fri, Oct 3, 2014 at 7:01 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> As suggested by Thomas: the AsciiDoc options we use ensure we get a sane
> output of the document. We want that configuration to be applied to
> other documents as well.
>
> Up until now, it was implicit that the configuration was applied to
> our manual, becasue we only supported document-specific configuration,
> and the configuration we had was in our manual dir, so we got to use it.
>
> But now, we can render other documents, especially ones from
> br2-external, and we want those to also use the default configuration
> from Buildroot, but still be able to provide their own customisation.
>
> So, always add Buildroot's configuration first, if available, before we
> append the document's configuration.
>
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> Cc: Samuel Martin <s.martin49@gmail.com>
> Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
> Reviewed-by: Samuel Martin <s.martin49@gmail.com>

Reviewed-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

[Buildroot] [PATCH 25/25 v7] docs/manual: document the asciidoc infra

[Thomas De Schampheleire]

Hi Yann,

On Fri, Oct 3, 2014 at 7:01 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> Cc: Samuel Martin <s.martin49@gmail.com>
> Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
> Reviewed-by: Samuel Martin <s.martin49@gmail.com>
>
> ---
> Changes v6 -> v7:
>   - typo  (Samuel)
>   - some rephrasing  (Thomas DS)
>
> Chamges v5 -> v6:
>   - fix names of hooks  (Thomas DS)
>   - remove trailing spaces
>   - typo  (Thomas DS)
> ---
>  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
>
> diff --git a/docs/manual/adding-packages-asciidoc.txt b/docs/manual/adding-packages-asciidoc.txt
> new file mode 100644
> index 0000000..6f925a0
> --- /dev/null
> +++ b/docs/manual/adding-packages-asciidoc.txt
> @@ -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.
> +
> +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 (like CSS or
> +  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 for example be used to
> +  generate 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].)

Here the period should be outside the parentheses, right?
See http://english.stackexchange.com/questions/6632/where-does-the-period-go-when-using-parentheses

> +
> +* +FOO_CHECK_DEPENDENCIES_<FMT>_HOOKS+, to run additional tests for
> +  the specified format +<FMT>+ (see the list of rendered formats, above.)

Same here I'd say.


Both are minor comments, really, and since the series went through so
much iterations already I'd say it's good to go and the above can be
fixed with a follow-up patch.

Hence:

Reviewed-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

[Buildroot] [PATCH 01/25 v7] gendoc infra: move manual build location into $(BUILD_DIR)/docs/manual

[Peter Korsgaard]

>>>>> "Yann" == Yann E MORIN <yann.morin.1998@free.fr> writes:

 > From: Samuel Martin <s.martin49@gmail.com>
 > 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

 > Cc: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
 > Signed-off-by: Samuel Martin <s.martin49@gmail.com>
 > [yann.morin.1998 at free.fr: moved into $(BUILD_DIR)/docs/manual as per
 > Thomas P. suggestion]
 > Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
 > Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>

Committed series with the small comment of Thomas DS and the default
make target fixed, thanks!

-- 
Bye, Peter Korsgaard