[Buildroot] [PATCH 01/23 v5] gendoc infra: cosmetic fixes

[Buildroot] [PATCH 01/23 v5] gendoc infra: cosmetic fixes

[Yann E. MORIN]

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

- wrap lines to 80 characters
- fix space/tab mixup

Signed-off-by: Samuel Martin <s.martin49@gmail.com>
Acked-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
[yann.morin.1998 at free.fr: tested all but PDF]
Tested-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Acked-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
---
 docs/manual/manual.mk | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index 8d401a2..136f725 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -70,8 +70,8 @@ $$(O)/docs/$(1)/$(1).$(4): docs/$(1)/$(1).txt \
 	$$(Q)mkdir -p $$(@D)/.build
 	$$(Q)rsync -au docs/$(1)/*.txt $$(@D)/.build
 	$$(Q)a2x $(6) -f $(2) -d book -L -r $$(TOPDIR)/docs/images \
-	        -D $$(@D) $$(@D)/.build/$(1).txt \
-	        --asciidoc-opts="$$(MANUAL_$(2)_ASCIIDOC_OPTS)"
+		--asciidoc-opts="$$(MANUAL_$(2)_ASCIIDOC_OPTS)" \
+		-D $$(@D) $$(@D)/.build/$(1).txt
 	-$$(Q)rm -rf $$(@D)/.build
 endef
 
@@ -84,9 +84,12 @@ endef
 # The variable <DOCUMENT_NAME>_SOURCES defines the dependencies.
 ################################################################################
 define GENDOC
-$(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")
-$(call GENDOC_INNER,$(pkgname),pdf,pdf,pdf,PDF,--dblatex-opts "-P latex.output.revhistory=0")
+$(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")
+$(call GENDOC_INNER,$(pkgname),pdf,pdf,pdf,PDF,\
+	--dblatex-opts "-P latex.output.revhistory=0")
 $(call GENDOC_INNER,$(pkgname),text,text,text,text)
 $(call GENDOC_INNER,$(pkgname),epub,epub,epub,ePUB)
 clean: $(pkgname)-clean
-- 
1.9.1

[Buildroot] [PATCH 02/23 v5] gendoc infra: move manual build location into $(BUILD_DIR)/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>
Reviewed-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
[yann.morin.1998 at free.fr: tested all but PDF]
Tested-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
---
 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..e86f872 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -1,11 +1,20 @@
+$(BUILD_DIR)/$(pkgname):
+	$(Q)mkdir -p $@
+
+manual-rsync: $(BUILD_DIR)/$(pkgname)
+	$(Q)$(call MESSAGE,"Preparing the manual sources...")
+	$(Q)rsync -a docs/$(pkgname)/ $(BUILD_DIR)/$(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)/$(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)/$(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)/$(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)/$(pkgname)
 .PHONY: $(pkgname) $(pkgname)-clean manual-update-lists
 endef
 
-- 
1.9.1

[Buildroot] [PATCH 03/23 v5] 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 e86f872..09d8b18 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)/$(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)/$(1)/$(1).txt
+# install the generated manual
+	$$(MANUAL_$(2)_INSTALL_CMDS)
 endef
 
 ################################################################################
-- 
1.9.1

[Buildroot] [PATCH 04/23 v5] 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 fail 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]
Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
---
 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 09d8b18..b5856b9 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):
+	$$(error 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)/$(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 05/23 v5] 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>
---
 docs/manual/manual.mk | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index b5856b9..4825a70 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 06/23 v5] 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>
---
 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 4825a70..bae517b 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -1,10 +1,3 @@
-$(BUILD_DIR)/$(pkgname):
-	$(Q)mkdir -p $@
-
-manual-rsync: $(BUILD_DIR)/$(pkgname)
-	$(Q)$(call MESSAGE,"Preparing the manual sources...")
-	$(Q)rsync -a docs/$(pkgname)/ $(BUILD_DIR)/$(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)/$(pkgname)
@@ -127,6 +120,13 @@ endef
 # The variable <DOCUMENT_NAME>_SOURCES defines the dependencies.
 ################################################################################
 define GENDOC
+$$(BUILD_DIR)/$(pkgname):
+	$$(Q)mkdir -p $$@
+
+$(pkgname)-rsync: $$(BUILD_DIR)/$(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 07/23 v5] 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>
---
 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 bae517b..135ab3d 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 08/23 v5] 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>
---
 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 135ab3d..08addd1 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)/$(pkgname)
 	$(Q)$(call MESSAGE,"Updating the manual lists...")
 	$(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(BUILD_DIR)/$(pkgname) \
@@ -140,7 +141,7 @@ $(call GENDOC_INNER,$(pkgname),epub,epub,epub,ePUB)
 clean: $(pkgname)-clean
 $(pkgname)-clean:
 	$$(Q)$$(RM) -rf $$(BUILD_DIR)/$(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 09/23 v5] 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>
---
 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 08addd1..0ae2d83 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -7,7 +7,7 @@ manual-update-lists: manual-check-dependencies-lists $(BUILD_DIR)/$(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)/$(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 10/23 v5] docs/manual: do not hardcode name of the generated document

[Yann E. MORIN]

Currently, GENDOC_INNER har-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).

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>
---
 docs/manual/manual.mk | 67 ++++++++++++++++++++++++++-------------------------
 1 file changed, 34 insertions(+), 33 deletions(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index 0ae2d83..a37f5e7 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -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)"
+$(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)/$(1)/$(1).$(4) $$(@D)
+define $(2)_$(3)_INSTALL_CMDS
+	$$(Q)cp -f $$(BUILD_DIR)/$(1)/$(1).$(5) $$(@D)
 endef
 endif
 
-ifeq ($(4)-$$(MANUAL_XSLTPROC_IS_BROKEN),pdf-y)
-$$(O)/docs/$(1)/$(1).$(4):
+ifeq ($(5)-$$(MANUAL_XSLTPROC_IS_BROKEN),pdf-y)
+$$(O)/docs/$(1)/$(1).$(5):
 	$$(error 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): $$($$(call UPPERCASE,$(1))_SOURCES) \
-			   manual-check-dependencies \
-			   manual-check-dependencies-$(3) \
-			   manual-prepare-sources
-	$$(Q)$$(call MESSAGE,"Generating $(5) $(1)...")
+$$(O)/docs/$(1)/$(1).$(5): $$($$(call UPPERCASE,$(1))_SOURCES) \
+			   $(1)-check-dependencies \
+			   $(1)-check-dependencies-$(4) \
+			   $(1)-prepare-sources
+	$$(Q)$$(call MESSAGE,"Generating $(6) $(1)...")
 	$$(Q)mkdir -p $$(@D)
-	$$(Q)a2x $(6) -f $(2) -d book -L -r $$(TOPDIR)/docs/images \
-		$$(MANUAL_$(2)_A2X_OPTS) \
-		--asciidoc-opts="$$(MANUAL_$(2)_ASCIIDOC_OPTS)" \
+	$$(Q)a2x $(7) -f $(3) -d book -L -r $$(TOPDIR)/docs/images \
+		$$($(2)_$(3)_A2X_OPTS) \
+		--asciidoc-opts="$$($(2)_$(3)_ASCIIDOC_OPTS)" \
 		$$(BUILD_DIR)/$(1)/$(1).txt
 # install the generated manual
-	$$(MANUAL_$(2)_INSTALL_CMDS)
+	$$($(2)_$(3)_INSTALL_CMDS)
 endif
 endef
 
@@ -129,17 +130,17 @@ $(pkgname)-rsync: $$(BUILD_DIR)/$(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)/$(pkgname)
-- 
1.9.1

[Buildroot] [PATCH 11/23 v5] docs/manual: allow a document to declare where its ressources are

[Yann E. MORIN]

Avoids hard-coding document's ressources in GENDOC_INNER, so we can
generate another document with different ressources (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>
---
 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 a37f5e7..befd1ed 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -106,7 +106,8 @@ $$(O)/docs/$(1)/$(1).$(5): $$($$(call UPPERCASE,$(1))_SOURCES) \
 			   $(1)-prepare-sources
 	$$(Q)$$(call MESSAGE,"Generating $(6) $(1)...")
 	$$(Q)mkdir -p $$(@D)
-	$$(Q)a2x $(7) -f $(3) -d book -L -r $$(TOPDIR)/docs/images \
+	$$(Q)a2x $(7) -f $(3) -d book -L \
+		$$(foreach r,$$($(2)_RESSOURCES),-r $$(r)) \
 		$$($(2)_$(3)_A2X_OPTS) \
 		--asciidoc-opts="$$($(2)_$(3)_ASCIIDOC_OPTS)" \
 		$$(BUILD_DIR)/$(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>_RESSOURCES defines where the document's
+# resources, such as images, are located; must be an absolute path.
 ################################################################################
 define GENDOC
 $$(BUILD_DIR)/$(pkgname):
@@ -148,4 +151,5 @@ $(pkgname)-clean:
 endef
 
 MANUAL_SOURCES = $(sort $(wildcard docs/manual/*.txt) $(wildcard docs/images/*))
+MANUAL_RESSOURCES = $(TOPDIR)/docs/images
 $(eval $(call GENDOC))
-- 
1.9.1

[Buildroot] [PATCH 12/23 v5] 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.

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.

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>
---
 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 befd1ed..9a50e1d 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -53,14 +53,15 @@ MANUAL_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 @@ MANUAL_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 manual 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)/$(1)/$(1).$(5) $$(@D)
+define $(2)_$(4)_INSTALL_CMDS
+	$$(Q)cp -f $$(BUILD_DIR)/$(1)/$(1).$(6) $$(@D)
 endef
 endif
 
-ifeq ($(5)-$$(MANUAL_XSLTPROC_IS_BROKEN),pdf-y)
-$$(O)/docs/$(1)/$(1).$(5):
+ifeq ($(6)-$$(MANUAL_XSLTPROC_IS_BROKEN),pdf-y)
+$$(O)/docs/$(1)/$(1).$(6):
 	$$(error 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).$(5): $$($$(call UPPERCASE,$(1))_SOURCES) \
+$$(O)/docs/$(1)/$(1).$(6): $$($$(call UPPERCASE,$(1))_SOURCES) \
 			   $(1)-check-dependencies \
-			   $(1)-check-dependencies-$(4) \
+			   $(1)-check-dependencies-$(5) \
 			   $(1)-prepare-sources
-	$$(Q)$$(call MESSAGE,"Generating $(6) $(1)...")
+	$$(Q)$$(call MESSAGE,"Generating $(7) $(1)...")
 	$$(Q)mkdir -p $$(@D)
-	$$(Q)a2x $(7) -f $(3) -d book -L \
+	$$(Q)a2x $(8) -f $(4) -d book -L \
 		$$(foreach r,$$($(2)_RESSOURCES),-r $$(r)) \
-		$$($(2)_$(3)_A2X_OPTS) \
-		--asciidoc-opts="$$($(2)_$(3)_ASCIIDOC_OPTS)" \
+		$$($(2)_$(4)_A2X_OPTS) \
+		--asciidoc-opts="$$($(2)_$(4)_ASCIIDOC_OPTS)" \
 		$$(BUILD_DIR)/$(1)/$(1).txt
 # install the generated manual
-	$$($(2)_$(3)_INSTALL_CMDS)
+	$$($(2)_$(4)_INSTALL_CMDS)
 endif
 endef
 
@@ -129,21 +130,26 @@ $$(BUILD_DIR)/$(pkgname):
 
 $(pkgname)-rsync: $$(BUILD_DIR)/$(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)/$(pkgname)
-- 
1.9.1

[Buildroot] [PATCH 13/23 v5] 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 shinny 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>
---
 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 9a50e1d..6744e4a 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)/$(pkgname)
-	$(Q)$(call MESSAGE,"Updating the manual lists...")
-	$(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(BUILD_DIR)/$(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 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:
@@ -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)/$(pkgname)
+	$(Q)$(call MESSAGE,"Updating the manual lists...")
+	$(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(BUILD_DIR)/$(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_RESSOURCES = $(TOPDIR)/docs/images
 $(eval $(call GENDOC))
-- 
1.9.1

[Buildroot] [PATCH 14/23 v5] 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>
---
 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 6744e4a..cd944fa 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 the manual"; \
@@ -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 the pdf manual"; \
 		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 15/23 v5] docs/manual: allow documents to define some hooks, as for a package

[Yann E. MORIN]

Allow documents to define two hooks:
  - DOC_EXTRA_CHECK_DEPENDENCIES
    to check for extra dependencies required by this document
  - DOC_EXTRA_CHECK_DEPENDENCIES_FMT
    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>

---
Changes v1 -> v2:
  - call post-extract hook in rsync rule
---
 docs/manual/manual.mk | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index cd944fa..52fac0e 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -55,10 +55,9 @@ $(1): $(1)-$(5)
 .PHONY: $(1)-$(5)
 $(1)-$(5): $$(O)/docs/$(1)/$(1).$(6)
 
-$(1)-check-dependencies: gendoc-check-dependencies
-
 gendoc-check-dependencies-$(5):
 $(1)-check-dependencies-$(5): gendoc-check-dependencies-$(5)
+	$$(Q)$$(foreach hook,$$($(2)_CHECK_EXTRA_DEPENDENCIES_$(5)_HOOKS),$$(call $$(hook))$$(sep))
 
 $(2)_$(4)_ASCIIDOC_CONF = $(3)/asciidoc-$(4).conf
 ifneq ($$(wildcard $$($(2)_$(4)_ASCIIDOC_CONF)),)
@@ -110,12 +109,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_EXTRA_DEPENDENCIES_HOOKS),$$(call $$(hook))$$(sep))
+
 $$(BUILD_DIR)/$(pkgname):
 	$$(Q)mkdir -p $$@
 
+# Single line, because splitting a foreach is not easy...
 $(pkgname)-rsync: $$(BUILD_DIR)/$(pkgname)
 	$$(Q)$$(call MESSAGE,"Preparing the $(pkgname) sources...")
 	$$(Q)rsync -a $(pkgdir) $$^
+	$$(Q)$$(foreach hook,$$($$(call UPPERCASE,$(pkgname))_POST_EXTRACT_HOOKS),$$(call $$(hook))$$(sep))
 
 $(pkgname)-prepare-sources: $(pkgname)-rsync
 
-- 
1.9.1

[Buildroot] [PATCH 16/23 v5] docs/manual: use the new hooks instead of gendoc rules

[Yann E. MORIN]

Also reorder a bit the definition of the variables, to more ressemble
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>
---
 docs/manual/manual.mk | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index 52fac0e..f3638a7 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -150,25 +150,26 @@ 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_RESSOURCES = $(TOPDIR)/docs/images
 
-# 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)/$(pkgname)
+# Our manual needs to generate lists
+define MANUAL_GEN_LISTS
 	$(Q)$(call MESSAGE,"Updating the manual lists...")
 	$(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(BUILD_DIR)/$(pkgname) \
 		BR2_EXTERNAL=$(TOPDIR)/support/dummy-external \
 		python -B $(TOPDIR)/support/scripts/gen-manual-lists.py
+endef
+MANUAL_POST_EXTRACT_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_EXTRA_DEPENDENCIES_HOOKS += MANUAL_CHECK_LISTS_DEPS
 
-MANUAL_SOURCES = $(sort $(wildcard docs/manual/*.txt) $(wildcard docs/images/*))
-MANUAL_RESSOURCES = $(TOPDIR)/docs/images
 $(eval $(call GENDOC))
-- 
1.9.1

[Buildroot] [PATCH 17/23 v5] docs/manual: always look for ressources in destination directory

[Yann E. MORIN]

Our manual does not use external filters in asciidoc, so we are happy
with just looking for ressources 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 ressources 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>

---
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 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index f3638a7..e649ffe 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -92,7 +92,7 @@ $$(O)/docs/$(1)/$(1).$(6): $$($$(call UPPERCASE,$(1))_SOURCES) \
 	$$(Q)$$(call MESSAGE,"Generating $(7) $(1)...")
 	$$(Q)mkdir -p $$(@D)
 	$$(Q)a2x $(8) -f $(4) -d book -L \
-		$$(foreach r,$$($(2)_RESSOURCES),-r $$(r)) \
+		$$(foreach r,$$($(2)_RESSOURCES),-r $$(r)) -r $$(@D) \
 		$$($(2)_$(4)_A2X_OPTS) \
 		--asciidoc-opts="$$($(2)_$(4)_ASCIIDOC_OPTS)" \
 		$$(BUILD_DIR)/$(1)/$(1).txt
-- 
1.9.1

[Buildroot] [PATCH 18/23 v5] 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>
---
 Makefile              |   1 +
 docs/manual/manual.mk | 148 --------------------------------------------------
 package/gendoc.mk     | 147 +++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 148 insertions(+), 148 deletions(-)
 create mode 100644 package/gendoc.mk

diff --git a/Makefile b/Makefile
index e788f1b..28f2097 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 e649ffe..85999c6 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -1,151 +1,3 @@
-# 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 the manual"; \
-		exit 1; \
-	fi
-	$(Q)if [ -z "`which w3m 2>/dev/null`" ]; then \
-		echo "You need w3m on your host to generate the manual"; \
-		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 the pdf manual"; \
-		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.
-#
-#  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)
-
-gendoc-check-dependencies-$(5):
-$(1)-check-dependencies-$(5): gendoc-check-dependencies-$(5)
-	$$(Q)$$(foreach hook,$$($(2)_CHECK_EXTRA_DEPENDENCIES_$(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 manual 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)/$(1)/$(1).$(6) $$(@D)
-endef
-endif
-
-ifeq ($(6)-$$(MANUAL_XSLTPROC_IS_BROKEN),pdf-y)
-$$(O)/docs/$(1)/$(1).$(6):
-	$$(error 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).$(6): $$($$(call UPPERCASE,$(1))_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)_RESSOURCES),-r $$(r)) -r $$(@D) \
-		$$($(2)_$(4)_A2X_OPTS) \
-		--asciidoc-opts="$$($(2)_$(4)_ASCIIDOC_OPTS)" \
-		$$(BUILD_DIR)/$(1)/$(1).txt
-# install the generated manual
-	$$($(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>_RESSOURCES 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_EXTRA_DEPENDENCIES_HOOKS),$$(call $$(hook))$$(sep))
-
-$$(BUILD_DIR)/$(pkgname):
-	$$(Q)mkdir -p $$@
-
-# Single line, because splitting a foreach is not easy...
-$(pkgname)-rsync: $$(BUILD_DIR)/$(pkgname)
-	$$(Q)$$(call MESSAGE,"Preparing the $(pkgname) sources...")
-	$$(Q)rsync -a $(pkgdir) $$^
-	$$(Q)$$(foreach hook,$$($$(call UPPERCASE,$(pkgname))_POST_EXTRACT_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)/$(pkgname)
-.PHONY: $(pkgname) $(pkgname)-clean
-endef
-
 ################################################################################
 # The Buildroot manual
 ################################################################################
diff --git a/package/gendoc.mk b/package/gendoc.mk
new file mode 100644
index 0000000..b859860
--- /dev/null
+++ b/package/gendoc.mk
@@ -0,0 +1,147 @@
+# 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 the manual"; \
+		exit 1; \
+	fi
+	$(Q)if [ -z "`which w3m 2>/dev/null`" ]; then \
+		echo "You need w3m on your host to generate the manual"; \
+		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 the pdf manual"; \
+		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.
+#
+#  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)
+
+gendoc-check-dependencies-$(5):
+$(1)-check-dependencies-$(5): gendoc-check-dependencies-$(5)
+	$$(Q)$$(foreach hook,$$($(2)_CHECK_EXTRA_DEPENDENCIES_$(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 manual 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)/$(1)/$(1).$(6) $$(@D)
+endef
+endif
+
+ifeq ($(6)-$$(MANUAL_XSLTPROC_IS_BROKEN),pdf-y)
+$$(O)/docs/$(1)/$(1).$(6):
+	$$(error 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).$(6): $$($$(call UPPERCASE,$(1))_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)_RESSOURCES),-r $$(r)) -r $$(@D) \
+		$$($(2)_$(4)_A2X_OPTS) \
+		--asciidoc-opts="$$($(2)_$(4)_ASCIIDOC_OPTS)" \
+		$$(BUILD_DIR)/$(1)/$(1).txt
+# install the generated manual
+	$$($(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>_RESSOURCES 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_EXTRA_DEPENDENCIES_HOOKS),$$(call $$(hook))$$(sep))
+
+$$(BUILD_DIR)/$(pkgname):
+	$$(Q)mkdir -p $$@
+
+# Single line, because splitting a foreach is not easy...
+$(pkgname)-rsync: $$(BUILD_DIR)/$(pkgname)
+	$$(Q)$$(call MESSAGE,"Preparing the $(pkgname) sources...")
+	$$(Q)rsync -a $(pkgdir) $$^
+	$$(Q)$$(foreach hook,$$($$(call UPPERCASE,$(pkgname))_POST_EXTRACT_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)/$(pkgname)
+.PHONY: $(pkgname) $(pkgname)-clean
+endef
-- 
1.9.1

[Buildroot] [PATCH 0/23 v5] 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-4 from Samuel, virtually untouched by me, save for the
    check for xsltproc, see the changelog in patch 4;

  - then, patches 5-16 to remove hard-coded reference to 'manual'
    in either GENDOC or GENDOC_INNER, and to remove hard-coded paths to
    our manual, and to properly separate GENDOC generic rules from
    document-specific rules, and make GENDOC look more like the
    pkg-XXX infrastructures;

  - finally, patches 17-18 allow building document from br2-external.

There are a few shortcomings here and there, be sure to read the
post-commit notes.


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 52fac6a2f7bba55fb78a7a1354eef7be5bba9f78:

  libelf: Removes the package (2014-09-14 00:11:20 +0200)

are available in the git repository at:

  git://gitorious.org/buildroot/buildroot.git yem/manual

for you to fetch changes up to cace268e0a2d0419476bc7c1952f753857a863a3:

  docs/manual: document the asciidoc infra (2014-09-14 11:33:34 +0200)

----------------------------------------------------------------
Samuel Martin (4):
      gendoc infra: cosmetic fixes
      gendoc infra: move manual build location into $(BUILD_DIR)/manual
      gendoc infra: avoid a2x warning
      gendoc infra: disable pdf manual generation if xsltproc is buggy

Yann E. MORIN (19):
      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 ressources 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 ressources 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
      Makefile: enable generating documents from br2-external
      docs/manual: document the asciidoc infra

 Makefile                                 |   2 +
 docs/manual/adding-packages-asciidoc.txt | 118 +++++++++++++++++++++++
 docs/manual/adding-packages.txt          |   2 +
 docs/manual/manual.mk                    | 104 ++++-----------------
 package/doc-asciidoc.mk                  | 156 +++++++++++++++++++++++++++++++
 5 files changed, 294 insertions(+), 88 deletions(-)
 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 19/23 v5] 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>
---
 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} (80%)

diff --git a/Makefile b/Makefile
index 28f2097..8f56f1f 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 85999c6..b221664 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -24,4 +24,4 @@ define MANUAL_CHECK_LISTS_DEPS
 endef
 MANUAL_CHECK_EXTRA_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 80%
rename from package/gendoc.mk
rename to package/doc-asciidoc.mk
index b859860..4366f8a 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 the manual"; \
@@ -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 the pdf manual"; \
 		exit 1; \
@@ -32,8 +32,8 @@ 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.
+# 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,13 +50,13 @@ MANUAL_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)
 
-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_EXTRA_DEPENDENCIES_$(5)_HOOKS),$$(call $$(hook))$$(sep))
 
 $(2)_$(4)_ASCIIDOC_CONF = $(3)/asciidoc-$(4).conf
@@ -102,15 +102,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>_RESSOURCES 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_EXTRA_DEPENDENCIES_HOOKS),$$(call $$(hook))$$(sep))
 
 $$(BUILD_DIR)/$(pkgname):
@@ -124,24 +124,30 @@ $(pkgname)-rsync: $$(BUILD_DIR)/$(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)/$(pkgname)
 .PHONY: $(pkgname) $(pkgname)-clean
 endef
+
+################################################################################
+# asciidoc-document -- the target generator macro for asiciidoc documents
+################################################################################
+
+asciidoc-document = $(call ASCIIDOC)
-- 
1.9.1

[Buildroot] [PATCH 20/23 v5] 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>
---
 package/doc-asciidoc.mk | 39 ++++++++++++++++++++++-----------------
 1 file changed, 22 insertions(+), 17 deletions(-)

diff --git a/package/doc-asciidoc.mk b/package/doc-asciidoc.mk
index 4366f8a..38c9ced 100644
--- a/package/doc-asciidoc.mk
+++ b/package/doc-asciidoc.mk
@@ -104,6 +104,11 @@ 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>_RESSOURCES defines where the document's
 # resources, such as images, are located; must be an absolute path.
@@ -111,43 +116,43 @@ endef
 define ASCIIDOC
 # Single line, because splitting a foreach is not easy...
 $(pkgname)-check-dependencies: asciidoc-check-dependencies
-	$$(Q)$$(foreach hook,$$($$(call UPPERCASE,$(pkgname))_CHECK_EXTRA_DEPENDENCIES_HOOKS),$$(call $$(hook))$$(sep))
+	$$(Q)$$(foreach hook,$$($(2)_CHECK_EXTRA_DEPENDENCIES_HOOKS),$$(call $$(hook))$$(sep))
 
-$$(BUILD_DIR)/$(pkgname):
+$$(BUILD_DIR)/$(1):
 	$$(Q)mkdir -p $$@
 
 # Single line, because splitting a foreach is not easy...
-$(pkgname)-rsync: $$(BUILD_DIR)/$(pkgname)
-	$$(Q)$$(call MESSAGE,"Preparing the $(pkgname) sources...")
-	$$(Q)rsync -a $(pkgdir) $$^
-	$$(Q)$$(foreach hook,$$($$(call UPPERCASE,$(pkgname))_POST_EXTRACT_HOOKS),$$(call $$(hook))$$(sep))
+$(1)-rsync: $$(BUILD_DIR)/$(1)
+	$$(Q)$$(call MESSAGE,"Preparing the $(1) sources...")
+	$$(Q)rsync -a $(3) $$^
+	$$(Q)$$(foreach hook,$$($(2)_POST_EXTRACT_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)/$(pkgname)
-.PHONY: $(pkgname) $(pkgname)-clean
+clean: $(1)-clean
+$(1)-clean:
+	$$(Q)$$(RM) -rf $$(BUILD_DIR)/$(1)
+.PHONY: $(1) $(1)-clean
 endef
 
 ################################################################################
 # asciidoc-document -- the target generator macro for asiciidoc documents
 ################################################################################
 
-asciidoc-document = $(call ASCIIDOC)
+asciidoc-document = $(call ASCIIDOC,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir))
-- 
1.9.1

[Buildroot] [PATCH 21/23 v5] 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>
---
 docs/manual/manual.mk   |  2 +-
 package/doc-asciidoc.mk | 10 ++++------
 2 files changed, 5 insertions(+), 7 deletions(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index b221664..9a86113 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -8,7 +8,7 @@ MANUAL_RESSOURCES = $(TOPDIR)/docs/images
 # Our manual needs to generate lists
 define MANUAL_GEN_LISTS
 	$(Q)$(call MESSAGE,"Updating the manual lists...")
-	$(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(BUILD_DIR)/$(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 38c9ced..13e4479 100644
--- a/package/doc-asciidoc.mk
+++ b/package/doc-asciidoc.mk
@@ -118,16 +118,14 @@ define ASCIIDOC
 $(pkgname)-check-dependencies: asciidoc-check-dependencies
 	$$(Q)$$(foreach hook,$$($(2)_CHECK_EXTRA_DEPENDENCIES_HOOKS),$$(call $$(hook))$$(sep))
 
-$$(BUILD_DIR)/$(1):
-	$$(Q)mkdir -p $$@
-
 # Single line, because splitting a foreach is not easy...
-$(1)-rsync: $$(BUILD_DIR)/$(1)
+$$(BUILD_DIR)/$(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_EXTRACT_HOOKS),$$(call $$(hook))$$(sep))
 
-$(1)-prepare-sources: $(1)-rsync
+$(1)-prepare-sources: $$(BUILD_DIR)/$(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 22/23 v5] 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>
---
 Makefile | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Makefile b/Makefile
index 8f56f1f..3075d0a 100644
--- a/Makefile
+++ b/Makefile
@@ -933,5 +933,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 23/23 v5] 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>
---
 docs/manual/adding-packages-asciidoc.txt | 118 +++++++++++++++++++++++++++++++
 docs/manual/adding-packages.txt          |   2 +
 2 files changed, 120 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..b8821ee
--- /dev/null
+++ b/docs/manual/adding-packages-asciidoc.txt
@@ -0,0 +1,118 @@
+// -*- 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 packages infrastructures are suffixed with +-package+, the documents
+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 $(widcard $(pkgdir)/*))
+08: $(eval $(call asciidoc-document))
+----
+
+On line 7, the Makefile declares what the sources of the document are.
+Currently, it is expected that the document's sources are only local;
+Buildroot will not attempt to download anything to render a document.
+Thus, you must indicate where the sources are. Usually, the string
+above is sufficient for a document with no sub-directory structure.
+
+Finally, on line 8, we call the +asciidoc-document+ function, which 
+generates all the Makefile code necessary to render the document.
+
+==== +asciidoc-document+ reference
+
+The list of variables that can be set in a +.mk+ file to give metadata
+information is (assuming the document name is +foo+) :
+
+* +FOO_SOURCES+, mandatory, defines the source files for the document.
+
+* +FOO_RESSOURCES+, optional, may contain a space-separated list of paths
+  to so-called ressources (CSS, images...) By default, none.
+
+There are also additional hooks (see xref:hooks[] for what a hook is),
+that a document may set to define extra actions to be done at various
+steps:
+
+* +FOO_POST_EXTRACT_HOOKS+ to run additional commands after the sources
+  have been copied by Buildroot. This can be used for, for example,
+  generating part of the manual with information extracted from the
+  tree. As an example, Buildroot uses that to generate the tables in the
+  appendices.
+
+* +FOO_EXTRA_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_EXTRA_CHECK_DEPENDENCIES_<FMT>_HOOKS+, to run additional tests for
+  the specified format +<FMT>+ (see the list of rendered formats, above.)
+
+Here is a complete example that uses all variables and all hooks:
+
+----
+01: ################################################################################
+02: #
+03: # foo-document
+04: #
+05: ################################################################################
+06: 
+07: FOO_SOURCES = $(sort $(widcard $(pkgdir)/*))
+08: FOO_RESSOURCES = $(sort $(wildcard $(pkgdir)/ressources))
+09: 
+10: define FOO_GEN_EXTRA_DOC
+11:     /path/to/generate-script --outdir=$(@D)
+12: endef
+13: FOO_POST_EXTRACT_HOOK += 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_EXTRA_CHECK_DEPENDENCIES += 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_EXTRA_CHECK_DEPENDENCIES_TEXT += 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 0/23 v5] gendoc infra: make it useable for other documents (branch yem/manual)

[Yann E. MORIN]

All,

Gee... I forgot to update the series description in the cover letter.
Sorry... :-(

Here it is:

On 2014-09-14 13:07 +0200, Yann E. MORIN spake thusly:
> 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-4 from Samuel, virtually untouched by me, save for the
>     check for xsltproc, see the changelog in patch 4;

Unchanged from previous iteration.

>   - then, patches 5-16 to remove hard-coded reference to 'manual'
>     in either GENDOC or GENDOC_INNER, and to remove hard-coded paths to
>     our manual, and to properly separate GENDOC generic rules from
>     document-specific rules, and make GENDOC look more like the
>     pkg-XXX infrastructures;

Replaced with:

  - patches 5-14: properly separate our manual defintion from the actual
    infrastructure;

  - patches 15-16: make the gendoc infra behave more like the pkg
    infras, by using hooks rather than extra rules;

  - patch 17: workaround asciidoc deficiency when calling filters;

  - patches 18-19: move and rename 'gendoc' to 'doc-asciidoc';

  - patches 20-21: 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);

  - patch 22: allow using doc-asciidoc from br2-external;

  - patch 23: 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/brsh-manual.html

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  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 05/23 v5] docs/manual: get rid of legacy comment in GENDOC

[Thomas De Schampheleire]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> 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>

[Buildroot] [PATCH 04/23 v5] gendoc infra: disable pdf manual generation if xsltproc is buggy

[Thomas De Schampheleire]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> 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 fail 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]
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> ---
>  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 09d8b18..b5856b9 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):
> +       $$(error 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')

I think this should be $(warning) instead of $(error), because if you
run 'make manual' with a broken xsltproc, then the manual generation
will stop at the pdf manual, even though the following manuals (text
and ePUB) could have been built without issue.

[Buildroot] [PATCH 06/23 v5] docs/manual: copying the manual sources is a common action

[Thomas De Schampheleire]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> 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>
> ---
>  docs/manual/manual.mk | 14 +++++++-------
>  1 file changed, 7 insertions(+), 7 deletions(-)
>

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

[Buildroot] [PATCH 04/23 v5] gendoc infra: disable pdf manual generation if xsltproc is buggy

[Yann E. MORIN]

Thomas, All,

On 2014-09-19 22:00 +0200, Thomas De Schampheleire spake thusly:
> On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> > 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].
[--SNIP--]
> >  ################################################################################
> >  # 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):
> > +       $$(error 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')
> 
> I think this should be $(warning) instead of $(error), because if you
> run 'make manual' with a broken xsltproc, then the manual generation
> will stop at the pdf manual, even though the following manuals (text
> and ePUB) could have been built without issue.

Yup, it always bothered me. But we can just skip it, indeed.

Another point about this hunk: the indentation of $(error...) is wrong:
it is not the commands of the rule. I.e. it is not interpreted by the
shell for the $$(O)/docs/$(1)/$(1).$(4) rule, but really by make itself.

So, we should probably have this instead:

    ifeq ($(4)-$$(MANUAL_XSLTPROC_IS_BROKEN),pdf-y)
    $$(error ........)
    $$(O)/docs/$(1)/$(1).$(4):
    else
    $$(O)/docs/$(1)/$(1).$(4):
        a2x ....
    endif

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  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 07/23 v5] docs/manual: simplify generation dependencies

[Thomas De Schampheleire]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> 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>

Just a side note: I've been wondering if we should change the
extension of the manual source files from .txt to .asciidoc. This
seems to be the default extension and will make sure that vim selects
the right syntax highlighting by default. I guess other editors would
do the same (not tested).
What do you think of that? Or is it unnecessary?
On Debian, vim does not parse the modeline by default for security
reasons, so the first two lines in each of these .txt files do not
help there.

Best regards,
Thomas

[Buildroot] [PATCH 04/23 v5] gendoc infra: disable pdf manual generation if xsltproc is buggy

[Thomas De Schampheleire]

On Fri, Sep 19, 2014 at 10:15 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Thomas, All,
>
> On 2014-09-19 22:00 +0200, Thomas De Schampheleire spake thusly:
>> On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
>> > 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].
> [--SNIP--]
>> >  ################################################################################
>> >  # 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):
>> > +       $$(error 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')
>>
>> I think this should be $(warning) instead of $(error), because if you
>> run 'make manual' with a broken xsltproc, then the manual generation
>> will stop at the pdf manual, even though the following manuals (text
>> and ePUB) could have been built without issue.
>
> Yup, it always bothered me. But we can just skip it, indeed.
>
> Another point about this hunk: the indentation of $(error...) is wrong:
> it is not the commands of the rule. I.e. it is not interpreted by the
> shell for the $$(O)/docs/$(1)/$(1).$(4) rule, but really by make itself.
>
> So, we should probably have this instead:
>
>     ifeq ($(4)-$$(MANUAL_XSLTPROC_IS_BROKEN),pdf-y)
>     $$(error ........)
>     $$(O)/docs/$(1)/$(1).$(4):
>     else
>     $$(O)/docs/$(1)/$(1).$(4):
>         a2x ....
>     endif

Yes, but with $(warning) then...

Best regards,
Thomas

[Buildroot] [PATCH 01/23 v5] gendoc infra: cosmetic fixes

[Thomas Petazzoni]

Dear Yann E. MORIN,

On Sun, 14 Sep 2014 13:07:35 +0200, Yann E. MORIN wrote:
> From: Samuel Martin <s.martin49@gmail.com>
> 
> - wrap lines to 80 characters
> - fix space/tab mixup
> 
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
> Acked-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
> [yann.morin.1998 at free.fr: tested all but PDF]
> Tested-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> Acked-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> ---
>  docs/manual/manual.mk | 13 ++++++++-----
>  1 file changed, 8 insertions(+), 5 deletions(-)

Applied, thanks.

Thomas
-- 
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com

[Buildroot] [PATCH 02/23 v5] gendoc infra: move manual build location into $(BUILD_DIR)/manual

[Thomas Petazzoni]

Dear Yann E. MORIN,

On Sun, 14 Sep 2014 13:07:36 +0200, Yann E. MORIN wrote:

> diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
> index 136f725..e86f872 100644
> --- a/docs/manual/manual.mk
> +++ b/docs/manual/manual.mk
> @@ -1,11 +1,20 @@
> +$(BUILD_DIR)/$(pkgname):
> +	$(Q)mkdir -p $@

Shouldn't we do things in $(BUILD_DIR)/docs/$(pkgname) instead? Even
though it's unlikely, I'm a bit worried about conflicting names between
real packages and documentations.

Thomas
-- 
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com

[Buildroot] [PATCH 02/23 v5] gendoc infra: move manual build location into $(BUILD_DIR)/manual

[Yann E. MORIN]

Thomas, All,

On 2014-09-21 21:13 +0200, Thomas Petazzoni spake thusly:
> On Sun, 14 Sep 2014 13:07:36 +0200, Yann E. MORIN wrote:
> > diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
> > index 136f725..e86f872 100644
> > --- a/docs/manual/manual.mk
> > +++ b/docs/manual/manual.mk
> > @@ -1,11 +1,20 @@
> > +$(BUILD_DIR)/$(pkgname):
> > +	$(Q)mkdir -p $@
> 
> Shouldn't we do things in $(BUILD_DIR)/docs/$(pkgname) instead? Even
> though it's unlikely, I'm a bit worried about conflicting names between
> real packages and documentations.

Unlkikely, but I don't mind moving the documents to a sub-dir. I'll do
the change before I respin.

Thanks!

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  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 08/23 v5] docs/manual: manual-update-lists is not a generic GENDOC rule

[Thomas De Schampheleire]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> 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>
> ---
>  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 135ab3d..08addd1 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)/$(pkgname)
>         $(Q)$(call MESSAGE,"Updating the manual lists...")
>         $(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(BUILD_DIR)/$(pkgname) \
> @@ -140,7 +141,7 @@ $(call GENDOC_INNER,$(pkgname),epub,epub,epub,ePUB)
>  clean: $(pkgname)-clean
>  $(pkgname)-clean:
>         $$(Q)$$(RM) -rf $$(BUILD_DIR)/$(pkgname)
> -.PHONY: $(pkgname) $(pkgname)-clean manual-update-lists
> +.PHONY: $(pkgname) $(pkgname)-clean
>  endef
>
>  MANUAL_SOURCES = $(sort $(wildcard docs/manual/*.txt) $(wildcard docs/images/*))


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

[Buildroot] [PATCH 09/23 v5] docs/manual: move manual-prepare-sources rule into GENDOC

[Thomas De Schampheleire]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> 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>
> ---
>  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 08addd1..0ae2d83 100644
> --- a/docs/manual/manual.mk
> +++ b/docs/manual/manual.mk
> @@ -7,7 +7,7 @@ manual-update-lists: manual-check-dependencies-lists $(BUILD_DIR)/$(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)/$(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,\

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

[Buildroot] [PATCH 10/23 v5] docs/manual: do not hardcode name of the generated document

[Thomas De Schampheleire]

Hi Yann,

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Currently, GENDOC_INNER har-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).
>
> 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>
> ---
>  docs/manual/manual.mk | 67 ++++++++++++++++++++++++++-------------------------
>  1 file changed, 34 insertions(+), 33 deletions(-)
>
> diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
> index 0ae2d83..a37f5e7 100644
> --- a/docs/manual/manual.mk
> +++ b/docs/manual/manual.mk
> @@ -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

In this comment and elsewhere in the file, there are still some
mentions to 'manual'. This patch could be a good opportunity to rename
these occurrences into 'document' or something.

> -MANUAL_$(2)_A2X_OPTS =
> -ifneq ($$(filter $(3),html split-html),)
> -MANUAL_$(2)_A2X_OPTS += --destination-dir="$$(@D)"
> +$(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)/$(1)/$(1).$(4) $$(@D)
> +define $(2)_$(3)_INSTALL_CMDS
> +       $$(Q)cp -f $$(BUILD_DIR)/$(1)/$(1).$(5) $$(@D)
>  endef
>  endif
>
> -ifeq ($(4)-$$(MANUAL_XSLTPROC_IS_BROKEN),pdf-y)
> -$$(O)/docs/$(1)/$(1).$(4):
> +ifeq ($(5)-$$(MANUAL_XSLTPROC_IS_BROKEN),pdf-y)
> +$$(O)/docs/$(1)/$(1).$(5):
>         $$(error 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): $$($$(call UPPERCASE,$(1))_SOURCES) \
> -                          manual-check-dependencies \
> -                          manual-check-dependencies-$(3) \
> -                          manual-prepare-sources
> -       $$(Q)$$(call MESSAGE,"Generating $(5) $(1)...")
> +$$(O)/docs/$(1)/$(1).$(5): $$($$(call UPPERCASE,$(1))_SOURCES) \
> +                          $(1)-check-dependencies \
> +                          $(1)-check-dependencies-$(4) \
> +                          $(1)-prepare-sources
> +       $$(Q)$$(call MESSAGE,"Generating $(6) $(1)...")
>         $$(Q)mkdir -p $$(@D)
> -       $$(Q)a2x $(6) -f $(2) -d book -L -r $$(TOPDIR)/docs/images \
> -               $$(MANUAL_$(2)_A2X_OPTS) \
> -               --asciidoc-opts="$$(MANUAL_$(2)_ASCIIDOC_OPTS)" \
> +       $$(Q)a2x $(7) -f $(3) -d book -L -r $$(TOPDIR)/docs/images \
> +               $$($(2)_$(3)_A2X_OPTS) \
> +               --asciidoc-opts="$$($(2)_$(3)_ASCIIDOC_OPTS)" \
>                 $$(BUILD_DIR)/$(1)/$(1).txt
>  # install the generated manual
> -       $$(MANUAL_$(2)_INSTALL_CMDS)
> +       $$($(2)_$(3)_INSTALL_CMDS)
>  endif
>  endef
>
> @@ -129,17 +130,17 @@ $(pkgname)-rsync: $$(BUILD_DIR)/$(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)

I'm unsure about these double dollars here. In none of the other
infras do we add double dollars for the UPPERCASE call, when going
from outer to inner infra. There was some discussion on this in the
dollar threads, but I currently don't remember all the details.
Shouldn't we follow the same strategy as for the other infras here and
use single dollars for this UPPERCASE call?

Side note on this patch: it was not trivial to review this patch: it
combines the addition of the new argument with the shifting off
arguments 2-... It could have been more easy by first introducing the
argument as last one, and then performing the shift in another patch.
Anyway, I was able to review it using graphical diff, and aside from
the comments above this looks good.

Best regards,
Thomas

[Buildroot] [PATCH 11/23 v5] docs/manual: allow a document to declare where its ressources are

[Thomas De Schampheleire]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Avoids hard-coding document's ressources in GENDOC_INNER, so we can
> generate another document with different ressources (if any).

General comment to be fixed throughout this patch and other patches.

Other than that, this patch looks fine.

[Buildroot] [PATCH 12/23 v5] docs/manual: last pass at removing hard-coded path in GENDOC_INNER

[Thomas De Schampheleire]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> GENDOC_INNER still has one hard-coded path to the document's directory:
> the asciidoc .conf files.

In this patch you assume that the asciidoc configuration is
document-specific, but at least the current contents of
asciidoc-text.conf are global IMO: they simply make sure that
hyperlinks are represented in a sane way, and that images are not
shown (text document only). These are settings that apply to all
documents.
It can be useful to provide a mechanism for other documents to pass
additional configuration files, but at this moment it is not strictly
needed. I don't know if it makes sense to already provide a variable
for that, or rather wait for a real use case to add it (KISS
principle).

Awaiting the outcome of this consideration, I did not yet review the
patch in detail.

[Buildroot] [PATCH 11/23 v5] docs/manual: allow a document to declare where its ressources are

[Thomas De Schampheleire]

On Mon, Sep 22, 2014 at 9:26 PM, Thomas De Schampheleire
<patrickdepinguin@gmail.com> wrote:
> On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
>> Avoids hard-coding document's ressources in GENDOC_INNER, so we can
>> generate another document with different ressources (if any).
>
> General comment to be fixed throughout this patch and other patches.

The comment being: s/ressources/resources

>
> Other than that, this patch looks fine.

[Buildroot] [PATCH 13/23 v5] docs/manual: properly separate rules specific for our manual

[Thomas De Schampheleire]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Move the rules specific to our own manual, so that they do not interfere
> with the generic rules of GENDOC.
>
> Separate them with a shinny header. ;-)

shiny

other than that:

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

[Buildroot] [PATCH 05/23 v5] docs/manual: get rid of legacy comment in GENDOC

[Samuel Martin]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> 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: Samuel Martin <s.martin49@gmail.com>

--
Samuel

[Buildroot] [PATCH 06/23 v5] docs/manual: copying the manual sources is a common action

[Samuel Martin]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> 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: Samuel Martin <s.martin49@gmail.com>

-- 
Samuel

[Buildroot] [PATCH 07/23 v5] docs/manual: simplify generation dependencies

[Samuel Martin]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> 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: Samuel Martin <s.martin49@gmail.com>

-- 
Samuel

[Buildroot] [PATCH 08/23 v5] docs/manual: manual-update-lists is not a generic GENDOC rule

[Samuel Martin]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> 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>

Reviewed-by: Samuel Martin <s.martin49@gmail.com>

-- 
Samuel

[Buildroot] [PATCH 09/23 v5] docs/manual: move manual-prepare-sources rule into GENDOC

[Samuel Martin]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> 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>

Reviewed-by: Samuel Martin <s.martin49@gmail.com>

-- 
Samuel

[Buildroot] [PATCH 10/23 v5] docs/manual: do not hardcode name of the generated document

[Samuel Martin]

Yann,

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Currently, GENDOC_INNER har-codes some variables to have the name of the

s/har-codes/hard-codes/

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

With the aformentioned typo fixed, you can add:
Reviewed-by: Samuel Martin <s.martin49@gmail.com>

-- 
Samuel

[Buildroot] [PATCH 14/23 v5] docs/manual: rename the generic dependency rules

[Samuel Martin]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> 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>

-- 
Samuel

[Buildroot] [PATCH 15/23 v5] docs/manual: allow documents to define some hooks, as for a package

[Samuel Martin]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Allow documents to define two hooks:
>   - DOC_EXTRA_CHECK_DEPENDENCIES
>     to check for extra dependencies required by this document
>   - DOC_EXTRA_CHECK_DEPENDENCIES_FMT
>     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>

-- 
Samuel

[Buildroot] [PATCH 16/23 v5] docs/manual: use the new hooks instead of gendoc rules

[Samuel Martin]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Also reorder a bit the definition of the variables, to more ressemble
> 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>

--
Samuel

[Buildroot] [PATCH 17/23 v5] docs/manual: always look for ressources in destination directory

[Samuel Martin]

Yann,

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Our manual does not use external filters in asciidoc, so we are happy
> with just looking for ressources from our source tree.

s/ressources/resources/
(also in the patch title)

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

With the aformentioned typo fixed:
Reviewed-by: Samuel Martin <s.martin49@gmail.com>

-- 
Samuel

[Buildroot] [PATCH 18/23 v5] docs: separate the GENDOC infra from our manual definition

[Samuel Martin]

Yann,

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> 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>
> ---
>  Makefile              |   1 +
>  docs/manual/manual.mk | 148 --------------------------------------------------
>  package/gendoc.mk     | 147 +++++++++++++++++++++++++++++++++++++++++++++++++
>  3 files changed, 148 insertions(+), 148 deletions(-)
>  create mode 100644 package/gendoc.mk
>
[...]
> diff --git a/package/gendoc.mk b/package/gendoc.mk
> new file mode 100644
> index 0000000..b859860
> --- /dev/null
> +++ b/package/gendoc.mk
> @@ -0,0 +1,147 @@
> +# 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 the manual"; \
> +               exit 1; \
> +       fi
> +       $(Q)if [ -z "`which w3m 2>/dev/null`" ]; then \
> +               echo "You need w3m on your host to generate the manual"; \
> +               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 the pdf manual"; \
> +               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 = \

Maybe  this variable could be renamed as well.
It is more related to asciidoc/a2x than specific tou Buildroot's manual.

> +       $(shell xsltproc --maxvars 0 >/dev/null 2>/dev/null || echo y)
> +
[...]

Regards,

-- 
Samuel

[Buildroot] [PATCH 19/23 v5] docs: rename the GENDOC infrastructure

[Samuel Martin]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> 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>

-- 
Samuel

[Buildroot] [PATCH 20/23 v5] docs/asciidoc: call $(pkgname) and $(pkgdir) in a single place

[Samuel Martin]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> 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>

-- 
Samuel

[Buildroot] [PATCH 21/23 v5] docs/asciidoc: make it possible to use $(@D) in hooks

[Samuel Martin]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> 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>

Reviewed-by: Samuel Martin <s.martin49@gmail.com>

-- 
Samuel

[Buildroot] [PATCH 22/23 v5] Makefile: enable generating documents from br2-external

[Samuel Martin]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> 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>

> ---
>  Makefile | 1 +
>  1 file changed, 1 insertion(+)
>
> diff --git a/Makefile b/Makefile
> index 8f56f1f..3075d0a 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -933,5 +933,6 @@ print-version:
>         @echo $(BR2_VERSION_FULL)
>
>  include docs/manual/manual.mk
> +-include $(BR2_EXTERNAL)/docs/*/*.mk
>
>  .PHONY: $(noconfig_targets)
> --
> 1.9.1
>



-- 
Samuel

[Buildroot] [PATCH 23/23 v5] docs/manual: document the asciidoc infra

[Samuel Martin]

Yann,

On Sun, Sep 14, 2014 at 1:07 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>
> ---
>  docs/manual/adding-packages-asciidoc.txt | 118 +++++++++++++++++++++++++++++++
>  docs/manual/adding-packages.txt          |   2 +
>  2 files changed, 120 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..b8821ee
> --- /dev/null
> +++ b/docs/manual/adding-packages-asciidoc.txt
> @@ -0,0 +1,118 @@
> +// -*- 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 packages infrastructures are suffixed with +-package+, the documents
> +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 $(widcard $(pkgdir)/*))
> +08: $(eval $(call asciidoc-document))
> +----
> +
> +On line 7, the Makefile declares what the sources of the document are.
> +Currently, it is expected that the document's sources are only local;
> +Buildroot will not attempt to download anything to render a document.
> +Thus, you must indicate where the sources are. Usually, the string
> +above is sufficient for a document with no sub-directory structure.
> +
> +Finally, on line 8, we call the +asciidoc-document+ function, which
> +generates all the Makefile code necessary to render the document.
> +
> +==== +asciidoc-document+ reference
> +
> +The list of variables that can be set in a +.mk+ file to give metadata
> +information is (assuming the document name is +foo+) :
> +
> +* +FOO_SOURCES+, mandatory, defines the source files for the document.
> +
> +* +FOO_RESSOURCES+, optional, may contain a space-separated list of paths

s/_RESSOURCES/_RESOURCES/
(here, and for all occurences below)

> +  to so-called ressources (CSS, images...) By default, none.

s/ressources/resources/

> +
> +There are also additional hooks (see xref:hooks[] for what a hook is),
> +that a document may set to define extra actions to be done at various
> +steps:
> +
> +* +FOO_POST_EXTRACT_HOOKS+ to run additional commands after the sources
> +  have been copied by Buildroot. This can be used for, for example,
> +  generating part of the manual with information extracted from the
> +  tree. As an example, Buildroot uses that to generate the tables in the
> +  appendices.
> +
> +* +FOO_EXTRA_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_EXTRA_CHECK_DEPENDENCIES_<FMT>_HOOKS+, to run additional tests for
> +  the specified format +<FMT>+ (see the list of rendered formats, above.)
> +
> +Here is a complete example that uses all variables and all hooks:
> +
> +----
> +01: ################################################################################
> +02: #
> +03: # foo-document
> +04: #
> +05: ################################################################################
> +06:
> +07: FOO_SOURCES = $(sort $(widcard $(pkgdir)/*))
> +08: FOO_RESSOURCES = $(sort $(wildcard $(pkgdir)/ressources))
> +09:
> +10: define FOO_GEN_EXTRA_DOC
> +11:     /path/to/generate-script --outdir=$(@D)
> +12: endef
> +13: FOO_POST_EXTRACT_HOOK += 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_EXTRA_CHECK_DEPENDENCIES += 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_EXTRA_CHECK_DEPENDENCIES_TEXT += FOO_CHECK_MY_OTHER_PROG

s/FOO_EXTRA_CHECK_DEPENDENCIES_TEXT/FOO_EXTRA_CHECK_DEPENDENCIES_PDF/

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

Regards,

-- 
Samuel

[Buildroot] [PATCH 07/23 v5] docs/manual: simplify generation dependencies

[Yann E. MORIN]

Thomas, All,

On 2014-09-19 22:18 +0200, Thomas De Schampheleire spake thusly:
> On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> > 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>
> 
> Just a side note: I've been wondering if we should change the
> extension of the manual source files from .txt to .asciidoc. This
> seems to be the default extension and will make sure that vim selects
> the right syntax highlighting by default. I guess other editors would
> do the same (not tested).
> What do you think of that? Or is it unnecessary?
> On Debian, vim does not parse the modeline by default for security
> reasons, so the first two lines in each of these .txt files do not
> help there.

Well, my vim surely does. OK, it's Ubuntu, not Debian. Still...
I tried with an empty ~/.vim: I still get asciidoc syntax highlighting.

.asciidoc is overkill, I think. I'm not against, but may we wait for
after the series is applied? Trying not to get too much on my plate...
Hehe! ;-)

> Best regards,
> Thomas

-- 
.-----------------.--------------------.------------------.--------------------.
|  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 12/23 v5] docs/manual: last pass at removing hard-coded path in GENDOC_INNER

[Yann E. MORIN]

Thomas, All,

On 2014-09-22 21:38 +0200, Thomas De Schampheleire spake thusly:
> On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> > GENDOC_INNER still has one hard-coded path to the document's directory:
> > the asciidoc .conf files.
> 
> In this patch you assume that the asciidoc configuration is
> document-specific,

Well, not really. The code already had:
    MANUAL_$(2)_ASCIIDOC_CONF = docs/$(1)/asciidoc-$(2).conf

so the location where the asciidoc-FORMAT.conf was already supposed to
be specific to one document.

This patch merely removes the assumption that the document is in a
sub-directory of docs:
    docs/$(1)/  -->  $(3)/   ($(3) is the directory of the document)

> but at least the current contents of
> asciidoc-text.conf are global IMO: they simply make sure that
> hyperlinks are represented in a sane way, and that images are not
> shown (text document only). These are settings that apply to all
> documents.

I agree. But then, where should we move it?

  - keep it in docs/manual/ ? That would imply it is specific to our
    manual.

  - move it in docs/ ? But docs/ contains our website.

  - keep docs/manual, move the website to docs/website/ ? This way we
    could move the asciidoc*.conf into docs/ and is IMHO much cleaner
    than we have today.

> It can be useful to provide a mechanism for other documents to pass
> additional configuration files, but at this moment it is not strictly
> needed. I don't know if it makes sense to already provide a variable
> for that, or rather wait for a real use case to add it (KISS
> principle).

I already need that, and already implemented it, because I need this
asciidoc configuration:

    [specialwords]
    emphasizedwords=WORD1 WORD2

> Awaiting the outcome of this consideration, I did not yet review the
> patch in detail.

OK, here's what I suggest:

  - add a new variable for documents to pass an asccidoc.conf (done);
  - add a new variable for documents to pass a format-specific
    asciidoc-FMT.conf;
  - keep the current asciidoc-text.conf where it is, and always use it.

Then, if we decide to move the website, I can come up with more patches
to do so, and move the global asciidoc*.conf files into docs/

Is that OK with you guys? Peter, that would have an impact on the server
to generate the nightly manual, so we need your input here.

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  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 18/23 v5] docs: separate the GENDOC infra from our manual definition

[Yann E. MORIN]

Samuel, All,

On 2014-09-22 22:42 +0200, Samuel Martin spake thusly:
> On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> > 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.
[--SNIP--]
> > +MANUAL_XSLTPROC_IS_BROKEN = \
> 
> Maybe  this variable could be renamed as well.
> It is more related to asciidoc/a2x than specific tou Buildroot's manual.

Right, I'll rename it too, but not in that patch. I'll rename in the
patch titled:
    docs/manual: do not hardcode name of the generated document

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  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 12/23 v5] docs/manual: last pass at removing hard-coded path in GENDOC_INNER

[Thomas De Schampheleire]

Hi Yann,

On Tue, Sep 23, 2014 at 7:21 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Thomas, All,
>
> On 2014-09-22 21:38 +0200, Thomas De Schampheleire spake thusly:
>> On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
>> > GENDOC_INNER still has one hard-coded path to the document's directory:
>> > the asciidoc .conf files.
>>
>> In this patch you assume that the asciidoc configuration is
>> document-specific,
>
> Well, not really. The code already had:
>     MANUAL_$(2)_ASCIIDOC_CONF = docs/$(1)/asciidoc-$(2).conf
>
> so the location where the asciidoc-FORMAT.conf was already supposed to
> be specific to one document.
>
> This patch merely removes the assumption that the document is in a
> sub-directory of docs:
>     docs/$(1)/  -->  $(3)/   ($(3) is the directory of the document)
>
>> but at least the current contents of
>> asciidoc-text.conf are global IMO: they simply make sure that
>> hyperlinks are represented in a sane way, and that images are not
>> shown (text document only). These are settings that apply to all
>> documents.
>
> I agree. But then, where should we move it?
>
>   - keep it in docs/manual/ ? That would imply it is specific to our
>     manual.
>
>   - move it in docs/ ? But docs/ contains our website.
>
>   - keep docs/manual, move the website to docs/website/ ? This way we
>     could move the asciidoc*.conf into docs/ and is IMHO much cleaner
>     than we have today.

I think this proposal is better than the first two. The layout would be

docs/
     asciidoc setting files
     website/
     manual/

It could be seen as odd to have these asciidoc settings at top-level,
next to website that is totally unrelated.
An alternative would be something like (forget about the names):
docs/
     docs/
          asciidoc setting files
          manual/
     website/

but that seems very odd.
And moving 'website' to top-level buildroot is not very nice either.

So I tend to go for

docs/
     asciidoc setting files
     website/
     manual/


>
>> It can be useful to provide a mechanism for other documents to pass
>> additional configuration files, but at this moment it is not strictly
>> needed. I don't know if it makes sense to already provide a variable
>> for that, or rather wait for a real use case to add it (KISS
>> principle).
>
> I already need that, and already implemented it, because I need this
> asciidoc configuration:
>
>     [specialwords]
>     emphasizedwords=WORD1 WORD2

Ok.

>
>> Awaiting the outcome of this consideration, I did not yet review the
>> patch in detail.
>
> OK, here's what I suggest:
>
>   - add a new variable for documents to pass an asccidoc.conf (done);
>   - add a new variable for documents to pass a format-specific
>     asciidoc-FMT.conf;
>   - keep the current asciidoc-text.conf where it is, and always use it.

and also always use a common asciidoc.conf, if it exists, right?

>
> Then, if we decide to move the website, I can come up with more patches
> to do so, and move the global asciidoc*.conf files into docs/
>
> Is that OK with you guys? Peter, that would have an impact on the server
> to generate the nightly manual, so we need your input here.

Yes, if there is agreement on this then I would like to have this
changed together / close after merging this gendoc series.

Best regards,
Thomas

[Buildroot] [PATCH 12/23 v5] docs/manual: last pass at removing hard-coded path in GENDOC_INNER

[Samuel Martin]

Hi Yann, Thomas, all

On Wed, Sep 24, 2014 at 8:54 AM, Thomas De Schampheleire
<patrickdepinguin@gmail.com> wrote:
> Hi Yann,
>
> On Tue, Sep 23, 2014 at 7:21 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
>> Thomas, All,
>>
>> On 2014-09-22 21:38 +0200, Thomas De Schampheleire spake thusly:
>>> On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
>>> > GENDOC_INNER still has one hard-coded path to the document's directory:
>>> > the asciidoc .conf files.
>>>
>>> In this patch you assume that the asciidoc configuration is
>>> document-specific,
>>
>> Well, not really. The code already had:
>>     MANUAL_$(2)_ASCIIDOC_CONF = docs/$(1)/asciidoc-$(2).conf
>>
>> so the location where the asciidoc-FORMAT.conf was already supposed to
>> be specific to one document.
>>
>> This patch merely removes the assumption that the document is in a
>> sub-directory of docs:
>>     docs/$(1)/  -->  $(3)/   ($(3) is the directory of the document)
>>
>>> but at least the current contents of
>>> asciidoc-text.conf are global IMO: they simply make sure that
>>> hyperlinks are represented in a sane way, and that images are not
>>> shown (text document only). These are settings that apply to all
>>> documents.
>>
>> I agree. But then, where should we move it?
>>
>>   - keep it in docs/manual/ ? That would imply it is specific to our
>>     manual.
>>
>>   - move it in docs/ ? But docs/ contains our website.
>>
>>   - keep docs/manual, move the website to docs/website/ ? This way we
>>     could move the asciidoc*.conf into docs/ and is IMHO much cleaner
>>     than we have today.
>
> I think this proposal is better than the first two. The layout would be
>
> docs/
>      asciidoc setting files
>      website/
>      manual/
>
> It could be seen as odd to have these asciidoc settings at top-level,
> next to website that is totally unrelated.
> An alternative would be something like (forget about the names):
> docs/
>      docs/
>           asciidoc setting files
>           manual/
>      website/
>

I prefer the first layout over the second one.

Regards,

-- 
Samuel

[Buildroot] [PATCH 14/23 v5] docs/manual: rename the generic dependency rules

[Thomas De Schampheleire]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> 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>
> ---

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

[Buildroot] [PATCH 15/23 v5] docs/manual: allow documents to define some hooks, as for a package

[Thomas De Schampheleire]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Allow documents to define two hooks:
>   - DOC_EXTRA_CHECK_DEPENDENCIES
>     to check for extra dependencies required by this document
>   - DOC_EXTRA_CHECK_DEPENDENCIES_FMT
>     ditto, but for the specific format

Is this EXTRA_ string necessary?

>   - DOC_POST_EXTRACT_HOOKS:
>     to run additional actions to fill-in the build directory

I assume you called this POST_EXTRACT to line up with the package
infras, but for gendoc no extraction is done.
In fact, an rsync of DOC_SOURCES is done. Doesn't it make more sense
to use DOC_POST_RSYNC_HOOKS ?
Such a hook also exists in pkg-generic, so it also lines up with the
existing infras.


>
> (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>
>
> ---
> Changes v1 -> v2:
>   - call post-extract hook in rsync rule
> ---
>  docs/manual/manual.mk | 9 +++++++--
>  1 file changed, 7 insertions(+), 2 deletions(-)
>
> diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
> index cd944fa..52fac0e 100644
> --- a/docs/manual/manual.mk
> +++ b/docs/manual/manual.mk
> @@ -55,10 +55,9 @@ $(1): $(1)-$(5)
>  .PHONY: $(1)-$(5)
>  $(1)-$(5): $$(O)/docs/$(1)/$(1).$(6)
>
> -$(1)-check-dependencies: gendoc-check-dependencies
> -
>  gendoc-check-dependencies-$(5):
>  $(1)-check-dependencies-$(5): gendoc-check-dependencies-$(5)
> +       $$(Q)$$(foreach hook,$$($(2)_CHECK_EXTRA_DEPENDENCIES_$(5)_HOOKS),$$(call $$(hook))$$(sep))

Here you didn't add the '# Single line' comment. Is that intentional?

>
>  $(2)_$(4)_ASCIIDOC_CONF = $(3)/asciidoc-$(4).conf
>  ifneq ($$(wildcard $$($(2)_$(4)_ASCIIDOC_CONF)),)
> @@ -110,12 +109,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_EXTRA_DEPENDENCIES_HOOKS),$$(call $$(hook))$$(sep))
> +
>  $$(BUILD_DIR)/$(pkgname):
>         $$(Q)mkdir -p $$@
>
> +# Single line, because splitting a foreach is not easy...
>  $(pkgname)-rsync: $$(BUILD_DIR)/$(pkgname)
>         $$(Q)$$(call MESSAGE,"Preparing the $(pkgname) sources...")
>         $$(Q)rsync -a $(pkgdir) $$^
> +       $$(Q)$$(foreach hook,$$($$(call UPPERCASE,$(pkgname))_POST_EXTRACT_HOOKS),$$(call $$(hook))$$(sep))
>
>  $(pkgname)-prepare-sources: $(pkgname)-rsync
>


Best regards,
Thomas

[Buildroot] [PATCH 16/23 v5] docs/manual: use the new hooks instead of gendoc rules

[Thomas De Schampheleire]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Also reorder a bit the definition of the variables, to more ressemble

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>

This patch looks fine to me, aside from the comments I gave in earlier patches:
- s/ressources/resources
- suggestion to use POST_RSYNC iso POST_EXTRACT
- suggestion to remove EXTRA_

Best regards,
Thomas

[Buildroot] [PATCH 17/23 v5] docs/manual: always look for ressources in destination directory

[Thomas De Schampheleire]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Our manual does not use external filters in asciidoc, so we are happy
> with just looking for ressources 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 ressources 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>
>
> ---
> 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 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
> index f3638a7..e649ffe 100644
> --- a/docs/manual/manual.mk
> +++ b/docs/manual/manual.mk
> @@ -92,7 +92,7 @@ $$(O)/docs/$(1)/$(1).$(6): $$($$(call UPPERCASE,$(1))_SOURCES) \
>         $$(Q)$$(call MESSAGE,"Generating $(7) $(1)...")
>         $$(Q)mkdir -p $$(@D)
>         $$(Q)a2x $(8) -f $(4) -d book -L \
> -               $$(foreach r,$$($(2)_RESSOURCES),-r $$(r)) \
> +               $$(foreach r,$$($(2)_RESSOURCES),-r $$(r)) -r $$(@D) \

Alternatively, you could have expanded FOO_RESOURCES from , right?
Something like

$(2)_RESOURCES += $$(@D)

and then keeping the foreach line untouched ?
I'd add a short comment line to explain why this is done though...

Best regards,
Thomas

[Buildroot] [PATCH 18/23 v5] docs: separate the GENDOC infra from our manual definition

[Thomas De Schampheleire]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> 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.

Based on the input on the move of the website, it could go directly in
docs/ anyway.

Other than that:

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

[Buildroot] [PATCH 19/23 v5] docs: rename the GENDOC infrastructure

[Thomas De Schampheleire]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> 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>
> ---
>  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} (80%)
>
> diff --git a/Makefile b/Makefile
> index 28f2097..8f56f1f 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 85999c6..b221664 100644
> --- a/docs/manual/manual.mk
> +++ b/docs/manual/manual.mk
> @@ -24,4 +24,4 @@ define MANUAL_CHECK_LISTS_DEPS
>  endef
>  MANUAL_CHECK_EXTRA_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 80%
> rename from package/gendoc.mk
> rename to package/doc-asciidoc.mk
> index b859860..4366f8a 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 the manual"; \
> @@ -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 the pdf manual"; \
>                 exit 1; \
> @@ -32,8 +32,8 @@ 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.
> +# 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,13 +50,13 @@ MANUAL_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)
>
> -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_EXTRA_DEPENDENCIES_$(5)_HOOKS),$$(call $$(hook))$$(sep))
>
>  $(2)_$(4)_ASCIIDOC_CONF = $(3)/asciidoc-$(4).conf
> @@ -102,15 +102,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>_RESSOURCES 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_EXTRA_DEPENDENCIES_HOOKS),$$(call $$(hook))$$(sep))
>
>  $$(BUILD_DIR)/$(pkgname):
> @@ -124,24 +124,30 @@ $(pkgname)-rsync: $$(BUILD_DIR)/$(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)/$(pkgname)
>  .PHONY: $(pkgname) $(pkgname)-clean
>  endef
> +
> +################################################################################
> +# asciidoc-document -- the target generator macro for asiciidoc documents

                                                         ^ asciidoc

Best regards,
Thomas

[Buildroot] [PATCH 20/23 v5] docs/asciidoc: call $(pkgname) and $(pkgdir) in a single place

[Thomas De Schampheleire]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> 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>
> ---
>  package/doc-asciidoc.mk | 39 ++++++++++++++++++++++-----------------
>  1 file changed, 22 insertions(+), 17 deletions(-)
>
> diff --git a/package/doc-asciidoc.mk b/package/doc-asciidoc.mk
> index 4366f8a..38c9ced 100644
> --- a/package/doc-asciidoc.mk
> +++ b/package/doc-asciidoc.mk
> @@ -104,6 +104,11 @@ 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>_RESSOURCES defines where the document's
>  # resources, such as images, are located; must be an absolute path.
> @@ -111,43 +116,43 @@ endef
>  define ASCIIDOC
>  # Single line, because splitting a foreach is not easy...
>  $(pkgname)-check-dependencies: asciidoc-check-dependencies

Any reason why you did not change this occurrence of $(pkgname) ?

Other than that, I like the simplification brought by this patch!

Note that the order strikes me as odd. If you'd have made this change
somewhere in the beginning of the series, the rest of the patches
would have been simpler to read too. (no need to change this though,
just an observation).

Best regards,
Thomas

[Buildroot] [PATCH 21/23 v5] docs/asciidoc: make it possible to use $(@D) in hooks

[Thomas De Schampheleire]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> 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.

Shouldn't we add this note as a comment in doc/asciidoc.mk, to avoid
later 'correction' that adds a touch?

>
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> ---
>  docs/manual/manual.mk   |  2 +-
>  package/doc-asciidoc.mk | 10 ++++------
>  2 files changed, 5 insertions(+), 7 deletions(-)
>
> diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
> index b221664..9a86113 100644
> --- a/docs/manual/manual.mk
> +++ b/docs/manual/manual.mk
> @@ -8,7 +8,7 @@ MANUAL_RESSOURCES = $(TOPDIR)/docs/images
>  # Our manual needs to generate lists
>  define MANUAL_GEN_LISTS
>         $(Q)$(call MESSAGE,"Updating the manual lists...")
> -       $(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(BUILD_DIR)/$(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 38c9ced..13e4479 100644
> --- a/package/doc-asciidoc.mk
> +++ b/package/doc-asciidoc.mk
> @@ -118,16 +118,14 @@ define ASCIIDOC
>  $(pkgname)-check-dependencies: asciidoc-check-dependencies
>         $$(Q)$$(foreach hook,$$($(2)_CHECK_EXTRA_DEPENDENCIES_HOOKS),$$(call $$(hook))$$(sep))

This patch does not allow $(@D) in the CHECK_EXTRA_DEPENDENCIES_HOOKS.
Is that intentional?

[Buildroot] [PATCH 22/23 v5] Makefile: enable generating documents from br2-external

[Thomas De Schampheleire]

On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> 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: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

[Buildroot] [PATCH 23/23 v5] docs/manual: document the asciidoc infra

[Thomas De Schampheleire]

On Sun, Sep 14, 2014 at 1:07 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>
> ---
>  docs/manual/adding-packages-asciidoc.txt | 118 +++++++++++++++++++++++++++++++
>  docs/manual/adding-packages.txt          |   2 +
>  2 files changed, 120 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..b8821ee
> --- /dev/null
> +++ b/docs/manual/adding-packages-asciidoc.txt
> @@ -0,0 +1,118 @@
> +// -*- 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+

Any reason why this is capitalized and underscored like they were variables?
There is nowhere a variable FOO_SPLIT_HTML_BAR, is there?

In fact, as far as I can see, the variables that should use them use
them as follows:

FOO_EXTRA_CHECK_DEPENDENCIES_split-html_HOOKS

no?

And related to that: the above is not in line with the variable
$(2)_$(4)_ASCIIDOC_OPTS where $(4) is used instead of $(5).

The above two comments, if needed, are of course to be fixed in earlier patches.

> +
> +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 packages infrastructures are suffixed with +-package+, the documents
> +infrastructures are suffixed with +-document+. So, the AsciiDoc infrastructure

'packages infrastructures' and 'documents infrastructures' sound odd
to me. I would say
'package infrastructures' and 'document infrastructures'.

> +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 $(widcard $(pkgdir)/*))

wildcard

> +08: $(eval $(call asciidoc-document))
> +----
> +
> +On line 7, the Makefile declares what the sources of the document are.
> +Currently, it is expected that the document's sources are only local;
> +Buildroot will not attempt to download anything to render a document.
> +Thus, you must indicate where the sources are. Usually, the string
> +above is sufficient for a document with no sub-directory structure.
> +
> +Finally, on line 8, we call the +asciidoc-document+ function, which
> +generates all the Makefile code necessary to render the document.
> +
> +==== +asciidoc-document+ reference
> +
> +The list of variables that can be set in a +.mk+ file to give metadata
> +information is (assuming the document name is +foo+) :
> +
> +* +FOO_SOURCES+, mandatory, defines the source files for the document.
> +
> +* +FOO_RESSOURCES+, optional, may contain a space-separated list of paths
> +  to so-called ressources (CSS, images...) By default, none.

I would clarify here that they are 'resource directories' not the
actual images, etc. themselves.

> +
> +There are also additional hooks (see xref:hooks[] for what a hook is),

I'm not sure about 'for what a hook is'. Maybe:
... for general information on how to use hooks.
or
... for general information on hooks.
?

> +that a document may set to define extra actions to be done at various
> +steps:
> +
> +* +FOO_POST_EXTRACT_HOOKS+ to run additional commands after the sources
> +  have been copied by Buildroot. This can be used for, for example,
> +  generating part of the manual with information extracted from the
> +  tree. As an example, Buildroot uses that to generate the tables in the

s/that/this hook/

> +  appendices.
> +
> +* +FOO_EXTRA_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

My feeling says to loose the comma after 'that is' but I'm no native
English writer.

> +  render it appropriately (e.g. http://ditaa.sourceforge.net/[ditaa] or
> +  https://pythonhosted.org/aafigure/[aafigure].)
> +
> +* +FOO_EXTRA_CHECK_DEPENDENCIES_<FMT>_HOOKS+, to run additional tests for
> +  the specified format +<FMT>+ (see the list of rendered formats, above.)
> +
> +Here is a complete example that uses all variables and all hooks:
> +
> +----
> +01: ################################################################################
> +02: #
> +03: # foo-document
> +04: #
> +05: ################################################################################
> +06:
> +07: FOO_SOURCES = $(sort $(widcard $(pkgdir)/*))

wildcard

> +08: FOO_RESSOURCES = $(sort $(wildcard $(pkgdir)/ressources))
> +09:
> +10: define FOO_GEN_EXTRA_DOC
> +11:     /path/to/generate-script --outdir=$(@D)
> +12: endef
> +13: FOO_POST_EXTRACT_HOOK += 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_EXTRA_CHECK_DEPENDENCIES += 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_EXTRA_CHECK_DEPENDENCIES_TEXT += FOO_CHECK_MY_OTHER_PROG

Have you checked that this actually works, and that it should not be
text in lowercase?

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

Best regards,
Thomas

[Buildroot] [PATCH 23/23 v5] docs/manual: document the asciidoc infra

[Thomas De Schampheleire]

Thomas De Schampheleire <patrickdepinguin@gmail.com> schreef:
>On Sun, Sep 14, 2014 at 1:07 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>

By the way, for the renamed variables, you could also
 avoid the rebase hell by exporting the changes to
 patch files and manually editing those and reimporting them. As long as
 it's one line changes, that works fine...

[Buildroot] [PATCH 12/23 v5] docs/manual: last pass at removing hard-coded path in GENDOC_INNER

[Yann E. MORIN]

Patrick, Samuel, All,

On 2014-09-24 08:54 +0200, Thomas De Schampheleire spake thusly:
> On Tue, Sep 23, 2014 at 7:21 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
[--SNIP--]
> > I agree. But then, where should we move it?
> >
> >   - keep it in docs/manual/ ? That would imply it is specific to our
> >     manual.
> >
> >   - move it in docs/ ? But docs/ contains our website.
> >
> >   - keep docs/manual, move the website to docs/website/ ? This way we
> >     could move the asciidoc*.conf into docs/ and is IMHO much cleaner
> >     than we have today.
> 
> I think this proposal is better than the first two. The layout would be
> 
> docs/
>      asciidoc setting files
>      website/
>      manual/

As Peter (on IRC), Samuel, you and I all prefer this layout, I'm going
with that. In fact, I already have the patches moving the website ready
for submission. But I'll do in a separate series, so it is easier to
handle.

Thanks! :-)

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  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 15/23 v5] docs/manual: allow documents to define some hooks, as for a package

[Yann E. MORIN]

Thomas, All,

On 2014-09-24 21:11 +0200, Thomas De Schampheleire spake thusly:
> On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> > Allow documents to define two hooks:
> >   - DOC_EXTRA_CHECK_DEPENDENCIES
> >     to check for extra dependencies required by this document
> >   - DOC_EXTRA_CHECK_DEPENDENCIES_FMT
> >     ditto, but for the specific format
> 
> Is this EXTRA_ string necessary?

I pondered that for a while, too. I'm not too fan of it, but I'd still
like that the user knows we already do some dependency checking.

But I'll remove it; we should just document that we already do basic
dependency checking.

> >   - DOC_POST_EXTRACT_HOOKS:
> >     to run additional actions to fill-in the build directory
> 
> I assume you called this POST_EXTRACT to line up with the package
> infras,

Yup.

> but for gendoc no extraction is done.
> In fact, an rsync of DOC_SOURCES is done. Doesn't it make more sense
> to use DOC_POST_RSYNC_HOOKS ?
> Such a hook also exists in pkg-generic, so it also lines up with the
> existing infras.

Ditto, I was not sure either way. I'll rename to RSYNC.

[--SNIP--]
> >  gendoc-check-dependencies-$(5):
> >  $(1)-check-dependencies-$(5): gendoc-check-dependencies-$(5)
> > +       $$(Q)$$(foreach hook,$$($(2)_CHECK_EXTRA_DEPENDENCIES_$(5)_HOOKS),$$(call $$(hook))$$(sep))
> 
> Here you didn't add the '# Single line' comment. Is that intentional?

I just forgot! ;-)

Thanks! :-)

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  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 19/23 v5] docs: rename the GENDOC infrastructure

[Yann E. MORIN]

Thomas, All,

On 2014-09-24 21:31 +0200, Thomas De Schampheleire spake thusly:
> On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
[--SNIP--]
> > +################################################################################
> > +# asciidoc-document -- the target generator macro for asiciidoc documents
>                                                          ^ asciidoc

Yup, already fixed! ;-)

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  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 20/23 v5] docs/asciidoc: call $(pkgname) and $(pkgdir) in a single place

[Yann E. MORIN]

Thomas, All,

On 2014-09-24 21:44 +0200, Thomas De Schampheleire spake thusly:
> On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> > 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>
> > ---
> >  package/doc-asciidoc.mk | 39 ++++++++++++++++++++++-----------------
> >  1 file changed, 22 insertions(+), 17 deletions(-)
> >
> > diff --git a/package/doc-asciidoc.mk b/package/doc-asciidoc.mk
> > index 4366f8a..38c9ced 100644
> > --- a/package/doc-asciidoc.mk
> > +++ b/package/doc-asciidoc.mk
> > @@ -104,6 +104,11 @@ 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>_RESSOURCES defines where the document's
> >  # resources, such as images, are located; must be an absolute path.
> > @@ -111,43 +116,43 @@ endef
> >  define ASCIIDOC
> >  # Single line, because splitting a foreach is not easy...
> >  $(pkgname)-check-dependencies: asciidoc-check-dependencies
> 
> Any reason why you did not change this occurrence of $(pkgname) ?

Gee... Drools... Yes, I missed that one.

> Other than that, I like the simplification brought by this patch!

So do I, so do I! ;-)

> Note that the order strikes me as odd. If you'd have made this change
> somewhere in the beginning of the series, the rest of the patches
> would have been simpler to read too. (no need to change this though,
> just an observation).

Yes, I wanted to re-order the series so it was more logical, and bring
cleanups before actual changes.

However, as we discussed on IRC, this series is a real rebase-and-merge
nightmare...

I'll try to see what I can do, but I'm afraid I'll keep this series in
the current order. :-(

At one point, I even considered trashing it and redoing it all from
scratch, but that's just as insane. :-]

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  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/23 v5] docs/asciidoc: make it possible to use $(@D) in hooks

[Yann E. MORIN]

Thomas, All,

On 2014-09-24 21:50 +0200, Thomas De Schampheleire spake thusly:
> On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> > 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.
> 
> Shouldn't we add this note as a comment in doc/asciidoc.mk, to avoid
> later 'correction' that adds a touch?

Right, I'll do.

> > Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> > ---
> >  docs/manual/manual.mk   |  2 +-
> >  package/doc-asciidoc.mk | 10 ++++------
> >  2 files changed, 5 insertions(+), 7 deletions(-)
> >
> > diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
> > index b221664..9a86113 100644
> > --- a/docs/manual/manual.mk
> > +++ b/docs/manual/manual.mk
> > @@ -8,7 +8,7 @@ MANUAL_RESSOURCES = $(TOPDIR)/docs/images
> >  # Our manual needs to generate lists
> >  define MANUAL_GEN_LISTS
> >         $(Q)$(call MESSAGE,"Updating the manual lists...")
> > -       $(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(BUILD_DIR)/$(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 38c9ced..13e4479 100644
> > --- a/package/doc-asciidoc.mk
> > +++ b/package/doc-asciidoc.mk
> > @@ -118,16 +118,14 @@ define ASCIIDOC
> >  $(pkgname)-check-dependencies: asciidoc-check-dependencies
> >         $$(Q)$$(foreach hook,$$($(2)_CHECK_EXTRA_DEPENDENCIES_HOOKS),$$(call $$(hook))$$(sep))
> 
> This patch does not allow $(@D) in the CHECK_EXTRA_DEPENDENCIES_HOOKS.
> Is that intentional?

Partly.

I could not find a real use-case where a dependency would depend on the
content of the document.

Also, dependencies are checked even before the rsync takes place, so
$(@D) does not even exist yet.

So, I did not bother handing a valid $(@D) to CHECK_DEPS.

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  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 17/23 v5] docs/manual: always look for ressources in destination directory

[Yann E. MORIN]

Thomas, All,

On 2014-09-24 21:21 +0200, Thomas De Schampheleire spake thusly:
> On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> > Our manual does not use external filters in asciidoc, so we are happy
> > with just looking for ressources 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 ressources 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>
> >
> > ---
> > 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 | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> >
> > diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
> > index f3638a7..e649ffe 100644
> > --- a/docs/manual/manual.mk
> > +++ b/docs/manual/manual.mk
> > @@ -92,7 +92,7 @@ $$(O)/docs/$(1)/$(1).$(6): $$($$(call UPPERCASE,$(1))_SOURCES) \
> >         $$(Q)$$(call MESSAGE,"Generating $(7) $(1)...")
> >         $$(Q)mkdir -p $$(@D)
> >         $$(Q)a2x $(8) -f $(4) -d book -L \
> > -               $$(foreach r,$$($(2)_RESSOURCES),-r $$(r)) \
> > +               $$(foreach r,$$($(2)_RESSOURCES),-r $$(r)) -r $$(@D) \
> 
> Alternatively, you could have expanded FOO_RESOURCES from , right?
> Something like
> 
> $(2)_RESOURCES += $$(@D)
> 
> and then keeping the foreach line untouched ?

Well, no: we do not already have the uppercase name of the package, so
it would be quite ugly to write:

    $(call UPPERCASE,$(pkgname))_RESOURCES += $$(@D)

So, I find it cleaner to write as I did.

Eventually, I can switch that once ASCIIDOC gets passed the uppercase
name of the document in a parameter. But I'm not sure it is worthwhile.

> I'd add a short comment line to explain why this is done though...

You mean, a comment in the .mk to explain why we pass -r $$(@D) ?

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  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 23/23 v5] docs/manual: document the asciidoc infra

[Yann E. MORIN]

Thomas, All,

On 2014-09-24 22:07 +0200, Thomas De Schampheleire spake thusly:
> On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> > +* +HTML+
> > +* +SPLIT_HTML+
> > +* +PDF+
> > +* +EPUB+
> > +* +TEXT+
> 
> Any reason why this is capitalized and underscored like they were variables?
> There is nowhere a variable FOO_SPLIT_HTML_BAR, is there?

Yup, I'll set it to lowercase: they are the types of documents we
generate. That it needs to be in caps in variables is just a naming
convention.

> In fact, as far as I can see, the variables that should use them use
> them as follows:
> 
> FOO_EXTRA_CHECK_DEPENDENCIES_split-html_HOOKS
> 
> no?

Right. This is a bug. For _HOOKS variables in all package infras, we
exclusively use uppercase. So should we do here, too.

However, as you noticed, this is not correctly handled. I'll fix before
I repsin the series.

Thomas DS, also known as Lynx Eye! ;-)

> And related to that: the above is not in line with the variable
> $(2)_$(4)_ASCIIDOC_OPTS where $(4) is used instead of $(5).
> 
> The above two comments, if needed, are of course to be fixed in earlier patches.

Right.

> > +* +FOO_EXTRA_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
> 
> My feeling says to loose the comma after 'that is' but I'm no native
> English writer.

Neither am I. Still, I believe that's the way it is used. For example:
    https://en.wikipedia.org/wiki/Comma#Between_adjectives

Title is unrelated to the subject, but the sentence uses a comma after
"that is".

See also:
    http://www.thefreedictionary.com/that+is

Quoting from two places:
    To explain more clearly; in other words: on the first floor, that
    is, the floor at street level.

    When that introduces a relative clause, the clause is usu.
    restrictive, that is, essential to the complete meaning of the
    sentence.

Hmm... Sure thing, we learn a great deal of English on the Buildroot
mailing list. What was the last argument we had some time ago? hehe! :-)

> > +29: FOO_EXTRA_CHECK_DEPENDENCIES_TEXT += FOO_CHECK_MY_OTHER_PROG
> 
> Have you checked that this actually works, and that it should not be
> text in lowercase?

Well, it used to work at one time, but now it does not any more.
As I said above, we want variables to be all uppercase, so the manual is
acurate in what we want; it's just a problem with the implementation,
that is, it is buggy. :-]

/me hides... Muhahaha! :-)

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  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 23/23 v5] docs/manual: document the asciidoc infra

[Thomas De Schampheleire]

Hi Yann,

On Fri, Sep 26, 2014 at 12:21 AM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Thomas, All,
>
> On 2014-09-24 22:07 +0200, Thomas De Schampheleire spake thusly:
>> On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
>> > +* +HTML+
>> > +* +SPLIT_HTML+
>> > +* +PDF+
>> > +* +EPUB+
>> > +* +TEXT+
>>
>> Any reason why this is capitalized and underscored like they were variables?
>> There is nowhere a variable FOO_SPLIT_HTML_BAR, is there?
>
> Yup, I'll set it to lowercase: they are the types of documents we
> generate. That it needs to be in caps in variables is just a naming
> convention.
>
>> In fact, as far as I can see, the variables that should use them use
>> them as follows:
>>
>> FOO_EXTRA_CHECK_DEPENDENCIES_split-html_HOOKS
>>
>> no?
>
> Right. This is a bug. For _HOOKS variables in all package infras, we
> exclusively use uppercase. So should we do here, too.
>
> However, as you noticed, this is not correctly handled. I'll fix before
> I repsin the series.

Ok, that's indeed more in line with all the other infras.

>
> Thomas DS, also known as Lynx Eye! ;-)

hehe :)

>
>> And related to that: the above is not in line with the variable
>> $(2)_$(4)_ASCIIDOC_OPTS where $(4) is used instead of $(5).
>>
>> The above two comments, if needed, are of course to be fixed in earlier patches.
>
> Right.
>
>> > +* +FOO_EXTRA_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
>>
>> My feeling says to loose the comma after 'that is' but I'm no native
>> English writer.
>
> Neither am I. Still, I believe that's the way it is used. For example:
>     https://en.wikipedia.org/wiki/Comma#Between_adjectives
>
> Title is unrelated to the subject, but the sentence uses a comma after
> "that is".
>
> See also:
>     http://www.thefreedictionary.com/that+is
>
> Quoting from two places:
>     To explain more clearly; in other words: on the first floor, that
>     is, the floor at street level.
>
>     When that introduces a relative clause, the clause is usu.
>     restrictive, that is, essential to the complete meaning of the
>     sentence.
>

Ok, I agree, keep the comma.

> Hmm... Sure thing, we learn a great deal of English on the Buildroot
> mailing list. What was the last argument we had some time ago? hehe! :-)

:)


Best regards,
Thomas

[Buildroot] [PATCH 17/23 v5] docs/manual: always look for ressources in destination directory

[Thomas De Schampheleire]

On Thu, Sep 25, 2014 at 9:31 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Thomas, All,
>
> On 2014-09-24 21:21 +0200, Thomas De Schampheleire spake thusly:
>> On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
>> > Our manual does not use external filters in asciidoc, so we are happy
>> > with just looking for ressources 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 ressources 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>
>> >
>> > ---
>> > 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 | 2 +-
>> >  1 file changed, 1 insertion(+), 1 deletion(-)
>> >
>> > diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
>> > index f3638a7..e649ffe 100644
>> > --- a/docs/manual/manual.mk
>> > +++ b/docs/manual/manual.mk
>> > @@ -92,7 +92,7 @@ $$(O)/docs/$(1)/$(1).$(6): $$($$(call UPPERCASE,$(1))_SOURCES) \
>> >         $$(Q)$$(call MESSAGE,"Generating $(7) $(1)...")
>> >         $$(Q)mkdir -p $$(@D)
>> >         $$(Q)a2x $(8) -f $(4) -d book -L \
>> > -               $$(foreach r,$$($(2)_RESSOURCES),-r $$(r)) \
>> > +               $$(foreach r,$$($(2)_RESSOURCES),-r $$(r)) -r $$(@D) \
>>
>> Alternatively, you could have expanded FOO_RESOURCES from , right?
>> Something like
>>
>> $(2)_RESOURCES += $$(@D)
>>
>> and then keeping the foreach line untouched ?
>
> Well, no: we do not already have the uppercase name of the package, so
> it would be quite ugly to write:
>
>     $(call UPPERCASE,$(pkgname))_RESOURCES += $$(@D)
>
> So, I find it cleaner to write as I did.

OK

>
> Eventually, I can switch that once ASCIIDOC gets passed the uppercase
> name of the document in a parameter. But I'm not sure it is worthwhile.
>
>> I'd add a short comment line to explain why this is done though...
>
> You mean, a comment in the .mk to explain why we pass -r $$(@D) ?

Yes. The fact that this extra -r is needed is not obvious at all. In
fact, removing it would work fine for the manual. Only when you use
the filters as you explain in the commit message is it really
necessary.
A comment would therefore avoid someone accidentally removing it
because he/she thinks it's unneeded.

Best regards,
Thomas

[Buildroot] [PATCH 17/23 v5] docs/manual: always look for ressources in destination directory

[Yann E. MORIN]

Thomas, All,

On 2014-09-26 12:50 +0200, Thomas De Schampheleire spake thusly:
> On Thu, Sep 25, 2014 at 9:31 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
[--SNIP--]
> > You mean, a comment in the .mk to explain why we pass -r $$(@D) ?
> 
> Yes. The fact that this extra -r is needed is not obvious at all. In
> fact, removing it would work fine for the manual. Only when you use
> the filters as you explain in the commit message is it really
> necessary.
> A comment would therefore avoid someone accidentally removing it
> because he/she thinks it's unneeded.

OK. Thanks.

Regards,
Yann E. MORIN.

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