[Buildroot] [pull request v6] gendoc infra: make it useable for other documents

[Buildroot] [pull request v6] gendoc infra: make it useable for other documents

[Yann E. MORIN]

Hello All!

This series builds up on top of Samuel previous series, and further
enhances the GENDOC infrastructure to be useable to generate other
documents, and especially documents in br2-external.

The series is articulated as thus:

  - patches 1-3: from Samuel, virtually untouched by me, save for the
    location where the docs are built (patch 1), and the check for
    xsltproc (patch 3);

  - patches 4-13: properly separate our manual defintion from the actual
    infrastructure;

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

  - patch 16: workaround asciidoc deficiency when calling filters;

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

  - patches 19-20: further tweak the new infra so it looks more like
    other infras: only call pkgdir and pkgname from the frontend macro,
    and use stamp files so we can use $(@D);

  - patches 21-22: add new locations where to get the AsciiDoc config
    files;

  - patch 23: always use UTC when generating the manual;

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

  - patch 25: document this new infra in the manual.

Here is an example of using this new infra from a br2-external tree:

    http://ymorin.is-a-geek.org/download/tmp/br.config/
    http://ymorin.is-a-geek.org/download/tmp/br.config/brsh-manual.html


Changes v5 -> v6:
  - change build location  (Thomas P.)
  - xsltproc check is a warniong only  (Thomas DS.)
  - do not use unnecessary $$(call)s  (Thomas DS.)
  - rename hooks  (Thomas DS.)
  - comment tricky code sections  (Thomas DS.)
  - more s/manual/document/  (Thomas DS., Samuel)
  - typoes  (Thomas DS., Samuel)

Changes v4 -> v5:
  - cleanup the series
  - make it posible to use $(@D) in hooks
  - call post-extract hook in the same rule that does the rsync
  - rename the extra check dependencies hooks, to look more like real hooks
  - document the doc-asciidoc infra in the manual

Changes v3 -> v4:
  - only run the xsltproc check once, not for every types of outputs
  - add patches 5..18

Regards,
Yann E. MORIN.


The following changes since commit 6f5bffc426f7418c555291450d482a0ceede0865:

  qemu-ppc: update kernel to latest for g3beige emulation (2014-09-27 09:53:12 +0200)

are available in the git repository at:

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

for you to fetch changes up to b0043d14369f4ce8fe60762c8b48c85a72a55894:

  docs/manual: document the asciidoc infra (2014-09-27 12:15:17 +0200)

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

Yann E. MORIN (22):
      docs/manual: get rid of legacy comment in GENDOC
      docs/manual: copying the manual sources is a common action
      docs/manual: simplify generation dependencies
      docs/manual: manual-update-lists is not a generic GENDOC rule
      docs/manual: move manual-prepare-sources rule into GENDOC
      docs/manual: do not hardcode name of the generated document
      docs/manual: allow a document to declare where its resources are
      docs/manual: last pass at removing hard-coded path in GENDOC_INNER
      docs/manual: properly separate rules specific for our manual
      docs/manual: rename the generic dependency rules
      docs/manual: allow documents to define some hooks, as for a package
      docs/manual: use the new hooks instead of gendoc rules
      docs/manual: always look for resources in destination directory
      docs: separate the GENDOC infra from our manual definition
      docs: rename the GENDOC infrastructure
      docs/asciidoc: call $(pkgname) and $(pkgdir) in a single place
      docs/asciidoc: make it possible to use $(@D) in hooks
      doc/asciidoc: allow documents to pass a global asciidoc configuration
      doc/asciidoc: always apply Buildroot's AsciiDoc config
      doc/asciidoc: always use UTC
      Makefile: enable generating documents from br2-external
      docs/manual: document the asciidoc infra

 Makefile                                 |   2 +
 docs/{manual => conf}/asciidoc-text.conf |   0
 docs/manual/adding-packages-asciidoc.txt | 119 ++++++++++++++++++++
 docs/manual/adding-packages.txt          |   2 +
 docs/manual/manual.mk                    | 105 +++---------------
 package/doc-asciidoc.mk                  | 181 +++++++++++++++++++++++++++++++
 6 files changed, 320 insertions(+), 89 deletions(-)
 rename docs/{manual => conf}/asciidoc-text.conf (100%)
 create mode 100644 docs/manual/adding-packages-asciidoc.txt
 create mode 100644 package/doc-asciidoc.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 01/25 v6] 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>
[yann.morin.1998 at free.fr: moved into $(BUILD_DIR)/docs/manual as per
Thomas P. suggestion]
Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>

---
Changes v5 -> v6:
  - build in BUILD_DIR/docs/manual, to avoid name-clashing with a
    package (for when later documents are added)  (Thomas P.)
---
 docs/manual/manual.mk | 24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index 136f725..cdc4c73 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -1,11 +1,20 @@
+$(BUILD_DIR)/docs/$(pkgname):
+	$(Q)mkdir -p $@
+
+manual-rsync: $(BUILD_DIR)/docs/$(pkgname)
+	$(Q)$(call MESSAGE,"Preparing the manual sources...")
+	$(Q)rsync -a docs/$(pkgname)/ $(BUILD_DIR)/docs/$(pkgname)
+
 # Packages included in BR2_EXTERNAL are not part of buildroot, so they
 # should not be included in the manual.
-manual-update-lists: manual-check-dependencies-lists
+manual-update-lists: manual-check-dependencies-lists $(BUILD_DIR)/docs/$(pkgname)
 	$(Q)$(call MESSAGE,"Updating the manual lists...")
-	$(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(O)/docs/manual/.build \
+	$(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(BUILD_DIR)/docs/$(pkgname) \
 		BR2_EXTERNAL=$(TOPDIR)/support/dummy-external \
 		python -B $(TOPDIR)/support/scripts/gen-manual-lists.py
 
+manual-prepare-sources: manual-rsync manual-update-lists
+
 # we can't use suitable-host-package here because that's not available in
 # the context of 'make release'
 manual-check-dependencies:
@@ -65,14 +74,13 @@ $$(O)/docs/$(1)/$(1).$(4): docs/$(1)/$(1).txt \
 			   $$($$(call UPPERCASE,$(1))_SOURCES) \
 			   manual-check-dependencies \
 			   manual-check-dependencies-$(3) \
-			   manual-update-lists
+			   manual-prepare-sources
 	$$(Q)$$(call MESSAGE,"Generating $(5) $(1)...")
-	$$(Q)mkdir -p $$(@D)/.build
-	$$(Q)rsync -au docs/$(1)/*.txt $$(@D)/.build
+	$$(Q)mkdir -p $$(@D)
 	$$(Q)a2x $(6) -f $(2) -d book -L -r $$(TOPDIR)/docs/images \
 		--asciidoc-opts="$$(MANUAL_$(2)_ASCIIDOC_OPTS)" \
-		-D $$(@D) $$(@D)/.build/$(1).txt
-	-$$(Q)rm -rf $$(@D)/.build
+		-D $$(@D) \
+		$$(BUILD_DIR)/docs/$(1)/$(1).txt
 endef
 
 ################################################################################
@@ -94,7 +102,7 @@ $(call GENDOC_INNER,$(pkgname),text,text,text,text)
 $(call GENDOC_INNER,$(pkgname),epub,epub,epub,ePUB)
 clean: $(pkgname)-clean
 $(pkgname)-clean:
-	$$(Q)$$(RM) -rf $$(O)/docs/$(pkgname)
+	$$(Q)$$(RM) -rf $$(BUILD_DIR)/docs/$(pkgname)
 .PHONY: $(pkgname) $(pkgname)-clean manual-update-lists
 endef
 
-- 
1.9.1

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

[Yann E. MORIN]

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

Though the --destination-dir option works as expected, a2x displays the
following message when generating the pdf and text manual:

  a2x: WARNING: --destination-dir option is only applicable to HTML based outputs

To avoid this warning, we now just build the manual in its build location,
then move the generated files into $(O)/docs/manual.

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

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index cdc4c73..03e3a0b 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -70,6 +70,19 @@ ifneq ($$(wildcard $$(MANUAL_$(2)_ASCIIDOC_CONF)),)
 MANUAL_$(2)_ASCIIDOC_OPTS += -f $$(MANUAL_$(2)_ASCIIDOC_CONF)
 endif
 
+# Handle a2x warning about --destination-dir option only applicable to HTML
+# based outputs. So:
+# - use the --destination-dir option if possible (html and split-html),
+# - otherwise copy the generated manual to the output directory
+MANUAL_$(2)_A2X_OPTS =
+ifneq ($$(filter $(3),html split-html),)
+MANUAL_$(2)_A2X_OPTS += --destination-dir="$$(@D)"
+else
+define MANUAL_$(2)_INSTALL_CMDS
+	$$(Q)cp -f $$(BUILD_DIR)/docs/$(1)/$(1).$(4) $$(@D)
+endef
+endif
+
 $$(O)/docs/$(1)/$(1).$(4): docs/$(1)/$(1).txt \
 			   $$($$(call UPPERCASE,$(1))_SOURCES) \
 			   manual-check-dependencies \
@@ -78,9 +91,11 @@ $$(O)/docs/$(1)/$(1).$(4): docs/$(1)/$(1).txt \
 	$$(Q)$$(call MESSAGE,"Generating $(5) $(1)...")
 	$$(Q)mkdir -p $$(@D)
 	$$(Q)a2x $(6) -f $(2) -d book -L -r $$(TOPDIR)/docs/images \
+		$$(MANUAL_$(2)_A2X_OPTS) \
 		--asciidoc-opts="$$(MANUAL_$(2)_ASCIIDOC_OPTS)" \
-		-D $$(@D) \
 		$$(BUILD_DIR)/docs/$(1)/$(1).txt
+# install the generated manual
+	$$(MANUAL_$(2)_INSTALL_CMDS)
 endef
 
 ################################################################################
-- 
1.9.1

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

[Yann E. MORIN]

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

The PDF manual generation reaches the default xsltproc's template
recursion limit when processing the target package list; this makes the
PDF manual generation fail [1-3].

This limit can be raised with the '--maxvars' option. Unfortunately,
this option is not correctly handled in the latest xsltproc/libxslt
release (1.1.28), but this bug is already fixed in the libxslt
repository [4].

This patch disables the PDF manual generation (makes it warn with a
meaningful error message) when the xsltproc program found in the PATH
does not support the --maxvars option.
So, one can still generate the PDF manual if he/she extends PATH with
the location of a working xsltproc, by running:

  $ PATH=/path/to/custom-xsltproc/bin:${PATH} make manual-pdf

[1] http://lists.busybox.net/pipermail/buildroot/2014-August/104390.html
[2] http://lists.busybox.net/pipermail/buildroot/2014-August/104418.html
[3] http://lists.busybox.net/pipermail/buildroot/2014-August/104421.html
[4] https://gitorious.org/libxslt/libxslt/commit/5af7ad745323004984287e48b42712e7305de35c

Reported-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
Cc: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
[yann.morin.1998 at free.fr: move the assignment block out of GENDOC_INNER, no
 need to retest for each type of each document: it's always the same answer;
 make it a warning as per Thomas DS. suggestion]
Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>

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

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index 03e3a0b..e9078f1 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -41,6 +41,20 @@ manual-check-dependencies-lists:
 		exit 1; \
 	fi
 
+# PDF manual generation is broken because of a bug in xsltproc program provided
+# by libxslt <=1.1.28, which does not honor an option we need to set.
+# Fortunately, this bug is already fixed upstream:
+#   https://gitorious.org/libxslt/libxslt/commit/5af7ad745323004984287e48b42712e7305de35c
+#
+# So, bail out when trying to build the pdf manual using a buggy version of the
+# xsltproc program.
+#
+# So, to overcome this issue and being able to build the pdf manual, you can
+# build xsltproc from it source repository, then run:
+#   $ PATH=/path/to/custom-xsltproc/bin:${PATH} make manual
+MANUAL_XSLTPROC_IS_BROKEN = \
+	$(shell xsltproc --maxvars 0 >/dev/null 2>/dev/null || echo y)
+
 ################################################################################
 # GENDOC_INNER -- generates the make targets needed to build a specific type of
 #                 asciidoc documentation.
@@ -83,6 +97,14 @@ define MANUAL_$(2)_INSTALL_CMDS
 endef
 endif
 
+ifeq ($(4)-$$(MANUAL_XSLTPROC_IS_BROKEN),pdf-y)
+$$(O)/docs/$(1)/$(1).$(4):
+	$$(warning PDF manual generation is disabled because of a bug in \
+		xsltproc. To be able to generate the PDF manual, you should \
+		build xsltproc from the libxslt sources >=1.1.29 and pass it \
+		to make through the command line: \
+		'PATH=/path/to/custom-xsltproc/bin:$$$${PATH} make manual-pdf')
+else
 $$(O)/docs/$(1)/$(1).$(4): docs/$(1)/$(1).txt \
 			   $$($$(call UPPERCASE,$(1))_SOURCES) \
 			   manual-check-dependencies \
@@ -96,6 +118,7 @@ $$(O)/docs/$(1)/$(1).$(4): docs/$(1)/$(1).txt \
 		$$(BUILD_DIR)/docs/$(1)/$(1).txt
 # install the generated manual
 	$$(MANUAL_$(2)_INSTALL_CMDS)
+endif
 endef
 
 ################################################################################
@@ -111,8 +134,11 @@ $(call GENDOC_INNER,$(pkgname),xhtml,html,html,HTML,\
 	--xsltproc-opts "--stringparam toc.section.depth 1")
 $(call GENDOC_INNER,$(pkgname),chunked,split-html,chunked,split HTML,\
 	--xsltproc-opts "--stringparam toc.section.depth 1")
+# dblatex needs to pass the '--maxvars ...' option to xsltproc to prevent it
+# from reaching the template recursion limit when processing the (long) target
+# package table and bailing out.
 $(call GENDOC_INNER,$(pkgname),pdf,pdf,pdf,PDF,\
-	--dblatex-opts "-P latex.output.revhistory=0")
+	--dblatex-opts "-P latex.output.revhistory=0 -x '--maxvars 100000'")
 $(call GENDOC_INNER,$(pkgname),text,text,text,text)
 $(call GENDOC_INNER,$(pkgname),epub,epub,epub,ePUB)
 clean: $(pkgname)-clean
-- 
1.9.1

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

[Yann E. MORIN]

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

Remove the stray comment.

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

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index e9078f1..69113e3 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -124,9 +124,6 @@ endef
 ################################################################################
 # GENDOC -- generates the make targets needed to build asciidoc documentation.
 #
-#  argument 1 is the name of the document and must be a subdirectory of docs/;
-#             the top-level asciidoc file must have the same name
-#
 # The variable <DOCUMENT_NAME>_SOURCES defines the dependencies.
 ################################################################################
 define GENDOC
-- 
1.9.1

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

[Yann E. MORIN]

Move the creation of $(BUILD_DIR)/manual and the rsyncing of the
sources into GENDOC.

This is is needed so that GENDOC can be easily used to generate another
document, without requiring that document to duplicate the copying rules.

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

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index 69113e3..dd6f0ea 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -1,10 +1,3 @@
-$(BUILD_DIR)/docs/$(pkgname):
-	$(Q)mkdir -p $@
-
-manual-rsync: $(BUILD_DIR)/docs/$(pkgname)
-	$(Q)$(call MESSAGE,"Preparing the manual sources...")
-	$(Q)rsync -a docs/$(pkgname)/ $(BUILD_DIR)/docs/$(pkgname)
-
 # Packages included in BR2_EXTERNAL are not part of buildroot, so they
 # should not be included in the manual.
 manual-update-lists: manual-check-dependencies-lists $(BUILD_DIR)/docs/$(pkgname)
@@ -127,6 +120,13 @@ endef
 # The variable <DOCUMENT_NAME>_SOURCES defines the dependencies.
 ################################################################################
 define GENDOC
+$$(BUILD_DIR)/docs/$(pkgname):
+	$$(Q)mkdir -p $$@
+
+$(pkgname)-rsync: $$(BUILD_DIR)/docs/$(pkgname)
+	$$(Q)$$(call MESSAGE,"Preparing the $(pkgname) sources...")
+	$$(Q)rsync -a docs/$(pkgname)/ $$^
+
 $(call GENDOC_INNER,$(pkgname),xhtml,html,html,HTML,\
 	--xsltproc-opts "--stringparam toc.section.depth 1")
 $(call GENDOC_INNER,$(pkgname),chunked,split-html,chunked,split HTML,\
-- 
1.9.1

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

[Yann E. MORIN]

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

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

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index dd6f0ea..56dff56 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -98,8 +98,7 @@ $$(O)/docs/$(1)/$(1).$(4):
 		to make through the command line: \
 		'PATH=/path/to/custom-xsltproc/bin:$$$${PATH} make manual-pdf')
 else
-$$(O)/docs/$(1)/$(1).$(4): docs/$(1)/$(1).txt \
-			   $$($$(call UPPERCASE,$(1))_SOURCES) \
+$$(O)/docs/$(1)/$(1).$(4): $$($$(call UPPERCASE,$(1))_SOURCES) \
 			   manual-check-dependencies \
 			   manual-check-dependencies-$(3) \
 			   manual-prepare-sources
-- 
1.9.1

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

[Yann E. MORIN]

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

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

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index 56dff56..3b79716 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -1,5 +1,6 @@
 # Packages included in BR2_EXTERNAL are not part of buildroot, so they
 # should not be included in the manual.
+.PHONY: manual-update-lists
 manual-update-lists: manual-check-dependencies-lists $(BUILD_DIR)/docs/$(pkgname)
 	$(Q)$(call MESSAGE,"Updating the manual lists...")
 	$(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(BUILD_DIR)/docs/$(pkgname) \
@@ -140,7 +141,7 @@ $(call GENDOC_INNER,$(pkgname),epub,epub,epub,ePUB)
 clean: $(pkgname)-clean
 $(pkgname)-clean:
 	$$(Q)$$(RM) -rf $$(BUILD_DIR)/docs/$(pkgname)
-.PHONY: $(pkgname) $(pkgname)-clean manual-update-lists
+.PHONY: $(pkgname) $(pkgname)-clean
 endef
 
 MANUAL_SOURCES = $(sort $(wildcard docs/manual/*.txt) $(wildcard docs/images/*))
-- 
1.9.1

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

[Yann E. MORIN]

Copying the document's source files is a generic GENDOC action, that
will be common to all documents, so the dependency rule should be
handled in GENDOC, rather than letting all documents duplicate it.

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

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index 3b79716..c40f371 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -7,7 +7,7 @@ manual-update-lists: manual-check-dependencies-lists $(BUILD_DIR)/docs/$(pkgname
 		BR2_EXTERNAL=$(TOPDIR)/support/dummy-external \
 		python -B $(TOPDIR)/support/scripts/gen-manual-lists.py
 
-manual-prepare-sources: manual-rsync manual-update-lists
+manual-prepare-sources: manual-update-lists
 
 # we can't use suitable-host-package here because that's not available in
 # the context of 'make release'
@@ -127,6 +127,8 @@ $(pkgname)-rsync: $$(BUILD_DIR)/docs/$(pkgname)
 	$$(Q)$$(call MESSAGE,"Preparing the $(pkgname) sources...")
 	$$(Q)rsync -a docs/$(pkgname)/ $$^
 
+$(pkgname)-prepare-sources: $(pkgname)-rsync
+
 $(call GENDOC_INNER,$(pkgname),xhtml,html,html,HTML,\
 	--xsltproc-opts "--stringparam toc.section.depth 1")
 $(call GENDOC_INNER,$(pkgname),chunked,split-html,chunked,split HTML,\
-- 
1.9.1

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

[Yann E. MORIN]

Currently, GENDOC_INNER hard-codes some variables to have the name of the
document in them:
    MANUAL_$(2)_ASCIIDOC_CONF
    MANUAL_$(2)_ASCIIDOC_OPTS
    MANUAL_$(2)_A2X_OPTS
    MANUAL_$(2)_INSTALL_CMDS
    ...

Also, it defines some dependency on the generation rule, onto:
    manual-check-dependencies
    manual-check-dependencies-$(3)
    manual-prepare-sources

This is problematic, as it is not possible to have another document
generated with the GENDOC infra, or it would trigger the rules, and use
the variables for our own document, 'manual'.

Add a new argument to GENDOC_INNER to be the uppercase name of the
document, much like it is done for the PKG_*_INNER functions. Replace
any reference to 'manual' with the currently passed named of the current
document, $(1).

The remaining references to 'manual' are on purpose, as they really
pertain to our manual.

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

---
Changes v5 -> v6:
  - do not use $$ when calling UPPERCASE  (Thomas DS)
  - also rename the variable with the xsltproc check  (Samuel)
  - s/manual/document/g in the comments, too  (Thomas DS)
  - typo in commit log  (Samuel)
---
 docs/manual/manual.mk | 93 ++++++++++++++++++++++++++-------------------------
 1 file changed, 47 insertions(+), 46 deletions(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index c40f371..b0ae2da 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -14,17 +14,17 @@ manual-prepare-sources: manual-update-lists
 manual-check-dependencies:
 	$(Q)if [ -z "$(shell support/dependencies/check-host-asciidoc.sh)" ]; then \
 		echo "You need a sufficiently recent asciidoc on your host" \
-			"to generate the manual"; \
+			"to generate a document"; \
 		exit 1; \
 	fi
 	$(Q)if [ -z "`which w3m 2>/dev/null`" ]; then \
-		echo "You need w3m on your host to generate the manual"; \
+		echo "You need w3m on your host to generate a document"; \
 		exit 1; \
 	fi
 
 manual-check-dependencies-pdf:
 	$(Q)if [ -z "`which dblatex 2>/dev/null`" ]; then \
-		echo "You need dblatex on your host to generate the pdf manual"; \
+		echo "You need dblatex on your host to generate a PDF document"; \
 		exit 1; \
 	fi
 
@@ -35,18 +35,18 @@ manual-check-dependencies-lists:
 		exit 1; \
 	fi
 
-# PDF manual generation is broken because of a bug in xsltproc program provided
+# PDF generation is broken because of a bug in xsltproc program provided
 # by libxslt <=1.1.28, which does not honor an option we need to set.
 # Fortunately, this bug is already fixed upstream:
 #   https://gitorious.org/libxslt/libxslt/commit/5af7ad745323004984287e48b42712e7305de35c
 #
-# So, bail out when trying to build the pdf manual using a buggy version of the
+# So, bail out when trying to build a PDF using a buggy version of the
 # xsltproc program.
 #
-# So, to overcome this issue and being able to build the pdf manual, you can
-# build xsltproc from it source repository, then run:
+# So, to overcome this issue and being able to build a PDF, you can
+# build xsltproc from its source repository, then run:
 #   $ PATH=/path/to/custom-xsltproc/bin:${PATH} make manual
-MANUAL_XSLTPROC_IS_BROKEN = \
+GENDOC_XSLTPROC_IS_BROKEN = \
 	$(shell xsltproc --maxvars 0 >/dev/null 2>/dev/null || echo y)
 
 ################################################################################
@@ -55,11 +55,12 @@ MANUAL_XSLTPROC_IS_BROKEN = \
 #
 #  argument 1 is the name of the document and must be a subdirectory of docs/;
 #             the top-level asciidoc file must have the same name
-#  argument 2 is the type of document to generate (-f argument of a2x)
-#  argument 3 is the document type as used in the make target
-#  argument 4 is the output file extension for the document type
-#  argument 5 is the human text for the document type
-#  argument 6 (optional) are extra arguments for a2x
+#  argument 2 is the uppercase name of the document
+#  argument 3 is the type of document to generate (-f argument of a2x)
+#  argument 4 is the document type as used in the make target
+#  argument 5 is the output file extension for the document type
+#  argument 6 is the human text for the document type
+#  argument 7 (optional) are extra arguments for a2x
 #
 # The variable <DOCUMENT_NAME>_SOURCES defines the dependencies.
 #
@@ -67,50 +68,50 @@ MANUAL_XSLTPROC_IS_BROKEN = \
 # all variable references except the arguments must be $$-quoted.
 ################################################################################
 define GENDOC_INNER
-$(1): $(1)-$(3)
-.PHONY: $(1)-$(3)
-$(1)-$(3): $$(O)/docs/$(1)/$(1).$(4)
+$(1): $(1)-$(4)
+.PHONY: $(1)-$(4)
+$(1)-$(4): $$(O)/docs/$(1)/$(1).$(5)
 
-manual-check-dependencies-$(3):
+$(1)-check-dependencies-$(4):
 
-MANUAL_$(2)_ASCIIDOC_CONF = docs/$(1)/asciidoc-$(2).conf
-ifneq ($$(wildcard $$(MANUAL_$(2)_ASCIIDOC_CONF)),)
-MANUAL_$(2)_ASCIIDOC_OPTS += -f $$(MANUAL_$(2)_ASCIIDOC_CONF)
+$(2)_$(3)_ASCIIDOC_CONF = docs/$(1)/asciidoc-$(3).conf
+ifneq ($$(wildcard $$($(2)_$(3)_ASCIIDOC_CONF)),)
+$(2)_$(3)_ASCIIDOC_OPTS += -f $$($(2)_$(3)_ASCIIDOC_CONF)
 endif
 
 # Handle a2x warning about --destination-dir option only applicable to HTML
 # based outputs. So:
 # - use the --destination-dir option if possible (html and split-html),
-# - otherwise copy the generated manual to the output directory
-MANUAL_$(2)_A2X_OPTS =
-ifneq ($$(filter $(3),html split-html),)
-MANUAL_$(2)_A2X_OPTS += --destination-dir="$$(@D)"
+# - otherwise copy the generated document to the output directory
+$(2)_$(3)_A2X_OPTS =
+ifneq ($$(filter $(4),html split-html),)
+$(2)_$(3)_A2X_OPTS += --destination-dir="$$(@D)"
 else
-define MANUAL_$(2)_INSTALL_CMDS
-	$$(Q)cp -f $$(BUILD_DIR)/docs/$(1)/$(1).$(4) $$(@D)
+define $(2)_$(3)_INSTALL_CMDS
+	$$(Q)cp -f $$(BUILD_DIR)/docs/$(1)/$(1).$(5) $$(@D)
 endef
 endif
 
-ifeq ($(4)-$$(MANUAL_XSLTPROC_IS_BROKEN),pdf-y)
-$$(O)/docs/$(1)/$(1).$(4):
-	$$(warning PDF manual generation is disabled because of a bug in \
-		xsltproc. To be able to generate the PDF manual, you should \
+ifeq ($(5)-$$(GENDOC_XSLTPROC_IS_BROKEN),pdf-y)
+$$(O)/docs/$(1)/$(1).$(5):
+	$$(warning PDF generation is disabled because of a bug in \
+		xsltproc. To be able to generate a PDF, you should \
 		build xsltproc from the libxslt sources >=1.1.29 and pass it \
 		to make through the command line: \
-		'PATH=/path/to/custom-xsltproc/bin:$$$${PATH} make manual-pdf')
+		'PATH=/path/to/custom-xsltproc/bin:$$$${PATH} make $(1)-pdf')
 else
-$$(O)/docs/$(1)/$(1).$(4): $$($$(call UPPERCASE,$(1))_SOURCES) \
-			   manual-check-dependencies \
-			   manual-check-dependencies-$(3) \
-			   manual-prepare-sources
-	$$(Q)$$(call MESSAGE,"Generating $(5) $(1)...")
+$$(O)/docs/$(1)/$(1).$(5): $$($(call UPPERCASE,$(1))_SOURCES) \
+			   $(1)-check-dependencies \
+			   $(1)-check-dependencies-$(4) \
+			   $(1)-prepare-sources
+	$$(Q)$$(call MESSAGE,"Generating $(6) $(1)...")
 	$$(Q)mkdir -p $$(@D)
-	$$(Q)a2x $(6) -f $(2) -d book -L -r $$(TOPDIR)/docs/images \
-		$$(MANUAL_$(2)_A2X_OPTS) \
-		--asciidoc-opts="$$(MANUAL_$(2)_ASCIIDOC_OPTS)" \
+	$$(Q)a2x $(7) -f $(3) -d book -L -r $$(TOPDIR)/docs/images \
+		$$($(2)_$(3)_A2X_OPTS) \
+		--asciidoc-opts="$$($(2)_$(3)_ASCIIDOC_OPTS)" \
 		$$(BUILD_DIR)/docs/$(1)/$(1).txt
-# install the generated manual
-	$$(MANUAL_$(2)_INSTALL_CMDS)
+# install the generated document
+	$$($(2)_$(3)_INSTALL_CMDS)
 endif
 endef
 
@@ -129,17 +130,17 @@ $(pkgname)-rsync: $$(BUILD_DIR)/docs/$(pkgname)
 
 $(pkgname)-prepare-sources: $(pkgname)-rsync
 
-$(call GENDOC_INNER,$(pkgname),xhtml,html,html,HTML,\
+$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),xhtml,html,html,HTML,\
 	--xsltproc-opts "--stringparam toc.section.depth 1")
-$(call GENDOC_INNER,$(pkgname),chunked,split-html,chunked,split HTML,\
+$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),chunked,split-html,chunked,split HTML,\
 	--xsltproc-opts "--stringparam toc.section.depth 1")
 # dblatex needs to pass the '--maxvars ...' option to xsltproc to prevent it
 # from reaching the template recursion limit when processing the (long) target
 # package table and bailing out.
-$(call GENDOC_INNER,$(pkgname),pdf,pdf,pdf,PDF,\
+$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),pdf,pdf,pdf,PDF,\
 	--dblatex-opts "-P latex.output.revhistory=0 -x '--maxvars 100000'")
-$(call GENDOC_INNER,$(pkgname),text,text,text,text)
-$(call GENDOC_INNER,$(pkgname),epub,epub,epub,ePUB)
+$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),text,text,text,text)
+$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),epub,epub,epub,ePUB)
 clean: $(pkgname)-clean
 $(pkgname)-clean:
 	$$(Q)$$(RM) -rf $$(BUILD_DIR)/docs/$(pkgname)
-- 
1.9.1

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

[Thomas De Schampheleire]

Hi Yann,

On Sat, Sep 27, 2014 at 12:16 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Currently, GENDOC_INNER hard-codes some variables to have the name of the
> document in them:
>     MANUAL_$(2)_ASCIIDOC_CONF
>     MANUAL_$(2)_ASCIIDOC_OPTS
>     MANUAL_$(2)_A2X_OPTS
>     MANUAL_$(2)_INSTALL_CMDS
>     ...
>
> Also, it defines some dependency on the generation rule, onto:
>     manual-check-dependencies
>     manual-check-dependencies-$(3)
>     manual-prepare-sources
>
> This is problematic, as it is not possible to have another document
> generated with the GENDOC infra, or it would trigger the rules, and use
> the variables for our own document, 'manual'.
>
> Add a new argument to GENDOC_INNER to be the uppercase name of the
> document, much like it is done for the PKG_*_INNER functions. Replace
> any reference to 'manual' with the currently passed named of the current
> document, $(1).
>
> The remaining references to 'manual' are on purpose, as they really
> pertain to our manual.
>
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> Cc: Samuel Martin <s.martin49@gmail.com>
> Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
> Reviewed-by: Samuel Martin <s.martin49@gmail.com>
>
> ---
> Changes v5 -> v6:
>   - do not use $$ when calling UPPERCASE  (Thomas DS)
>   - also rename the variable with the xsltproc check  (Samuel)
>   - s/manual/document/g in the comments, too  (Thomas DS)
>   - typo in commit log  (Samuel)
> ---
>  docs/manual/manual.mk | 93 ++++++++++++++++++++++++++-------------------------
>  1 file changed, 47 insertions(+), 46 deletions(-)
>
> diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
> index c40f371..b0ae2da 100644
> --- a/docs/manual/manual.mk
> +++ b/docs/manual/manual.mk
> @@ -14,17 +14,17 @@ manual-prepare-sources: manual-update-lists
>  manual-check-dependencies:
>         $(Q)if [ -z "$(shell support/dependencies/check-host-asciidoc.sh)" ]; then \
>                 echo "You need a sufficiently recent asciidoc on your host" \
> -                       "to generate the manual"; \
> +                       "to generate a document"; \

Nit: I would write 'to generate documents' here.

>                 exit 1; \
>         fi
>         $(Q)if [ -z "`which w3m 2>/dev/null`" ]; then \
> -               echo "You need w3m on your host to generate the manual"; \
> +               echo "You need w3m on your host to generate a document"; \

Same here.

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

This would become 'to generate PDF documents'

>                 exit 1; \
>         fi
>
> @@ -35,18 +35,18 @@ manual-check-dependencies-lists:
>                 exit 1; \
>         fi
>
> -# PDF manual generation is broken because of a bug in xsltproc program provided
> +# PDF generation is broken because of a bug in xsltproc program provided
>  # by libxslt <=1.1.28, which does not honor an option we need to set.
>  # Fortunately, this bug is already fixed upstream:
>  #   https://gitorious.org/libxslt/libxslt/commit/5af7ad745323004984287e48b42712e7305de35c
>  #
> -# So, bail out when trying to build the pdf manual using a buggy version of the
> +# So, bail out when trying to build a PDF using a buggy version of the
>  # xsltproc program.
>  #
> -# So, to overcome this issue and being able to build the pdf manual, you can
> -# build xsltproc from it source repository, then run:
> +# So, to overcome this issue and being able to build a PDF, you can
> +# build xsltproc from its source repository, then run:
>  #   $ PATH=/path/to/custom-xsltproc/bin:${PATH} make manual
> -MANUAL_XSLTPROC_IS_BROKEN = \
> +GENDOC_XSLTPROC_IS_BROKEN = \
>         $(shell xsltproc --maxvars 0 >/dev/null 2>/dev/null || echo y)
>
>  ################################################################################
> @@ -55,11 +55,12 @@ MANUAL_XSLTPROC_IS_BROKEN = \
>  #
>  #  argument 1 is the name of the document and must be a subdirectory of docs/;
>  #             the top-level asciidoc file must have the same name
> -#  argument 2 is the type of document to generate (-f argument of a2x)
> -#  argument 3 is the document type as used in the make target
> -#  argument 4 is the output file extension for the document type
> -#  argument 5 is the human text for the document type
> -#  argument 6 (optional) are extra arguments for a2x
> +#  argument 2 is the uppercase name of the document
> +#  argument 3 is the type of document to generate (-f argument of a2x)
> +#  argument 4 is the document type as used in the make target
> +#  argument 5 is the output file extension for the document type
> +#  argument 6 is the human text for the document type
> +#  argument 7 (optional) are extra arguments for a2x
>  #
>  # The variable <DOCUMENT_NAME>_SOURCES defines the dependencies.
>  #
> @@ -67,50 +68,50 @@ MANUAL_XSLTPROC_IS_BROKEN = \
>  # all variable references except the arguments must be $$-quoted.
>  ################################################################################
>  define GENDOC_INNER
> -$(1): $(1)-$(3)
> -.PHONY: $(1)-$(3)
> -$(1)-$(3): $$(O)/docs/$(1)/$(1).$(4)
> +$(1): $(1)-$(4)
> +.PHONY: $(1)-$(4)
> +$(1)-$(4): $$(O)/docs/$(1)/$(1).$(5)
>
> -manual-check-dependencies-$(3):
> +$(1)-check-dependencies-$(4):
>
> -MANUAL_$(2)_ASCIIDOC_CONF = docs/$(1)/asciidoc-$(2).conf
> -ifneq ($$(wildcard $$(MANUAL_$(2)_ASCIIDOC_CONF)),)
> -MANUAL_$(2)_ASCIIDOC_OPTS += -f $$(MANUAL_$(2)_ASCIIDOC_CONF)
> +$(2)_$(3)_ASCIIDOC_CONF = docs/$(1)/asciidoc-$(3).conf
> +ifneq ($$(wildcard $$($(2)_$(3)_ASCIIDOC_CONF)),)
> +$(2)_$(3)_ASCIIDOC_OPTS += -f $$($(2)_$(3)_ASCIIDOC_CONF)
>  endif
>
>  # Handle a2x warning about --destination-dir option only applicable to HTML
>  # based outputs. So:
>  # - use the --destination-dir option if possible (html and split-html),
> -# - otherwise copy the generated manual to the output directory
> -MANUAL_$(2)_A2X_OPTS =
> -ifneq ($$(filter $(3),html split-html),)
> -MANUAL_$(2)_A2X_OPTS += --destination-dir="$$(@D)"
> +# - otherwise copy the generated document to the output directory
> +$(2)_$(3)_A2X_OPTS =
> +ifneq ($$(filter $(4),html split-html),)
> +$(2)_$(3)_A2X_OPTS += --destination-dir="$$(@D)"
>  else
> -define MANUAL_$(2)_INSTALL_CMDS
> -       $$(Q)cp -f $$(BUILD_DIR)/docs/$(1)/$(1).$(4) $$(@D)
> +define $(2)_$(3)_INSTALL_CMDS
> +       $$(Q)cp -f $$(BUILD_DIR)/docs/$(1)/$(1).$(5) $$(@D)
>  endef
>  endif
>
> -ifeq ($(4)-$$(MANUAL_XSLTPROC_IS_BROKEN),pdf-y)
> -$$(O)/docs/$(1)/$(1).$(4):
> -       $$(warning PDF manual generation is disabled because of a bug in \
> -               xsltproc. To be able to generate the PDF manual, you should \
> +ifeq ($(5)-$$(GENDOC_XSLTPROC_IS_BROKEN),pdf-y)
> +$$(O)/docs/$(1)/$(1).$(5):
> +       $$(warning PDF generation is disabled because of a bug in \
> +               xsltproc. To be able to generate a PDF, you should \
>                 build xsltproc from the libxslt sources >=1.1.29 and pass it \
>                 to make through the command line: \
> -               'PATH=/path/to/custom-xsltproc/bin:$$$${PATH} make manual-pdf')
> +               'PATH=/path/to/custom-xsltproc/bin:$$$${PATH} make $(1)-pdf')
>  else
> -$$(O)/docs/$(1)/$(1).$(4): $$($$(call UPPERCASE,$(1))_SOURCES) \
> -                          manual-check-dependencies \
> -                          manual-check-dependencies-$(3) \
> -                          manual-prepare-sources
> -       $$(Q)$$(call MESSAGE,"Generating $(5) $(1)...")
> +$$(O)/docs/$(1)/$(1).$(5): $$($(call UPPERCASE,$(1))_SOURCES) \

I didn't mean to also change this uppercase call from $$ to $. The
'exception' is until now only made when calling the inner infra from
the outer one. On this line, we are already in the inner infra so one
would use $$.

> +                          $(1)-check-dependencies \
> +                          $(1)-check-dependencies-$(4) \
> +                          $(1)-prepare-sources
> +       $$(Q)$$(call MESSAGE,"Generating $(6) $(1)...")

What is the purpose of the quotes here, given your recent commit of
qstrip in MESSAGE ?

Best regards,
Thomas

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

[Yann E. MORIN]

Thomas, All,

On 2014-09-29 21:33 +0200, Thomas De Schampheleire spake thusly:
> On Sat, Sep 27, 2014 at 12:16 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
[--SNIp--]
> > -                       "to generate the manual"; \
> > +                       "to generate a document"; \
> Nit: I would write 'to generate documents' here.
> > -               echo "You need w3m on your host to generate the manual"; \
> > +               echo "You need w3m on your host to generate a document"; \
> Same here.
> > -               echo "You need dblatex on your host to generate the pdf manual"; \
> > +               echo "You need dblatex on your host to generate a PDF document"; \
> This would become 'to generate PDF documents'

OK, I don;t mind. Will do.

> > +$$(O)/docs/$(1)/$(1).$(5): $$($(call UPPERCASE,$(1))_SOURCES) \
> 
> I didn't mean to also change this uppercase call from $$ to $. The
> 'exception' is until now only made when calling the inner infra from
> the outer one. On this line, we are already in the inner infra so one
> would use $$.

But that does not matter, does it?

The expansion of $(call UPPERCASE) is done on a parameter, so we might
as well expand it right at call time, rather than at evaluation time,
no?

> > +                          $(1)-check-dependencies \
> > +                          $(1)-check-dependencies-$(4) \
> > +                          $(1)-prepare-sources
> > +       $$(Q)$$(call MESSAGE,"Generating $(6) $(1)...")
> 
> What is the purpose of the quotes here, given your recent commit of
> qstrip in MESSAGE ?

Because I looked at what was done in pkg-generic or some such, and
mimicked. At which point someone noticed on the ML (or IRC) about the
quoting issue, and I did not adapt my code.

But it does not really matter: we can quote messages, now. Or not.

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  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 09/25 v6] docs/manual: do not hardcode name of the generated document

[Thomas De Schampheleire]

"Yann E. MORIN" <yann.morin.1998@free.fr> schreef:
>Thomas, All,
>
>On 2014-09-29 21:33 +0200, Thomas De Schampheleire spake thusly:
>> On Sat, Sep 27, 2014 at 12:16 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
>[--SNIp--]
>> > -                       "to generate the manual"; \
>> > +                       "to generate a document"; \
>> Nit: I would write 'to generate documents' here.
>> > -               echo "You need w3m on your host to generate the manual"; \
>> > +               echo "You need w3m on your host to generate a document"; \
>> Same here.
>> > -               echo "You need dblatex on your host to generate the pdf manual"; \
>> > +               echo "You need dblatex on your host to generate a PDF document"; \
>> This would become 'to generate PDF documents'
>
>OK, I don;t mind. Will do.
>
>> > +$$(O)/docs/$(1)/$(1).$(5): $$($(call UPPERCASE,$(1))_SOURCES) \
>> 
>> I didn't mean to also change this uppercase call from $$ to $. The
>> 'exception' is until now only made when calling the inner infra from
>> the outer one. On this line, we are already in the inner infra so one
>> would use $$.
>
>But that does not matter, does it?
>
>The expansion of $(call UPPERCASE) is done on a parameter, so we might
>as well expand it right at call time, rather than at evaluation time,
>no?

Technically you're right. However, in the discussion
 on the dollars we realized that the matter is
 sufficiently non-obvious that we better use clear cut
 rules. That rule says that everything should be $$
 except for parameters, pkgname/pkgdir and the
 uppercase call from outer to inner. 

In this case, you understand the issue and judge that
 a single $ suffices, but tomorrow someone else will
 change the value and forget to reevaluate the dollars.

>
>> > +                          $(1)-check-dependencies \
>> > +                          $(1)-check-dependencies-$(4) \
>> > +                          $(1)-prepare-sources
>> > +       $$(Q)$$(call MESSAGE,"Generating $(6) $(1)...")
>> 
>> What is the purpose of the quotes here, given your recent commit of
>> qstrip in MESSAGE ?
>
>Because I looked at what was done in pkg-generic or some such, and
>mimicked. At which point someone noticed on the ML (or IRC) about the
>quoting issue, and I did not adapt my code.
>
>But it does not really matter: we can quote messages, now. Or not.

True. I don't understand though why we wouldn't
 change all unnecessary quoting in the quest for symmetry and simplicity.

Best regards,
Thomas

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

[Yann E. MORIN]

Thomas, All,

On 2014-09-29 22:09 +0200, Thomas De Schampheleire spake thusly:
> "Yann E. MORIN" <yann.morin.1998@free.fr> schreef:
> >On 2014-09-29 21:33 +0200, Thomas De Schampheleire spake thusly:
> >> On Sat, Sep 27, 2014 at 12:16 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
[--SNIP--]
> >> > +$$(O)/docs/$(1)/$(1).$(5): $$($(call UPPERCASE,$(1))_SOURCES) \
> >> 
> >> I didn't mean to also change this uppercase call from $$ to $. The
> >> 'exception' is until now only made when calling the inner infra from
> >> the outer one. On this line, we are already in the inner infra so one
> >> would use $$.
> >
> >But that does not matter, does it?
> >
> >The expansion of $(call UPPERCASE) is done on a parameter, so we might
> >as well expand it right at call time, rather than at evaluation time,
> >no?
> 
> Technically you're right. However, in the discussion
>  on the dollars we realized that the matter is
>  sufficiently non-obvious that we better use clear cut
>  rules. That rule says that everything should be $$
>  except for parameters, pkgname/pkgdir and the
>  uppercase call from outer to inner. 
> 
> In this case, you understand the issue and judge that
>  a single $ suffices, but tomorrow someone else will
>  change the value and forget to reevaluate the dollars.

Agreed, that's fair. I will change.

> >> > +                          $(1)-check-dependencies \
> >> > +                          $(1)-check-dependencies-$(4) \
> >> > +                          $(1)-prepare-sources
> >> > +       $$(Q)$$(call MESSAGE,"Generating $(6) $(1)...")
> >> 
> >> What is the purpose of the quotes here, given your recent commit of
> >> qstrip in MESSAGE ?
> >
> >Because I looked at what was done in pkg-generic or some such, and
> >mimicked. At which point someone noticed on the ML (or IRC) about the
> >quoting issue, and I did not adapt my code.
> >
> >But it does not really matter: we can quote messages, now. Or not.
> 
> True. I don't understand though why we wouldn't
>  change all unnecessary quoting in the quest for symmetry and simplicity.

If at all, we should change to always quote messages.

The problem is two-fold:

  - no quoting: we can not have a comma in the message, otherwise make
    would split on it:  $(call MESSAGE,This, and that, should foo)

  - always quoting: the MESSAGE definition already does the quoting to
    ensure it does not break on a semi-colon (which you noticed):
    $(call MESSAGE,"; echo shellshock")

(He, shellshock is all the hype nowadays. Even superseeds heartbleed!)

If MESSAGE would not do the quoting, and rely on the caller to do it,
we'd be vulnerable to: $(call MESSAGE,; echo shellshock)

So: we want MESSAGE to always quote its arguments (and no, single quotes
do not cut it either, because a message might have single quotes too),
while still allowing callers to do the quoting. Or not.

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  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 09/25 v6] docs/manual: do not hardcode name of the generated document

[Arnout Vandecappelle]

On 29/09/14 22:26, Yann E. MORIN wrote:
> Thomas, All,
[snip]

>>> But it does not really matter: we can quote messages, now. Or not.
>>
>> True. I don't understand though why we wouldn't
>>  change all unnecessary quoting in the quest for symmetry and simplicity.
> 
> If at all, we should change to always quote messages.
> 
> The problem is two-fold:
> 
>   - no quoting: we can not have a comma in the message, otherwise make
>     would split on it:  $(call MESSAGE,This, and that, should foo)

 "-quotes are completely transparent for make, so quoting doesn't help for
commas. You need $(call MESSAGE,This$(comma) and that$(comma) should foo).


 Regards,
 Arnout

>   - always quoting: the MESSAGE definition already does the quoting to
>     ensure it does not break on a semi-colon (which you noticed):
>     $(call MESSAGE,"; echo shellshock")
> 
> (He, shellshock is all the hype nowadays. Even superseeds heartbleed!)
> 
> If MESSAGE would not do the quoting, and rely on the caller to do it,
> we'd be vulnerable to: $(call MESSAGE,; echo shellshock)
> 
> So: we want MESSAGE to always quote its arguments (and no, single quotes
> do not cut it either, because a message might have single quotes too),
> while still allowing callers to do the quoting. Or not.
> 
> Regards,
> Yann E. MORIN.
> 


-- 
Arnout Vandecappelle                          arnout at mind be
Senior Embedded Software Architect            +32-16-286500
Essensium/Mind                                http://www.mind.be
G.Geenslaan 9, 3001 Leuven, Belgium           BE 872 984 063 RPR Leuven
LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
GPG fingerprint:  7CB5 E4CC 6C2E EFD4 6E3D A754 F963 ECAB 2450 2F1F

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

[Yann E. MORIN]

Avoids hard-coding document's resources in GENDOC_INNER, so we can
generate another document with different resources (if any).

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

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

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index b0ae2da..f5af504 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)_RESOURCES),-r $$(r)) \
 		$$($(2)_$(3)_A2X_OPTS) \
 		--asciidoc-opts="$$($(2)_$(3)_ASCIIDOC_OPTS)" \
 		$$(BUILD_DIR)/docs/$(1)/$(1).txt
@@ -119,6 +120,8 @@ endef
 # GENDOC -- generates the make targets needed to build asciidoc documentation.
 #
 # The variable <DOCUMENT_NAME>_SOURCES defines the dependencies.
+# The variable <DOCUMENT_NAME>_RESOURCES defines where the document's
+# resources, such as images, are located; must be an absolute path.
 ################################################################################
 define GENDOC
 $$(BUILD_DIR)/docs/$(pkgname):
@@ -148,4 +151,5 @@ $(pkgname)-clean:
 endef
 
 MANUAL_SOURCES = $(sort $(wildcard docs/manual/*.txt) $(wildcard docs/images/*))
+MANUAL_RESOURCES = $(TOPDIR)/docs/images
 $(eval $(call GENDOC))
-- 
1.9.1

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

[Samuel Martin]

On Sat, Sep 27, 2014 at 12:16 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Avoids hard-coding document's resources in GENDOC_INNER, so we can
> generate another document with different resources (if any).
>
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> Cc: Samuel Martin <s.martin49@gmail.com>
> Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>

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


-- 
Samuel

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

[Thomas De Schampheleire]

On Sat, Sep 27, 2014 at 12:16 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Avoids hard-coding document's resources in GENDOC_INNER, so we can
> generate another document with different resources (if any).
>
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> Cc: Samuel Martin <s.martin49@gmail.com>
> Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>

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

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

[Yann E. MORIN]

GENDOC_INNER still has one hard-coded path to the document's directory:
the asciidoc .conf files.

Add a new argument to GENDOC_INNER to pass the directory of the
document.

Notes:

- this makes for overly-long lines, but splitting is not possible,
otherwise the first argument on the continuation line would get (at
least) a leading space or tab, and that would break either or all of
the variables names, the dependency rules, or the filenames we look
for. A future patch will further clean this up (see: docs/asciidoc: call
$(pkgname) and $(pkgdir) in a single place.)

- this means that another document would be missing our tweaks from
asciidoc-text.conf to not render images and sanely render hyperlinks.
But that was already the case anyway, since we were using docs/$(1)/ to
search for that file. A further patch will allow us to have such
configuration in a common place.

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
---
 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 f5af504..dfea759 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -53,14 +53,15 @@ GENDOC_XSLTPROC_IS_BROKEN = \
 # GENDOC_INNER -- generates the make targets needed to build a specific type of
 #                 asciidoc documentation.
 #
-#  argument 1 is the name of the document and must be a subdirectory of docs/;
-#             the top-level asciidoc file must have the same name
+#  argument 1 is the name of the document and the top-level asciidoc file must
+#             have the same name
 #  argument 2 is the uppercase name of the document
-#  argument 3 is the type of document to generate (-f argument of a2x)
-#  argument 4 is the document type as used in the make target
-#  argument 5 is the output file extension for the document type
-#  argument 6 is the human text for the document type
-#  argument 7 (optional) are extra arguments for a2x
+#  argument 3 is the directory containing the document
+#  argument 4 is the type of document to generate (-f argument of a2x)
+#  argument 5 is the document type as used in the make target
+#  argument 6 is the output file extension for the document type
+#  argument 7 is the human text for the document type
+#  argument 8 (optional) are extra arguments for a2x
 #
 # The variable <DOCUMENT_NAME>_SOURCES defines the dependencies.
 #
@@ -68,51 +69,51 @@ GENDOC_XSLTPROC_IS_BROKEN = \
 # all variable references except the arguments must be $$-quoted.
 ################################################################################
 define GENDOC_INNER
-$(1): $(1)-$(4)
-.PHONY: $(1)-$(4)
-$(1)-$(4): $$(O)/docs/$(1)/$(1).$(5)
+$(1): $(1)-$(5)
+.PHONY: $(1)-$(5)
+$(1)-$(5): $$(O)/docs/$(1)/$(1).$(6)
 
-$(1)-check-dependencies-$(4):
+$(1)-check-dependencies-$(5):
 
-$(2)_$(3)_ASCIIDOC_CONF = docs/$(1)/asciidoc-$(3).conf
-ifneq ($$(wildcard $$($(2)_$(3)_ASCIIDOC_CONF)),)
-$(2)_$(3)_ASCIIDOC_OPTS += -f $$($(2)_$(3)_ASCIIDOC_CONF)
+$(2)_$(4)_ASCIIDOC_CONF = $(3)/asciidoc-$(4).conf
+ifneq ($$(wildcard $$($(2)_$(4)_ASCIIDOC_CONF)),)
+$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_$(4)_ASCIIDOC_CONF)
 endif
 
 # Handle a2x warning about --destination-dir option only applicable to HTML
 # based outputs. So:
 # - use the --destination-dir option if possible (html and split-html),
 # - otherwise copy the generated document to the output directory
-$(2)_$(3)_A2X_OPTS =
-ifneq ($$(filter $(4),html split-html),)
-$(2)_$(3)_A2X_OPTS += --destination-dir="$$(@D)"
+$(2)_$(4)_A2X_OPTS =
+ifneq ($$(filter $(5),html split-html),)
+$(2)_$(4)_A2X_OPTS += --destination-dir="$$(@D)"
 else
-define $(2)_$(3)_INSTALL_CMDS
-	$$(Q)cp -f $$(BUILD_DIR)/docs/$(1)/$(1).$(5) $$(@D)
+define $(2)_$(4)_INSTALL_CMDS
+	$$(Q)cp -f $$(BUILD_DIR)/docs/$(1)/$(1).$(6) $$(@D)
 endef
 endif
 
-ifeq ($(5)-$$(GENDOC_XSLTPROC_IS_BROKEN),pdf-y)
-$$(O)/docs/$(1)/$(1).$(5):
+ifeq ($(6)-$$(GENDOC_XSLTPROC_IS_BROKEN),pdf-y)
+$$(O)/docs/$(1)/$(1).$(6):
 	$$(warning PDF generation is disabled because of a bug in \
 		xsltproc. To be able to generate a PDF, you should \
 		build xsltproc from the libxslt sources >=1.1.29 and pass it \
 		to make through the command line: \
 		'PATH=/path/to/custom-xsltproc/bin:$$$${PATH} make $(1)-pdf')
 else
-$$(O)/docs/$(1)/$(1).$(5): $$($(call UPPERCASE,$(1))_SOURCES) \
+$$(O)/docs/$(1)/$(1).$(6): $$($(call UPPERCASE,$(1))_SOURCES) \
 			   $(1)-check-dependencies \
-			   $(1)-check-dependencies-$(4) \
+			   $(1)-check-dependencies-$(5) \
 			   $(1)-prepare-sources
-	$$(Q)$$(call MESSAGE,"Generating $(6) $(1)...")
+	$$(Q)$$(call MESSAGE,"Generating $(7) $(1)...")
 	$$(Q)mkdir -p $$(@D)
-	$$(Q)a2x $(7) -f $(3) -d book -L \
+	$$(Q)a2x $(8) -f $(4) -d book -L \
 		$$(foreach r,$$($(2)_RESOURCES),-r $$(r)) \
-		$$($(2)_$(3)_A2X_OPTS) \
-		--asciidoc-opts="$$($(2)_$(3)_ASCIIDOC_OPTS)" \
+		$$($(2)_$(4)_A2X_OPTS) \
+		--asciidoc-opts="$$($(2)_$(4)_ASCIIDOC_OPTS)" \
 		$$(BUILD_DIR)/docs/$(1)/$(1).txt
 # install the generated document
-	$$($(2)_$(3)_INSTALL_CMDS)
+	$$($(2)_$(4)_INSTALL_CMDS)
 endif
 endef
 
@@ -129,21 +130,26 @@ $$(BUILD_DIR)/docs/$(pkgname):
 
 $(pkgname)-rsync: $$(BUILD_DIR)/docs/$(pkgname)
 	$$(Q)$$(call MESSAGE,"Preparing the $(pkgname) sources...")
-	$$(Q)rsync -a docs/$(pkgname)/ $$^
+	$$(Q)rsync -a $(pkgdir) $$^
 
 $(pkgname)-prepare-sources: $(pkgname)-rsync
 
-$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),xhtml,html,html,HTML,\
+$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),xhtml,html,html,HTML,\
 	--xsltproc-opts "--stringparam toc.section.depth 1")
-$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),chunked,split-html,chunked,split HTML,\
+
+$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),chunked,split-html,chunked,split HTML,\
 	--xsltproc-opts "--stringparam toc.section.depth 1")
+
 # dblatex needs to pass the '--maxvars ...' option to xsltproc to prevent it
 # from reaching the template recursion limit when processing the (long) target
 # package table and bailing out.
-$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),pdf,pdf,pdf,PDF,\
+$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),pdf,pdf,pdf,PDF,\
 	--dblatex-opts "-P latex.output.revhistory=0 -x '--maxvars 100000'")
-$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),text,text,text,text)
-$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),epub,epub,epub,ePUB)
+
+$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),text,text,text,text)
+
+$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),epub,epub,epub,ePUB)
+
 clean: $(pkgname)-clean
 $(pkgname)-clean:
 	$$(Q)$$(RM) -rf $$(BUILD_DIR)/docs/$(pkgname)
-- 
1.9.1

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

[Samuel Martin]

On Sat, Sep 27, 2014 at 12:16 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.
>
> Add a new argument to GENDOC_INNER to pass the directory of the
> document.
>
> Notes:
>
> - this makes for overly-long lines, but splitting is not possible,
> otherwise the first argument on the continuation line would get (at
> least) a leading space or tab, and that would break either or all of
> the variables names, the dependency rules, or the filenames we look
> for. A future patch will further clean this up (see: docs/asciidoc: call
> $(pkgname) and $(pkgdir) in a single place.)
>
> - this means that another document would be missing our tweaks from
> asciidoc-text.conf to not render images and sanely render hyperlinks.
> But that was already the case anyway, since we were using docs/$(1)/ to
> search for that file. A further patch will allow us to have such
> configuration in a common place.
>
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> Cc: Samuel Martin <s.martin49@gmail.com>
> Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>

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


-- 
Samuel

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

[Yann E. MORIN]

Move the rules specific to our own manual, so that they do not interfere
with the generic rules of GENDOC.

Separate them with a shiny header. ;-)

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Acked-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
---
 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 dfea759..05f6f05 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -1,14 +1,3 @@
-# Packages included in BR2_EXTERNAL are not part of buildroot, so they
-# should not be included in the manual.
-.PHONY: manual-update-lists
-manual-update-lists: manual-check-dependencies-lists $(BUILD_DIR)/docs/$(pkgname)
-	$(Q)$(call MESSAGE,"Updating the manual lists...")
-	$(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(BUILD_DIR)/docs/$(pkgname) \
-		BR2_EXTERNAL=$(TOPDIR)/support/dummy-external \
-		python -B $(TOPDIR)/support/scripts/gen-manual-lists.py
-
-manual-prepare-sources: manual-update-lists
-
 # we can't use suitable-host-package here because that's not available in
 # the context of 'make release'
 manual-check-dependencies:
@@ -28,13 +17,6 @@ manual-check-dependencies-pdf:
 		exit 1; \
 	fi
 
-manual-check-dependencies-lists:
-	$(Q)if ! python -c "import argparse" >/dev/null 2>&1 ; then \
-		echo "You need python with argparse on your host to generate" \
-			"the list of packages in the manual"; \
-		exit 1; \
-	fi
-
 # PDF generation is broken because of a bug in xsltproc program provided
 # by libxslt <=1.1.28, which does not honor an option we need to set.
 # Fortunately, this bug is already fixed upstream:
@@ -156,6 +138,29 @@ $(pkgname)-clean:
 .PHONY: $(pkgname) $(pkgname)-clean
 endef
 
+################################################################################
+# The Buildroot manual
+################################################################################
+
+# Our manual needs to generate lists
+manual-prepare-sources: manual-update-lists
+
+# Packages included in BR2_EXTERNAL are not part of buildroot, so they
+# should not be included in the manual.
+.PHONY: manual-update-lists
+manual-update-lists: manual-check-dependencies-lists $(BUILD_DIR)/docs/$(pkgname)
+	$(Q)$(call MESSAGE,"Updating the manual lists...")
+	$(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(BUILD_DIR)/docs/$(pkgname) \
+		BR2_EXTERNAL=$(TOPDIR)/support/dummy-external \
+		python -B $(TOPDIR)/support/scripts/gen-manual-lists.py
+
+manual-check-dependencies-lists:
+	$(Q)if ! python -c "import argparse" >/dev/null 2>&1 ; then \
+		echo "You need python with argparse on your host to generate" \
+			"the list of packages in the manual"; \
+		exit 1; \
+	fi
+
 MANUAL_SOURCES = $(sort $(wildcard docs/manual/*.txt) $(wildcard docs/images/*))
 MANUAL_RESOURCES = $(TOPDIR)/docs/images
 $(eval $(call GENDOC))
-- 
1.9.1

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

[Samuel Martin]

On Sat, Sep 27, 2014 at 12:16 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 shiny header. ;-)
>
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> Cc: Samuel Martin <s.martin49@gmail.com>
> Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
> Acked-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

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


-- 
Samuel

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

[Yann E. MORIN]

Those rules are generic, and not specific to our manual, we want them
always called:
  - manual-check-dependencies
  - manual-check-dependencies-pdf

So, rename them to be generic to gendoc.

Cascade the document's dependency checking to call those rules, too.

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

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index 05f6f05..26906b5 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 a document"; \
@@ -11,7 +11,7 @@ manual-check-dependencies:
 		exit 1; \
 	fi
 
-manual-check-dependencies-pdf:
+gendoc-check-dependencies-pdf:
 	$(Q)if [ -z "`which dblatex 2>/dev/null`" ]; then \
 		echo "You need dblatex on your host to generate a PDF document"; \
 		exit 1; \
@@ -55,7 +55,10 @@ $(1): $(1)-$(5)
 .PHONY: $(1)-$(5)
 $(1)-$(5): $$(O)/docs/$(1)/$(1).$(6)
 
-$(1)-check-dependencies-$(5):
+$(1)-check-dependencies: gendoc-check-dependencies
+
+gendoc-check-dependencies-$(5):
+$(1)-check-dependencies-$(5): gendoc-check-dependencies-$(5)
 
 $(2)_$(4)_ASCIIDOC_CONF = $(3)/asciidoc-$(4).conf
 ifneq ($$(wildcard $$($(2)_$(4)_ASCIIDOC_CONF)),)
-- 
1.9.1

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

[Yann E. MORIN]

Allow documents to define two hooks:
  - DOC_CHECK_EXTRA_DEPENDENCIES_HOOKS
    to check for extra dependencies required by this document
  - DOC_CHECK_EXTRA_DEPENDENCIES_FMT_HOOKS
    ditto, but for the specific format
  - DOC_POST_EXTRACT_HOOKS:
    to run additional actions to fill-in the build directory

(Replace 'DOC' with the uppercase name of the document, and 'FMT' with
the format.)

This is supposed to replace the current use of overloading the internal
dependency rules, and makes GENDOC behave yet a bit more like the
package infrastructure.

Note that GENDOC_INNER already has the uppercase name as an argument,
whereas GENDOC does not, so the two foreach loops are not exactly
similar (for now.)

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

---
Changes v5 -> v6:
  - do not use $$ for call to UPPERCASE  (Thomas DS)

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

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index 26906b5..2ee680e 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -55,10 +55,10 @@ $(1): $(1)-$(5)
 .PHONY: $(1)-$(5)
 $(1)-$(5): $$(O)/docs/$(1)/$(1).$(6)
 
-$(1)-check-dependencies: gendoc-check-dependencies
-
+# Single line, because splitting a foreach is not easy...
 gendoc-check-dependencies-$(5):
 $(1)-check-dependencies-$(5): gendoc-check-dependencies-$(5)
+	$$(Q)$$(foreach hook,$$($(2)_CHECK_DEPENDENCIES_$(call UPPERCASE,$(5))_HOOKS),$$(call $$(hook))$$(sep))
 
 $(2)_$(4)_ASCIIDOC_CONF = $(3)/asciidoc-$(4).conf
 ifneq ($$(wildcard $$($(2)_$(4)_ASCIIDOC_CONF)),)
@@ -110,12 +110,18 @@ endef
 # resources, such as images, are located; must be an absolute path.
 ################################################################################
 define GENDOC
+# Single line, because splitting a foreach is not easy...
+$(pkgname)-check-dependencies: gendoc-check-dependencies
+	$$(Q)$$(foreach hook,$$($(call UPPERCASE,$(pkgname))_CHECK_DEPENDENCIES_HOOKS),$$(call $$(hook))$$(sep))
+
 $$(BUILD_DIR)/docs/$(pkgname):
 	$$(Q)mkdir -p $$@
 
+# Single line, because splitting a foreach is not easy...
 $(pkgname)-rsync: $$(BUILD_DIR)/docs/$(pkgname)
 	$$(Q)$$(call MESSAGE,"Preparing the $(pkgname) sources...")
 	$$(Q)rsync -a $(pkgdir) $$^
+	$$(Q)$$(foreach hook,$$($(call UPPERCASE,$(pkgname))_POST_RSYNC_HOOKS),$$(call $$(hook))$$(sep))
 
 $(pkgname)-prepare-sources: $(pkgname)-rsync
 
-- 
1.9.1

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

[Thomas De Schampheleire]

On Sat, Sep 27, 2014 at 12:16 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Allow documents to define two hooks:
>   - DOC_CHECK_EXTRA_DEPENDENCIES_HOOKS
>     to check for extra dependencies required by this document
>   - DOC_CHECK_EXTRA_DEPENDENCIES_FMT_HOOKS
>     ditto, but for the specific format
>   - DOC_POST_EXTRACT_HOOKS:
>     to run additional actions to fill-in the build directory
>
> (Replace 'DOC' with the uppercase name of the document, and 'FMT' with
> the format.)
>
> This is supposed to replace the current use of overloading the internal
> dependency rules, and makes GENDOC behave yet a bit more like the
> package infrastructure.
>
> Note that GENDOC_INNER already has the uppercase name as an argument,
> whereas GENDOC does not, so the two foreach loops are not exactly
> similar (for now.)
>
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> Cc: Samuel Martin <s.martin49@gmail.com>
> Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
> Reviewed-by: Samuel Martin <s.martin49@gmail.com>
>
> ---
> Changes v5 -> v6:
>   - do not use $$ for call to UPPERCASE  (Thomas DS)
>

Here the same misunderstanding occurred. In these cases, I do think $$
should be used.

If the resulting patch is the same as v5, my Ack on that still counts.

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

[Yann E. MORIN]

Also reorder a bit the definition of the variables, to more resemble
a package. Yet a bit more...

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

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

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index 2ee680e..94f7551 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -151,25 +151,28 @@ endef
 # The Buildroot manual
 ################################################################################
 
-# Our manual needs to generate lists
-manual-prepare-sources: manual-update-lists
+MANUAL_SOURCES = $(sort $(wildcard docs/manual/*.txt) $(wildcard docs/images/*))
+MANUAL_RESOURCES = $(TOPDIR)/docs/images
 
+# Our manual needs to generate lists
 # Packages included in BR2_EXTERNAL are not part of buildroot, so they
 # should not be included in the manual.
-.PHONY: manual-update-lists
-manual-update-lists: manual-check-dependencies-lists $(BUILD_DIR)/docs/$(pkgname)
+define MANUAL_GEN_LISTS
 	$(Q)$(call MESSAGE,"Updating the manual lists...")
 	$(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(BUILD_DIR)/docs/$(pkgname) \
 		BR2_EXTERNAL=$(TOPDIR)/support/dummy-external \
 		python -B $(TOPDIR)/support/scripts/gen-manual-lists.py
+endef
+MANUAL_POST_RSYNC_HOOKS += MANUAL_GEN_LISTS
 
-manual-check-dependencies-lists:
+# Our list-generating script requires argparse
+define MANUAL_CHECK_LISTS_DEPS
 	$(Q)if ! python -c "import argparse" >/dev/null 2>&1 ; then \
 		echo "You need python with argparse on your host to generate" \
 			"the list of packages in the manual"; \
 		exit 1; \
 	fi
+endef
+MANUAL_CHECK_DEPENDENCIES_HOOKS += MANUAL_CHECK_LISTS_DEPS
 
-MANUAL_SOURCES = $(sort $(wildcard docs/manual/*.txt) $(wildcard docs/images/*))
-MANUAL_RESOURCES = $(TOPDIR)/docs/images
 $(eval $(call GENDOC))
-- 
1.9.1

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

[Thomas De Schampheleire]

On Sat, Sep 27, 2014 at 12:16 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Also reorder a bit the definition of the variables, to more resemble
> a package. Yet a bit more...
>
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> Cc: Samuel Martin <s.martin49@gmail.com>
> Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
> Reviewed-by: Samuel Martin <s.martin49@gmail.com>
>
> ---
> Changes v5 -> v6:
>   - hooks were renamed  (Thomas DS)
>   - typo  (Thomas DS)
> ---
>  docs/manual/manual.mk | 17 ++++++++++-------
>  1 file changed, 10 insertions(+), 7 deletions(-)
>
> diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
> index 2ee680e..94f7551 100644
> --- a/docs/manual/manual.mk
> +++ b/docs/manual/manual.mk
> @@ -151,25 +151,28 @@ endef
>  # The Buildroot manual
>  ################################################################################
>
> -# Our manual needs to generate lists
> -manual-prepare-sources: manual-update-lists
> +MANUAL_SOURCES = $(sort $(wildcard docs/manual/*.txt) $(wildcard docs/images/*))
> +MANUAL_RESOURCES = $(TOPDIR)/docs/images
>
> +# Our manual needs to generate lists
>  # Packages included in BR2_EXTERNAL are not part of buildroot, so they
>  # should not be included in the manual.
> -.PHONY: manual-update-lists
> -manual-update-lists: manual-check-dependencies-lists $(BUILD_DIR)/docs/$(pkgname)
> +define MANUAL_GEN_LISTS
>         $(Q)$(call MESSAGE,"Updating the manual lists...")
>         $(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(BUILD_DIR)/docs/$(pkgname) \
>                 BR2_EXTERNAL=$(TOPDIR)/support/dummy-external \
>                 python -B $(TOPDIR)/support/scripts/gen-manual-lists.py
> +endef
> +MANUAL_POST_RSYNC_HOOKS += MANUAL_GEN_LISTS
>
> -manual-check-dependencies-lists:
> +# Our list-generating script requires argparse
> +define MANUAL_CHECK_LISTS_DEPS
>         $(Q)if ! python -c "import argparse" >/dev/null 2>&1 ; then \
>                 echo "You need python with argparse on your host to generate" \
>                         "the list of packages in the manual"; \
>                 exit 1; \
>         fi
> +endef
> +MANUAL_CHECK_DEPENDENCIES_HOOKS += MANUAL_CHECK_LISTS_DEPS
>
> -MANUAL_SOURCES = $(sort $(wildcard docs/manual/*.txt) $(wildcard docs/images/*))
> -MANUAL_RESOURCES = $(TOPDIR)/docs/images
>  $(eval $(call GENDOC))
> --
> 1.9.1
>

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

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

[Yann E. MORIN]

Our manual does not use external filters in asciidoc, so we are happy
with just looking for resources from our source tree.

However, other documents (like ones in br2-external) may use such
filters, to generate diagrams, graphs...

External filters generate their output files in the output directory, so
we must also look for resources in there.

Note: external filters in asccidoc are used thus:
    ["filter-name"]
    ----
    Text to be rendered
    ----

In the future, our own manual may even make use of filters to include
some of the graphs we generate, to store in the documentation.

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

---
Changes v5 -> v6:
  - comment in the code the reason for -r  (Thomas DS)

---
Note: this is to work around a deficiency (bug?) in asccidoc. Asciidoc
actually tells the filter where to put the output files, but forgets to
look in there when it needs to link to those files...
---
 docs/manual/manual.mk | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index 94f7551..8e55035 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -86,6 +86,8 @@ $$(O)/docs/$(1)/$(1).$(6):
 		to make through the command line: \
 		'PATH=/path/to/custom-xsltproc/bin:$$$${PATH} make $(1)-pdf')
 else
+# -r $(@D) is there for documents that use external filters; those filters
+# generate code at the same location it finds the document's source files.
 $$(O)/docs/$(1)/$(1).$(6): $$($(call UPPERCASE,$(1))_SOURCES) \
 			   $(1)-check-dependencies \
 			   $(1)-check-dependencies-$(5) \
@@ -93,7 +95,7 @@ $$(O)/docs/$(1)/$(1).$(6): $$($(call UPPERCASE,$(1))_SOURCES) \
 	$$(Q)$$(call MESSAGE,"Generating $(7) $(1)...")
 	$$(Q)mkdir -p $$(@D)
 	$$(Q)a2x $(8) -f $(4) -d book -L \
-		$$(foreach r,$$($(2)_RESOURCES),-r $$(r)) \
+		$$(foreach r,$$($(2)_RESOURCES),-r $$(r)) -r $$(@D) \
 		$$($(2)_$(4)_A2X_OPTS) \
 		--asciidoc-opts="$$($(2)_$(4)_ASCIIDOC_OPTS)" \
 		$$(BUILD_DIR)/docs/$(1)/$(1).txt
-- 
1.9.1

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

[Thomas De Schampheleire]

On Sat, Sep 27, 2014 at 12:16 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 resources from our source tree.
>
> However, other documents (like ones in br2-external) may use such
> filters, to generate diagrams, graphs...
>
> External filters generate their output files in the output directory, so
> we must also look for resources in there.
>
> Note: external filters in asccidoc are used thus:
>     ["filter-name"]
>     ----
>     Text to be rendered
>     ----
>
> In the future, our own manual may even make use of filters to include
> some of the graphs we generate, to store in the documentation.
>
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> Cc: Samuel Martin <s.martin49@gmail.com>
> Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
> Reviewed-by: Samuel Martin <s.martin49@gmail.com>
>

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

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

[Yann E. MORIN]

Move the GENDOC infra to its own file, so it is even less tied to our
manual document, so that it is more obvious that GENDOC is an infra like
our packages infras, and 'manual' is a document like we have packages.

Ideally, this new file should better go in docs/ rather than in package/ .
However, docs/ is already full of our website stuff, so adding it in
there would just serve to clutter the website.

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

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Acked-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
---
 Makefile              |   1 +
 docs/manual/manual.mk | 151 --------------------------------------------------
 package/gendoc.mk     | 150 +++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 151 insertions(+), 151 deletions(-)
 create mode 100644 package/gendoc.mk

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

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

[Samuel Martin]

On Sat, Sep 27, 2014 at 12:16 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>
> Acked-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

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


-- 
Samuel

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

[Yann E. MORIN]

Rename the GENDOC infrastructure so that it more closely matches the way
we handle the packages infras.

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

---
Chamges v5 -> v6:
  - fix typo: s/asiciidoc/asciidoc/
---
 Makefile                               |  2 +-
 docs/manual/manual.mk                  |  2 +-
 package/{gendoc.mk => doc-asciidoc.mk} | 36 ++++++++++++++++++++--------------
 3 files changed, 23 insertions(+), 17 deletions(-)
 rename package/{gendoc.mk => doc-asciidoc.mk} (81%)

diff --git a/Makefile b/Makefile
index 5a1bbbd..3146525 100644
--- a/Makefile
+++ b/Makefile
@@ -272,7 +272,7 @@ unexport DESTDIR
 unexport RUBYOPT
 
 include package/pkg-utils.mk
-include package/gendoc.mk
+include package/doc-asciidoc.mk
 
 ifeq ($(BR2_HAVE_DOT_CONFIG),y)
 
diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index 2411da4..da260df 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -26,4 +26,4 @@ define MANUAL_CHECK_LISTS_DEPS
 endef
 MANUAL_CHECK_DEPENDENCIES_HOOKS += MANUAL_CHECK_LISTS_DEPS
 
-$(eval $(call GENDOC))
+$(eval $(call asciidoc-document))
diff --git a/package/gendoc.mk b/package/doc-asciidoc.mk
similarity index 81%
rename from package/gendoc.mk
rename to package/doc-asciidoc.mk
index 737627b..856ea2f 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 a document"; \
@@ -11,7 +11,7 @@ gendoc-check-dependencies:
 		exit 1; \
 	fi
 
-gendoc-check-dependencies-pdf:
+asciidoc-check-dependencies-pdf:
 	$(Q)if [ -z "`which dblatex 2>/dev/null`" ]; then \
 		echo "You need dblatex on your host to generate a PDF document"; \
 		exit 1; \
@@ -32,8 +32,8 @@ GENDOC_XSLTPROC_IS_BROKEN = \
 	$(shell xsltproc --maxvars 0 >/dev/null 2>/dev/null || echo y)
 
 ################################################################################
-# GENDOC_INNER -- generates the make targets needed to build a specific type of
-#                 asciidoc documentation.
+# ASCIIDOC_INNER -- generates the make targets needed to build a specific type of
+#                   asciidoc documentation.
 #
 #  argument 1 is the name of the document and the top-level asciidoc file must
 #             have the same name
@@ -50,14 +50,14 @@ GENDOC_XSLTPROC_IS_BROKEN = \
 # Since this function will be called from within an $(eval ...)
 # all variable references except the arguments must be $$-quoted.
 ################################################################################
-define GENDOC_INNER
+define ASCIIDOC_INNER
 $(1): $(1)-$(5)
 .PHONY: $(1)-$(5)
 $(1)-$(5): $$(O)/docs/$(1)/$(1).$(6)
 
 # Single line, because splitting a foreach is not easy...
-gendoc-check-dependencies-$(5):
-$(1)-check-dependencies-$(5): gendoc-check-dependencies-$(5)
+asciidoc-check-dependencies-$(5):
+$(1)-check-dependencies-$(5): asciidoc-check-dependencies-$(5)
 	$$(Q)$$(foreach hook,$$($(2)_CHECK_DEPENDENCIES_$(call UPPERCASE,$(5))_HOOKS),$$(call $$(hook))$$(sep))
 
 $(2)_$(4)_ASCIIDOC_CONF = $(3)/asciidoc-$(4).conf
@@ -105,15 +105,15 @@ endif
 endef
 
 ################################################################################
-# GENDOC -- generates the make targets needed to build asciidoc documentation.
+# ASCIIDOC -- generates the make targets needed to build asciidoc documentation.
 #
 # The variable <DOCUMENT_NAME>_SOURCES defines the dependencies.
 # The variable <DOCUMENT_NAME>_RESOURCES defines where the document's
 # resources, such as images, are located; must be an absolute path.
 ################################################################################
-define GENDOC
+define ASCIIDOC
 # Single line, because splitting a foreach is not easy...
-$(pkgname)-check-dependencies: gendoc-check-dependencies
+$(pkgname)-check-dependencies: asciidoc-check-dependencies
 	$$(Q)$$(foreach hook,$$($(call UPPERCASE,$(pkgname))_CHECK_DEPENDENCIES_HOOKS),$$(call $$(hook))$$(sep))
 
 $$(BUILD_DIR)/docs/$(pkgname):
@@ -127,24 +127,30 @@ $(pkgname)-rsync: $$(BUILD_DIR)/docs/$(pkgname)
 
 $(pkgname)-prepare-sources: $(pkgname)-rsync
 
-$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),xhtml,html,html,HTML,\
+$(call ASCIIDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),xhtml,html,html,HTML,\
 	--xsltproc-opts "--stringparam toc.section.depth 1")
 
-$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),chunked,split-html,chunked,split HTML,\
+$(call ASCIIDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),chunked,split-html,chunked,split HTML,\
 	--xsltproc-opts "--stringparam toc.section.depth 1")
 
 # dblatex needs to pass the '--maxvars ...' option to xsltproc to prevent it
 # from reaching the template recursion limit when processing the (long) target
 # package table and bailing out.
-$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),pdf,pdf,pdf,PDF,\
+$(call ASCIIDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),pdf,pdf,pdf,PDF,\
 	--dblatex-opts "-P latex.output.revhistory=0 -x '--maxvars 100000'")
 
-$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),text,text,text,text)
+$(call ASCIIDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),text,text,text,text)
 
-$(call GENDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),epub,epub,epub,ePUB)
+$(call ASCIIDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),epub,epub,epub,ePUB)
 
 clean: $(pkgname)-clean
 $(pkgname)-clean:
 	$$(Q)$$(RM) -rf $$(BUILD_DIR)/docs/$(pkgname)
 .PHONY: $(pkgname) $(pkgname)-clean
 endef
+
+################################################################################
+# asciidoc-document -- the target generator macro for asciidoc documents
+################################################################################
+
+asciidoc-document = $(call ASCIIDOC)
-- 
1.9.1

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

[Thomas De Schampheleire]

On Sat, Sep 27, 2014 at 12:16 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>

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

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

[Yann E. MORIN]

Like for all the package infrastructures, retrieve the package name and
directory in the front-end macro-variable, rather than everywhere in the
backend macro.

This allows us to clean up the ASCIIDOC macro, by removing all the calls
to $(pkgname) and $(pkgdir), and to UPPERCASE (which made the macro a
bit difficult to read.)

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

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

diff --git a/package/doc-asciidoc.mk b/package/doc-asciidoc.mk
index 856ea2f..d43f7ca 100644
--- a/package/doc-asciidoc.mk
+++ b/package/doc-asciidoc.mk
@@ -107,50 +107,55 @@ endef
 ################################################################################
 # ASCIIDOC -- generates the make targets needed to build asciidoc documentation.
 #
+# argument 1 is the lowercase name of the document; the document's main file
+#            must have the same name, with the .txt extension
+# argument 2 is the uppercase name of the document
+# argument 3 is the directory containing the document's sources
+#
 # The variable <DOCUMENT_NAME>_SOURCES defines the dependencies.
 # The variable <DOCUMENT_NAME>_RESOURCES defines where the document's
 # resources, such as images, are located; must be an absolute path.
 ################################################################################
 define ASCIIDOC
 # Single line, because splitting a foreach is not easy...
-$(pkgname)-check-dependencies: asciidoc-check-dependencies
-	$$(Q)$$(foreach hook,$$($(call UPPERCASE,$(pkgname))_CHECK_DEPENDENCIES_HOOKS),$$(call $$(hook))$$(sep))
+$(1)-check-dependencies: asciidoc-check-dependencies
+	$$(Q)$$(foreach hook,$$($(2)_CHECK_DEPENDENCIES_HOOKS),$$(call $$(hook))$$(sep))
 
-$$(BUILD_DIR)/docs/$(pkgname):
+$$(BUILD_DIR)/docs/$(1):
 	$$(Q)mkdir -p $$@
 
 # Single line, because splitting a foreach is not easy...
-$(pkgname)-rsync: $$(BUILD_DIR)/docs/$(pkgname)
-	$$(Q)$$(call MESSAGE,"Preparing the $(pkgname) sources...")
-	$$(Q)rsync -a $(pkgdir) $$^
-	$$(Q)$$(foreach hook,$$($(call UPPERCASE,$(pkgname))_POST_RSYNC_HOOKS),$$(call $$(hook))$$(sep))
+$(1)-rsync: $$(BUILD_DIR)/docs/$(1)
+	$$(Q)$$(call MESSAGE,"Preparing the $(1) sources...")
+	$$(Q)rsync -a $(3) $$^
+	$$(Q)$$(foreach hook,$$($(2)_POST_RSYNC_HOOKS),$$(call $$(hook))$$(sep))
 
-$(pkgname)-prepare-sources: $(pkgname)-rsync
+$(1)-prepare-sources: $(1)-rsync
 
-$(call ASCIIDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),xhtml,html,html,HTML,\
+$(call ASCIIDOC_INNER,$(1),$(2),$(3),xhtml,html,html,HTML,\
 	--xsltproc-opts "--stringparam toc.section.depth 1")
 
-$(call ASCIIDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),chunked,split-html,chunked,split HTML,\
+$(call ASCIIDOC_INNER,$(1),$(2),$(3),chunked,split-html,chunked,split HTML,\
 	--xsltproc-opts "--stringparam toc.section.depth 1")
 
 # dblatex needs to pass the '--maxvars ...' option to xsltproc to prevent it
 # from reaching the template recursion limit when processing the (long) target
 # package table and bailing out.
-$(call ASCIIDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),pdf,pdf,pdf,PDF,\
+$(call ASCIIDOC_INNER,$(1),$(2),$(3),pdf,pdf,pdf,PDF,\
 	--dblatex-opts "-P latex.output.revhistory=0 -x '--maxvars 100000'")
 
-$(call ASCIIDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),text,text,text,text)
+$(call ASCIIDOC_INNER,$(1),$(2),$(3),text,text,text,text)
 
-$(call ASCIIDOC_INNER,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir),epub,epub,epub,ePUB)
+$(call ASCIIDOC_INNER,$(1),$(2),$(3),epub,epub,epub,ePUB)
 
-clean: $(pkgname)-clean
-$(pkgname)-clean:
-	$$(Q)$$(RM) -rf $$(BUILD_DIR)/docs/$(pkgname)
-.PHONY: $(pkgname) $(pkgname)-clean
+clean: $(1)-clean
+$(1)-clean:
+	$$(Q)$$(RM) -rf $$(BUILD_DIR)/docs/$(1)
+.PHONY: $(1) $(1)-clean
 endef
 
 ################################################################################
 # asciidoc-document -- the target generator macro for asciidoc documents
 ################################################################################
 
-asciidoc-document = $(call ASCIIDOC)
+asciidoc-document = $(call ASCIIDOC,$(pkgname),$(call UPPERCASE,$(pkgname)),$(pkgdir))
-- 
1.9.1

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

[Thomas De Schampheleire]

On Sat, Sep 27, 2014 at 12:16 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>
>

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

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

[Yann E. MORIN]

Currently, it is not possible to use $(@D) in documents' hooks, because
there is no actual target file for the copying rule.

So, use the same mechanism as for generic-package.

We do not touch the target file, so it is easy to regenerate the manual
without calling the -clean rule first.

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

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index da260df..92aebb7 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -10,7 +10,7 @@ MANUAL_RESOURCES = $(TOPDIR)/docs/images
 # should not be included in the manual.
 define MANUAL_GEN_LISTS
 	$(Q)$(call MESSAGE,"Updating the manual lists...")
-	$(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(BUILD_DIR)/docs/$(pkgname) \
+	$(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(@D) \
 		BR2_EXTERNAL=$(TOPDIR)/support/dummy-external \
 		python -B $(TOPDIR)/support/scripts/gen-manual-lists.py
 endef
diff --git a/package/doc-asciidoc.mk b/package/doc-asciidoc.mk
index d43f7ca..4dc92a8 100644
--- a/package/doc-asciidoc.mk
+++ b/package/doc-asciidoc.mk
@@ -121,16 +121,16 @@ define ASCIIDOC
 $(1)-check-dependencies: asciidoc-check-dependencies
 	$$(Q)$$(foreach hook,$$($(2)_CHECK_DEPENDENCIES_HOOKS),$$(call $$(hook))$$(sep))
 
-$$(BUILD_DIR)/docs/$(1):
-	$$(Q)mkdir -p $$@
-
 # Single line, because splitting a foreach is not easy...
-$(1)-rsync: $$(BUILD_DIR)/docs/$(1)
+# Do not touch the stamp file, so we get to rsync again every time we build
+# the document.
+$$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced:
 	$$(Q)$$(call MESSAGE,"Preparing the $(1) sources...")
-	$$(Q)rsync -a $(3) $$^
+	$$(Q)mkdir -p $$(@D)
+	$$(Q)rsync -a $(3) $$(@D)
 	$$(Q)$$(foreach hook,$$($(2)_POST_RSYNC_HOOKS),$$(call $$(hook))$$(sep))
 
-$(1)-prepare-sources: $(1)-rsync
+$(1)-prepare-sources: $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced
 
 $(call ASCIIDOC_INNER,$(1),$(2),$(3),xhtml,html,html,HTML,\
 	--xsltproc-opts "--stringparam toc.section.depth 1")
-- 
1.9.1

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

[Thomas De Schampheleire]

On Sat, Sep 27, 2014 at 12:16 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>
> Cc: Samuel Martin <s.martin49@gmail.com>
> Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
> Reviewed-by: Samuel Martin <s.martin49@gmail.com>

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

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

[Yann E. MORIN]

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

But sometime it is required that a specific configuration is used for
all the output formats, to always apply the same markup rules in all
documents (like using the [specialwords] section.)

Also look for a file named 'asciidoc.conf' in the document's directory.
If that file exists, add it to the asciidoc options (before the
output-specific config, so the former takes precedence over the latter.)

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 | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/package/doc-asciidoc.mk b/package/doc-asciidoc.mk
index 4dc92a8..f949733 100644
--- a/package/doc-asciidoc.mk
+++ b/package/doc-asciidoc.mk
@@ -60,6 +60,10 @@ asciidoc-check-dependencies-$(5):
 $(1)-check-dependencies-$(5): asciidoc-check-dependencies-$(5)
 	$$(Q)$$(foreach hook,$$($(2)_CHECK_DEPENDENCIES_$(call UPPERCASE,$(5))_HOOKS),$$(call $$(hook))$$(sep))
 
+ifneq ($$(wildcard $$($(2)_ASCIIDOC_CONF)),)
+$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_ASCIIDOC_CONF)
+endif
+
 $(2)_$(4)_ASCIIDOC_CONF = $(3)/asciidoc-$(4).conf
 ifneq ($$(wildcard $$($(2)_$(4)_ASCIIDOC_CONF)),)
 $(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_$(4)_ASCIIDOC_CONF)
@@ -132,6 +136,8 @@ $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced:
 
 $(1)-prepare-sources: $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced
 
+$(2)_ASCIIDOC_CONF = $(3)/asciidoc.conf
+
 $(call ASCIIDOC_INNER,$(1),$(2),$(3),xhtml,html,html,HTML,\
 	--xsltproc-opts "--stringparam toc.section.depth 1")
 
-- 
1.9.1

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

[Samuel Martin]

Yann,

On Sat, Sep 27, 2014 at 12:16 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Currently, a document can specify an output-specific configuration, like
> the text output, that hides images references, and formats hyperlinks.
>
> But sometime it is required that a specific configuration is used for
> all the output formats, to always apply the same markup rules in all
> documents (like using the [specialwords] section.)
>
> Also look for a file named 'asciidoc.conf' in the document's directory.
> If that file exists, add it to the asciidoc options (before the
> output-specific config, so the former takes precedence over the latter.)

It is the other way around, no?
(the output-specific config taking precedence over/overriding the
sections defined in the global one)

>
> 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 | 6 ++++++
>  1 file changed, 6 insertions(+)
>
> diff --git a/package/doc-asciidoc.mk b/package/doc-asciidoc.mk
> index 4dc92a8..f949733 100644
> --- a/package/doc-asciidoc.mk
> +++ b/package/doc-asciidoc.mk
> @@ -60,6 +60,10 @@ asciidoc-check-dependencies-$(5):
>  $(1)-check-dependencies-$(5): asciidoc-check-dependencies-$(5)
>         $$(Q)$$(foreach hook,$$($(2)_CHECK_DEPENDENCIES_$(call UPPERCASE,$(5))_HOOKS),$$(call $$(hook))$$(sep))
>
> +ifneq ($$(wildcard $$($(2)_ASCIIDOC_CONF)),)
> +$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_ASCIIDOC_CONF)
> +endif
> +
>  $(2)_$(4)_ASCIIDOC_CONF = $(3)/asciidoc-$(4).conf
>  ifneq ($$(wildcard $$($(2)_$(4)_ASCIIDOC_CONF)),)
>  $(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_$(4)_ASCIIDOC_CONF)
> @@ -132,6 +136,8 @@ $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced:
>
>  $(1)-prepare-sources: $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced
>
> +$(2)_ASCIIDOC_CONF = $(3)/asciidoc.conf
> +
>  $(call ASCIIDOC_INNER,$(1),$(2),$(3),xhtml,html,html,HTML,\
>         --xsltproc-opts "--stringparam toc.section.depth 1")
>
> --
> 1.9.1
>

Regards,

-- 
Samuel

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

[Yann E. MORIN]

Samuel, All,

On 2014-09-27 13:20 +0200, Samuel Martin spake thusly:
> On Sat, Sep 27, 2014 at 12:16 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> > Currently, a document can specify an output-specific configuration, like
> > the text output, that hides images references, and formats hyperlinks.
> >
> > But sometime it is required that a specific configuration is used for
> > all the output formats, to always apply the same markup rules in all
> > documents (like using the [specialwords] section.)
> >
> > Also look for a file named 'asciidoc.conf' in the document's directory.
> > If that file exists, add it to the asciidoc options (before the
> > output-specific config, so the former takes precedence over the latter.)
> 
> It is the other way around, no?
> (the output-specific config taking precedence over/overriding the
> sections defined in the global one)

Yes indeed; the commit log is backward. Fixed.
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 21/25 v6] doc/asciidoc: allow documents to pass a global asciidoc configuration

[Thomas De Schampheleire]

On Sat, Sep 27, 2014 at 12:16 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Currently, a document can specify an output-specific configuration, like
> the text output, that hides images references, and formats hyperlinks.
>
> But sometime it is required that a specific configuration is used for

sometimes

> all the output formats, to always apply the same markup rules in all
> documents (like using the [specialwords] section.)
>
> Also look for a file named 'asciidoc.conf' in the document's directory.
> If that file exists, add it to the asciidoc options (before the
> output-specific config, so the former takes precedence over the latter.)
>
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> Cc: Samuel Martin <s.martin49@gmail.com>
> Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>

Aside from the above commit message change + the commit message change
indicated by Samuel:

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

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

[Yann E. MORIN]

As suggested by Thomas: the AsciiDoc options we use ensure we get a sane
output of the document. We want that configuration to be applied to
other documents as well.

Up until now, it was implicit that the configuration was applied to
our manual, becasue we only supported document-specific configuration,
and the configuration we had was in our manual dir, so we got to use it.

But now, we can render other documents, especially ones from
br2-external, and we want those to also use the default configuration
from Buildroot, but still be able to provide their own customisation.

So, always add Buildroot's configuration first, if available, before we
append the document's configuration.

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
---
 docs/{manual => conf}/asciidoc-text.conf |  0
 package/doc-asciidoc.mk                  | 12 ++++++++++++
 2 files changed, 12 insertions(+)
 rename docs/{manual => conf}/asciidoc-text.conf (100%)

diff --git a/docs/manual/asciidoc-text.conf b/docs/conf/asciidoc-text.conf
similarity index 100%
rename from docs/manual/asciidoc-text.conf
rename to docs/conf/asciidoc-text.conf
diff --git a/package/doc-asciidoc.mk b/package/doc-asciidoc.mk
index f949733..6185982 100644
--- a/package/doc-asciidoc.mk
+++ b/package/doc-asciidoc.mk
@@ -60,10 +60,21 @@ asciidoc-check-dependencies-$(5):
 $(1)-check-dependencies-$(5): asciidoc-check-dependencies-$(5)
 	$$(Q)$$(foreach hook,$$($(2)_CHECK_DEPENDENCIES_$(call UPPERCASE,$(5))_HOOKS),$$(call $$(hook))$$(sep))
 
+# Include output-specific Asciidoc configuration: first, Buildroot's
+# configuration, then the document's configuration
+ifneq ($$(wildcard $$($(2)_ASCIIDOC_BR_CONF)),)
+$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_ASCIIDOC_BR_CONF)
+endif
 ifneq ($$(wildcard $$($(2)_ASCIIDOC_CONF)),)
 $(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_ASCIIDOC_CONF)
 endif
 
+# Include output-specific Asciidoc configuration: first, Buildroot's
+# configuration, then the document's configuration
+$(2)_$(4)_ASCIIDOC_BR_CONF = docs/conf/asciidoc-$(4).conf
+ifneq ($$(wildcard $$($(2)_$(4)_ASCIIDOC_BR_CONF)),)
+$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_$(4)_ASCIIDOC_BR_CONF)
+endif
 $(2)_$(4)_ASCIIDOC_CONF = $(3)/asciidoc-$(4).conf
 ifneq ($$(wildcard $$($(2)_$(4)_ASCIIDOC_CONF)),)
 $(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_$(4)_ASCIIDOC_CONF)
@@ -136,6 +147,7 @@ $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced:
 
 $(1)-prepare-sources: $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced
 
+$(2)_ASCIIDOC_BR_CONF = docs/conf/asciidoc.conf
 $(2)_ASCIIDOC_CONF = $(3)/asciidoc.conf
 
 $(call ASCIIDOC_INNER,$(1),$(2),$(3),xhtml,html,html,HTML,\
-- 
1.9.1

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

[Samuel Martin]

Yann,

On Sat, Sep 27, 2014 at 12:16 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> As suggested by Thomas: the AsciiDoc options we use ensure we get a sane
> output of the document. We want that configuration to be applied to
> other documents as well.
>
> Up until now, it was implicit that the configuration was applied to
> our manual, becasue we only supported document-specific configuration,
> and the configuration we had was in our manual dir, so we got to use it.
>
> But now, we can render other documents, especially ones from
> br2-external, and we want those to also use the default configuration
> from Buildroot, but still be able to provide their own customisation.
>
> So, always add Buildroot's configuration first, if available, before we
> append the document's configuration.
>
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> Cc: Samuel Martin <s.martin49@gmail.com>
> Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
> ---
>  docs/{manual => conf}/asciidoc-text.conf |  0
>  package/doc-asciidoc.mk                  | 12 ++++++++++++
>  2 files changed, 12 insertions(+)
>  rename docs/{manual => conf}/asciidoc-text.conf (100%)
>
> diff --git a/docs/manual/asciidoc-text.conf b/docs/conf/asciidoc-text.conf
> similarity index 100%
> rename from docs/manual/asciidoc-text.conf
> rename to docs/conf/asciidoc-text.conf
> diff --git a/package/doc-asciidoc.mk b/package/doc-asciidoc.mk
> index f949733..6185982 100644
> --- a/package/doc-asciidoc.mk
> +++ b/package/doc-asciidoc.mk
> @@ -60,10 +60,21 @@ asciidoc-check-dependencies-$(5):
>  $(1)-check-dependencies-$(5): asciidoc-check-dependencies-$(5)
>         $$(Q)$$(foreach hook,$$($(2)_CHECK_DEPENDENCIES_$(call UPPERCASE,$(5))_HOOKS),$$(call $$(hook))$$(sep))
>
> +# Include output-specific Asciidoc configuration: first, Buildroot's
> +# configuration, then the document's configuration
> +ifneq ($$(wildcard $$($(2)_ASCIIDOC_BR_CONF)),)
> +$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_ASCIIDOC_BR_CONF)
> +endif
>  ifneq ($$(wildcard $$($(2)_ASCIIDOC_CONF)),)
>  $(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_ASCIIDOC_CONF)
>  endif
>
> +# Include output-specific Asciidoc configuration: first, Buildroot's
> +# configuration, then the document's configuration
> +$(2)_$(4)_ASCIIDOC_BR_CONF = docs/conf/asciidoc-$(4).conf
> +ifneq ($$(wildcard $$($(2)_$(4)_ASCIIDOC_BR_CONF)),)
> +$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_$(4)_ASCIIDOC_BR_CONF)
> +endif
>  $(2)_$(4)_ASCIIDOC_CONF = $(3)/asciidoc-$(4).conf
>  ifneq ($$(wildcard $$($(2)_$(4)_ASCIIDOC_CONF)),)
>  $(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_$(4)_ASCIIDOC_CONF)
> @@ -136,6 +147,7 @@ $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced:
>
>  $(1)-prepare-sources: $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced
>
> +$(2)_ASCIIDOC_BR_CONF = docs/conf/asciidoc.conf
>  $(2)_ASCIIDOC_CONF = $(3)/asciidoc.conf

It's a bit odd to have *_ASCIIDOC{,_BR}_CONF definitions after using
them, whereas teh output-specific config file is defined just before
using it.
Anyway, it has no impact on the behavior of the infra, so:

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

-- 
Samuel

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

[Yann E. MORIN]

Samuel, All,

On 2014-09-27 13:21 +0200, Samuel Martin spake thusly:
> On Sat, Sep 27, 2014 at 12:16 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
[--SNIP--]
> > +# Include output-specific Asciidoc configuration: first, Buildroot's
> > +# configuration, then the document's configuration
> > +ifneq ($$(wildcard $$($(2)_ASCIIDOC_BR_CONF)),)
> > +$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_ASCIIDOC_BR_CONF)
> > +endif
> >  ifneq ($$(wildcard $$($(2)_ASCIIDOC_CONF)),)
> >  $(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_ASCIIDOC_CONF)
> >  endif
> >
> > +# Include output-specific Asciidoc configuration: first, Buildroot's
> > +# configuration, then the document's configuration
> > +$(2)_$(4)_ASCIIDOC_BR_CONF = docs/conf/asciidoc-$(4).conf
> > +ifneq ($$(wildcard $$($(2)_$(4)_ASCIIDOC_BR_CONF)),)
> > +$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_$(4)_ASCIIDOC_BR_CONF)
> > +endif
> >  $(2)_$(4)_ASCIIDOC_CONF = $(3)/asciidoc-$(4).conf
> >  ifneq ($$(wildcard $$($(2)_$(4)_ASCIIDOC_CONF)),)
> >  $(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_$(4)_ASCIIDOC_CONF)
> > @@ -136,6 +147,7 @@ $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced:
> >
> >  $(1)-prepare-sources: $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced
> >
> > +$(2)_ASCIIDOC_BR_CONF = docs/conf/asciidoc.conf
> >  $(2)_ASCIIDOC_CONF = $(3)/asciidoc.conf
> 
> It's a bit odd to have *_ASCIIDOC{,_BR}_CONF definitions after using
> them, whereas teh output-specific config file is defined just before
> using it.

That's because the definitions of $(2)_ASCIIDOC_CONF and $(2)_ASCIIDOC_BR_CONF
are common to all of that document, so we define them in ASCIIDOC, not
_INNER, or they'd be redefined every time _INNER is expanded.

OTOH, the $(2)_$(4)_ASCIIDOC_CONF and $(2)_$(4)_ASCIIDOC_BR_CONF are
different for each output type, so they only get defined in _INNER.

> Anyway, it has no impact on the behavior of the infra, so:

No impact on the behaviour, indeed, but no need to redefine the same
variable to the same value over-and-over again (well, just 5 times, but
still.)

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

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 22/25 v6] doc/asciidoc: always apply Buildroot's AsciiDoc config

[Thomas De Schampheleire]

Hi Yann,

On Sat, Sep 27, 2014 at 12:16 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> As suggested by Thomas: the AsciiDoc options we use ensure we get a sane
> output of the document. We want that configuration to be applied to
> other documents as well.
>
> Up until now, it was implicit that the configuration was applied to
> our manual, becasue we only supported document-specific configuration,
> and the configuration we had was in our manual dir, so we got to use it.
>
> But now, we can render other documents, especially ones from
> br2-external, and we want those to also use the default configuration
> from Buildroot, but still be able to provide their own customisation.
>
> So, always add Buildroot's configuration first, if available, before we
> append the document's configuration.
>
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> Cc: Samuel Martin <s.martin49@gmail.com>
> Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
> ---
>  docs/{manual => conf}/asciidoc-text.conf |  0
>  package/doc-asciidoc.mk                  | 12 ++++++++++++
>  2 files changed, 12 insertions(+)
>  rename docs/{manual => conf}/asciidoc-text.conf (100%)
>
> diff --git a/docs/manual/asciidoc-text.conf b/docs/conf/asciidoc-text.conf
> similarity index 100%
> rename from docs/manual/asciidoc-text.conf
> rename to docs/conf/asciidoc-text.conf
> diff --git a/package/doc-asciidoc.mk b/package/doc-asciidoc.mk
> index f949733..6185982 100644
> --- a/package/doc-asciidoc.mk
> +++ b/package/doc-asciidoc.mk
> @@ -60,10 +60,21 @@ asciidoc-check-dependencies-$(5):
>  $(1)-check-dependencies-$(5): asciidoc-check-dependencies-$(5)
>         $$(Q)$$(foreach hook,$$($(2)_CHECK_DEPENDENCIES_$(call UPPERCASE,$(5))_HOOKS),$$(call $$(hook))$$(sep))
>
> +# Include output-specific Asciidoc configuration: first, Buildroot's
> +# configuration, then the document's configuration
> +ifneq ($$(wildcard $$($(2)_ASCIIDOC_BR_CONF)),)
> +$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_ASCIIDOC_BR_CONF)
> +endif
>  ifneq ($$(wildcard $$($(2)_ASCIIDOC_CONF)),)
>  $(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_ASCIIDOC_CONF)
>  endif
>
> +# Include output-specific Asciidoc configuration: first, Buildroot's
> +# configuration, then the document's configuration
> +$(2)_$(4)_ASCIIDOC_BR_CONF = docs/conf/asciidoc-$(4).conf
> +ifneq ($$(wildcard $$($(2)_$(4)_ASCIIDOC_BR_CONF)),)
> +$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_$(4)_ASCIIDOC_BR_CONF)
> +endif

The above two snippets almost are the same and at first I thought this
was a merge/rebase issue.
In fact, one of the comments should change.

Moreover, I have been staring at this patch for several minutes to
verify if I misunderstood something. The confusing thing is that
variable $(2)_ASCIIDOC_BR_CONF, which can expand to
MANUAL_ASCIIDOC_BR_CONF or SOMEDOC_ASCIIDOC_BR_CONF will both contain
the same common value docs/conf/asciidoc.conf, while the name of the
variable suggests that it is document-specific.

Strictly speaking, you have following levels:

- buildroot conf for all formats
- buildroot conf for a specific format
- <doc> conf for all formats
- <doc> conf for a specific format

Currently, the variables mapped on this are (respectively)

$(2)_ASCIIDOC_BR_CONF
$(2)_$(4)_ASCIIDOC_BR_CONF
$(2)_ASCIIDOC_CONF
$(2)_$(4)_ASCIIDOC_CONF

while I would find it more logical to have:

BR_ASCIIDOC_CONF
BR_$(4)_ASCIIDOC_CONF
$(2)_ASCIIDOC_CONF
$(2)_$(4)_ASCIIDOC_CONF


Best regards,
Thomas

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

[Yann E. MORIN]

Thomas, All,

On 2014-10-02 12:17 +0200, Thomas De Schampheleire spake thusly:
> On Sat, Sep 27, 2014 at 12:16 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> > As suggested by Thomas: the AsciiDoc options we use ensure we get a sane
> > output of the document. We want that configuration to be applied to
> > other documents as well.
[--SNIP--]
> > +# Include output-specific Asciidoc configuration: first, Buildroot's
> > +# configuration, then the document's configuration
> > +ifneq ($$(wildcard $$($(2)_ASCIIDOC_BR_CONF)),)
> > +$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_ASCIIDOC_BR_CONF)
> > +endif
> >  ifneq ($$(wildcard $$($(2)_ASCIIDOC_CONF)),)
> >  $(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_ASCIIDOC_CONF)
> >  endif
> >
> > +# Include output-specific Asciidoc configuration: first, Buildroot's
> > +# configuration, then the document's configuration
> > +$(2)_$(4)_ASCIIDOC_BR_CONF = docs/conf/asciidoc-$(4).conf
> > +ifneq ($$(wildcard $$($(2)_$(4)_ASCIIDOC_BR_CONF)),)
> > +$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_$(4)_ASCIIDOC_BR_CONF)
> > +endif
> 
> The above two snippets almost are the same and at first I thought this
> was a merge/rebase issue.
> In fact, one of the comments should change.

Yup, 'output-specifc' is superfluous in first comment.

> Moreover, I have been staring at this patch for several minutes to
> verify if I misunderstood something. The confusing thing is that
> variable $(2)_ASCIIDOC_BR_CONF, which can expand to
> MANUAL_ASCIIDOC_BR_CONF or SOMEDOC_ASCIIDOC_BR_CONF will both contain
> the same common value docs/conf/asciidoc.conf, while the name of the
> variable suggests that it is document-specific.
> 
> Strictly speaking, you have following levels:
> 
> - buildroot conf for all formats
> - buildroot conf for a specific format
> - <doc> conf for all formats
> - <doc> conf for a specific format
> 
> Currently, the variables mapped on this are (respectively)
> 
> $(2)_ASCIIDOC_BR_CONF
> $(2)_$(4)_ASCIIDOC_BR_CONF
> $(2)_ASCIIDOC_CONF
> $(2)_$(4)_ASCIIDOC_CONF
> 
> while I would find it more logical to have:
> 
> BR_ASCIIDOC_CONF
> BR_$(4)_ASCIIDOC_CONF
> $(2)_ASCIIDOC_CONF
> $(2)_$(4)_ASCIIDOC_CONF

I've reworked that patch to account for your comments, and include the
configuration filers in the order you suggest above.

It is indeed much better. Thank you!

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  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/25 v6] doc/asciidoc: always use UTC

[Yann E. MORIN]

Currently, the manual is rendered with the timezone of the user running
the rendering. This timezone can fluctuate, depending on the date, due
to DST (Daylight Saving Time). Currently, the manual is rendered in
either CET or CEST (Central European Time, or its DST variant.)

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

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

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
---
 package/doc-asciidoc.mk | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/package/doc-asciidoc.mk b/package/doc-asciidoc.mk
index 6185982..04c6299 100644
--- a/package/doc-asciidoc.mk
+++ b/package/doc-asciidoc.mk
@@ -93,6 +93,8 @@ define $(2)_$(4)_INSTALL_CMDS
 endef
 endif
 
+$$(O)/docs/$(1)/$(1).$(6): export TZ=UTC
+
 ifeq ($(6)-$$(GENDOC_XSLTPROC_IS_BROKEN),pdf-y)
 $$(O)/docs/$(1)/$(1).$(6):
 	$$(warning PDF generation is disabled because of a bug in \
-- 
1.9.1

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

[Thomas De Schampheleire]

On Sat, Sep 27, 2014 at 12:16 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Currently, the manual is rendered with the timezone of the user running
> the rendering. This timezone can fluctuate, depending on the date, due
> to DST (Daylight Saving Time). Currently, the manual is rendered in
> either CET or CEST (Central European Time, or its DST variant.)
>
> So, a manual rendered during the summer or the winter would refer to a
> non-constant timezone. If the machine and/or user doing the rendering
> also changes, there is no guarantee the timezone would still be CET/CEST.
> This is not a hard issue, since the user can still deduce the time in
> UTC, but is just incoherent.
>
> Just force the timezone to be UTC when doing the rendering of the
> manual, so we are not dependent on the machine or user doign the

doing

> rendering.
>
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> Cc: Samuel Martin <s.martin49@gmail.com>
> Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
> ---
>  package/doc-asciidoc.mk | 2 ++
>  1 file changed, 2 insertions(+)
>
> diff --git a/package/doc-asciidoc.mk b/package/doc-asciidoc.mk
> index 6185982..04c6299 100644
> --- a/package/doc-asciidoc.mk
> +++ b/package/doc-asciidoc.mk
> @@ -93,6 +93,8 @@ define $(2)_$(4)_INSTALL_CMDS
>  endef
>  endif
>
> +$$(O)/docs/$(1)/$(1).$(6): export TZ=UTC
> +
>  ifeq ($(6)-$$(GENDOC_XSLTPROC_IS_BROKEN),pdf-y)
>  $$(O)/docs/$(1)/$(1).$(6):
>         $$(warning PDF generation is disabled because of a bug in \
> --
> 1.9.1
>

Although I don't mind such a change, I fail to understand the use case
here. Is this only regarding the printed date at the beginning of the
manual?

With the typo in the commit msg fixed:

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

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

[Yann E. MORIN]

Thomas, All,

On 2014-10-02 12:21 +0200, Thomas De Schampheleire spake thusly:
> On Sat, Sep 27, 2014 at 12:16 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
[--SNIP--]
> > Just force the timezone to be UTC when doing the rendering of the
> > manual, so we are not dependent on the machine or user doign the
> 
> doing

Fixed.

> > rendering.
> >
> > Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> > Cc: Samuel Martin <s.martin49@gmail.com>
> > Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
> > ---
> >  package/doc-asciidoc.mk | 2 ++
> >  1 file changed, 2 insertions(+)
> >
> > diff --git a/package/doc-asciidoc.mk b/package/doc-asciidoc.mk
> > index 6185982..04c6299 100644
> > --- a/package/doc-asciidoc.mk
> > +++ b/package/doc-asciidoc.mk
> > @@ -93,6 +93,8 @@ define $(2)_$(4)_INSTALL_CMDS
> >  endef
> >  endif
> >
> > +$$(O)/docs/$(1)/$(1).$(6): export TZ=UTC
> > +
> >  ifeq ($(6)-$$(GENDOC_XSLTPROC_IS_BROKEN),pdf-y)
> >  $$(O)/docs/$(1)/$(1).$(6):
> >         $$(warning PDF generation is disabled because of a bug in \
> > --
> > 1.9.1
> >
> 
> Although I don't mind such a change, I fail to understand the use case
> here. Is this only regarding the printed date at the beginning of the
> manual?

Yes, that's about that. What bothers me is potential for inconsistency.
Also, for something that is world-readable, I usually prefer to read
dates that are not tainted by any local, user-specific timezone. UTC is
a the reference time, so I believe it is better lookign to see UTC than
any other timezone.

Indeed, it's just a trivial (as in: not important) change.

Thanks! :-)

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  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 24/25 v6] Makefile: enable generating documents from br2-external

[Yann E. MORIN]

Currently, the only way br2-external may generate a document is by
including that document's recipe from within external.mk.

But external.mk is only parsed when the tree is configured.

This is unlike our internal document (the manual) which can be generated
from within an unconfigured tree.

So, include the documents from br2-external at the same time we include
our own document:
  - expect the same layout as we have:      docs/DOC_NAME/doc-name.mk
  - do not fail if there is no document:    use "-include", not "include"

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

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

[Buildroot] [PATCH 25/25 v6] 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>

---
Chamges v5 -> v6:
  - fix names of hooks
  - remove trailing spaces
---
 docs/manual/adding-packages-asciidoc.txt | 119 +++++++++++++++++++++++++++++++
 docs/manual/adding-packages.txt          |   2 +
 2 files changed, 121 insertions(+)
 create mode 100644 docs/manual/adding-packages-asciidoc.txt

diff --git a/docs/manual/adding-packages-asciidoc.txt b/docs/manual/adding-packages-asciidoc.txt
new file mode 100644
index 0000000..8d6b282
--- /dev/null
+++ b/docs/manual/adding-packages-asciidoc.txt
@@ -0,0 +1,119 @@
+// -*- mode:doc; -*-
+// vim: syntax=asciidoc
+
+=== Infrastructure for asciidoc documents
+
+[[asciidoc-documents-tutorial]]
+
+The Buildroot manual, which you are currently reading, is entirely written
+using the http://asciidoc.org/[AsciiDoc] mark-up syntax. The manual is then
+rendered to many formats:
+
+* html
+* split-html
+* pdf
+* epub
+* text
+
+Although Buildroot only contains one document written in AsciiDoc, there
+is, as for packages, an infrastructure for rendering documents using the
+AsciiDoc syntax.
+
+Also as for packages, the AsciiDoc infrastructure is available from
+xref:outside-br-custom[BR2_EXTERNAL]. This allows documentation for a
+BR2_EXTERNAL tree to match the Buildroot documentation, as it will be
+rendered to the same formats and use the same layout and theme.
+
+==== +asciidoc-document+ tutorial
+
+Whereas package infrastructures are suffixed with +-package+, the document
+infrastructures are suffixed with +-document+. So, the AsciiDoc infrastructure
+is named +asciidoc-document+.
+
+Here is an example to render a simple AsciiDoc document.
+
+----
+01: ################################################################################
+02: #
+03: # foo-document
+04: #
+05: ################################################################################
+06:
+07: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*))
+08: $(eval $(call asciidoc-document))
+----
+
+On line 7, the Makefile declares what the sources of the document are.
+Currently, it is expected that the document's sources are only local;
+Buildroot will not attempt to download anything to render a document.
+Thus, you must indicate where the sources are. Usually, the string
+above is sufficient for a document with no sub-directory structure.
+
+Finally, on line 8, we call the +asciidoc-document+ function, which
+generates all the Makefile code necessary to render the document.
+
+==== +asciidoc-document+ reference
+
+The list of variables that can be set in a +.mk+ file to give metadata
+information is (assuming the document name is +foo+) :
+
+* +FOO_SOURCES+, mandatory, defines the source files for the document.
+
+* +FOO_RESOURCES+, optional, may contain a space-separated list of paths
+  to one or more directories containing so-called resources (CSS,
+  images...) By default, empty.
+
+There are also additional hooks (see xref:hooks[] for general information
+on hooks), that a document may set to define extra actions to be done at
+various steps:
+
+* +FOO_POST_RSYNC_HOOKS+ to run additional commands after the sources
+  have been copied by Buildroot. This can be used for, for example,
+  generating part of the manual with information extracted from the
+  tree. As an example, Buildroot uses this hook to generate the tables
+  in the appendices.
+
+* +FOO_CHECK_DEPENDENCIES_HOOKS+ to run additional tests on required
+  components to generate the document. In AsciiDoc, it is possible to
+  call filters, that is, programs that will parse an AsciiDoc block and
+  render it appropriately (e.g. http://ditaa.sourceforge.net/[ditaa] or
+  https://pythonhosted.org/aafigure/[aafigure].)
+
+* +FOO_CHECK_DEPENDENCIES_<FMT>_HOOKS+, to run additional tests for
+  the specified format +<FMT>+ (see the list of rendered formats, above.)
+
+Here is a complete example that uses all variables and all hooks:
+
+----
+01: ################################################################################
+02: #
+03: # foo-document
+04: #
+05: ################################################################################
+06:
+07: FOO_SOURCES = $(sort $(widcard $(pkgdir)/*))
+08: FOO_RESOURCES = $(sort $(wildcard $(pkgdir)/ressources))
+09:
+10: define FOO_GEN_EXTRA_DOC
+11:     /path/to/generate-script --outdir=$(@D)
+12: endef
+13: FOO_POST_RSYNC_HOOKS += FOO_GEN_EXTRA_DOC
+14:
+15: define FOO_CHECK_MY_PROG
+16:     if ! which my-prog >/dev/null 2>&1; then \
+17:         echo "You need my-prog to generate the foo document"; \
+18:         exit 1; \
+19:     fi
+20: endef
+21: FOO_CHECK_DEPENDENCIES_HOOKS += FOO_CHECK_MY_PROG
+22:
+23: define FOO_CHECK_MY_OTHER_PROG
+24:     if ! which my-other-prog >/dev/null 2>&1; then \
+25:         echo "You need my-other-prog to generate the foo document as PDF"; \
+26:         exit 1; \
+27:     fi
+28: endef
+29: FOO_CHECK_DEPENDENCIES_PDF_HOOKS += FOO_CHECK_MY_OTHER_PROG
+30:
+31: $(eval $(call asciidoc-document))
+----
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 25/25 v6] docs/manual: document the asciidoc infra

[Samuel Martin]

Yann,

On Sat, Sep 27, 2014 at 12:17 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>
>
> ---
> Chamges v5 -> v6:
>   - fix names of hooks
>   - remove trailing spaces
> ---
>  docs/manual/adding-packages-asciidoc.txt | 119 +++++++++++++++++++++++++++++++
>  docs/manual/adding-packages.txt          |   2 +
>  2 files changed, 121 insertions(+)
>  create mode 100644 docs/manual/adding-packages-asciidoc.txt
>
> diff --git a/docs/manual/adding-packages-asciidoc.txt b/docs/manual/adding-packages-asciidoc.txt
> new file mode 100644
> index 0000000..8d6b282
> --- /dev/null
> +++ b/docs/manual/adding-packages-asciidoc.txt
> @@ -0,0 +1,119 @@
> +// -*- mode:doc; -*-
> +// vim: syntax=asciidoc
> +
> +=== Infrastructure for asciidoc documents
> +
> +[[asciidoc-documents-tutorial]]
> +
> +The Buildroot manual, which you are currently reading, is entirely written
> +using the http://asciidoc.org/[AsciiDoc] mark-up syntax. The manual is then
> +rendered to many formats:
> +
> +* html
> +* split-html
> +* pdf
> +* epub
> +* text
> +
> +Although Buildroot only contains one document written in AsciiDoc, there
> +is, as for packages, an infrastructure for rendering documents using the
> +AsciiDoc syntax.
> +
> +Also as for packages, the AsciiDoc infrastructure is available from
> +xref:outside-br-custom[BR2_EXTERNAL]. This allows documentation for a
> +BR2_EXTERNAL tree to match the Buildroot documentation, as it will be
> +rendered to the same formats and use the same layout and theme.
> +
> +==== +asciidoc-document+ tutorial
> +
> +Whereas package infrastructures are suffixed with +-package+, the document
> +infrastructures are suffixed with +-document+. So, the AsciiDoc infrastructure
> +is named +asciidoc-document+.
> +
> +Here is an example to render a simple AsciiDoc document.
> +
> +----
> +01: ################################################################################
> +02: #
> +03: # foo-document
> +04: #
> +05: ################################################################################
> +06:
> +07: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*))
> +08: $(eval $(call asciidoc-document))
> +----
> +
> +On line 7, the Makefile declares what the sources of the document are.
> +Currently, it is expected that the document's sources are only local;
> +Buildroot will not attempt to download anything to render a document.
> +Thus, you must indicate where the sources are. Usually, the string
> +above is sufficient for a document with no sub-directory structure.
> +
> +Finally, on line 8, we call the +asciidoc-document+ function, which
> +generates all the Makefile code necessary to render the document.
> +
> +==== +asciidoc-document+ reference
> +
> +The list of variables that can be set in a +.mk+ file to give metadata
> +information is (assuming the document name is +foo+) :
> +
> +* +FOO_SOURCES+, mandatory, defines the source files for the document.
> +
> +* +FOO_RESOURCES+, optional, may contain a space-separated list of paths
> +  to one or more directories containing so-called resources (CSS,
> +  images...) By default, empty.
> +
> +There are also additional hooks (see xref:hooks[] for general information
> +on hooks), that a document may set to define extra actions to be done at
> +various steps:
> +
> +* +FOO_POST_RSYNC_HOOKS+ to run additional commands after the sources
> +  have been copied by Buildroot. This can be used for, for example,
> +  generating part of the manual with information extracted from the
> +  tree. As an example, Buildroot uses this hook to generate the tables
> +  in the appendices.
> +
> +* +FOO_CHECK_DEPENDENCIES_HOOKS+ to run additional tests on required
> +  components to generate the document. In AsciiDoc, it is possible to
> +  call filters, that is, programs that will parse an AsciiDoc block and
> +  render it appropriately (e.g. http://ditaa.sourceforge.net/[ditaa] or
> +  https://pythonhosted.org/aafigure/[aafigure].)
> +
> +* +FOO_CHECK_DEPENDENCIES_<FMT>_HOOKS+, to run additional tests for
> +  the specified format +<FMT>+ (see the list of rendered formats, above.)
> +
> +Here is a complete example that uses all variables and all hooks:
> +
> +----
> +01: ################################################################################
> +02: #
> +03: # foo-document
> +04: #
> +05: ################################################################################
> +06:
> +07: FOO_SOURCES = $(sort $(widcard $(pkgdir)/*))

s/widcard/wildcard/

> +08: FOO_RESOURCES = $(sort $(wildcard $(pkgdir)/ressources))
> +09:
> +10: define FOO_GEN_EXTRA_DOC
> +11:     /path/to/generate-script --outdir=$(@D)
> +12: endef
> +13: FOO_POST_RSYNC_HOOKS += FOO_GEN_EXTRA_DOC
> +14:
> +15: define FOO_CHECK_MY_PROG
> +16:     if ! which my-prog >/dev/null 2>&1; then \
> +17:         echo "You need my-prog to generate the foo document"; \
> +18:         exit 1; \
> +19:     fi
> +20: endef
> +21: FOO_CHECK_DEPENDENCIES_HOOKS += FOO_CHECK_MY_PROG
> +22:
> +23: define FOO_CHECK_MY_OTHER_PROG
> +24:     if ! which my-other-prog >/dev/null 2>&1; then \
> +25:         echo "You need my-other-prog to generate the foo document as PDF"; \
> +26:         exit 1; \
> +27:     fi
> +28: endef
> +29: FOO_CHECK_DEPENDENCIES_PDF_HOOKS += FOO_CHECK_MY_OTHER_PROG
> +30:
> +31: $(eval $(call asciidoc-document))
> +----
> diff --git a/docs/manual/adding-packages.txt b/docs/manual/adding-packages.txt
> index 9c97128..feb0d13 100644
> --- a/docs/manual/adding-packages.txt
> +++ b/docs/manual/adding-packages.txt
> @@ -27,6 +27,8 @@ include::adding-packages-virtual.txt[]
>
>  include::adding-packages-kconfig.txt[]
>
> +include::adding-packages-asciidoc.txt[]
> +
>  include::adding-packages-hooks.txt[]
>
>  include::adding-packages-gettext.txt[]
> --
> 1.9.1
>

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

Regards,

-- 
Samuel

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

[Yann E. MORIN]

Samuel, All,

On 2014-09-27 13:21 +0200, Samuel Martin spake thusly:
> On Sat, Sep 27, 2014 at 12:17 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
[--SNIP--]
> > +01: ################################################################################
> > +02: #
> > +03: # foo-document
> > +04: #
> > +05: ################################################################################
> > +06:
> > +07: FOO_SOURCES = $(sort $(widcard $(pkgdir)/*))
> 
> s/widcard/wildcard/

Gah... I fixed the other one Thomas pointed out in the previous review,
and did not even think of looking if I borked that one too... :-/

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

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 25/25 v6] docs/manual: document the asciidoc infra

[Thomas De Schampheleire]

Hi Yann,

On Sat, Sep 27, 2014 at 12:17 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>
>
> ---
> Chamges v5 -> v6:
>   - fix names of hooks
>   - remove trailing spaces
> ---

Found some other comments below:

>  docs/manual/adding-packages-asciidoc.txt | 119 +++++++++++++++++++++++++++++++
>  docs/manual/adding-packages.txt          |   2 +
>  2 files changed, 121 insertions(+)
>  create mode 100644 docs/manual/adding-packages-asciidoc.txt
>
> diff --git a/docs/manual/adding-packages-asciidoc.txt b/docs/manual/adding-packages-asciidoc.txt
[..]
> +
> +==== +asciidoc-document+ tutorial
> +
> +Whereas package infrastructures are suffixed with +-package+, the document
> +infrastructures are suffixed with +-document+. So, the AsciiDoc infrastructure
> +is named +asciidoc-document+.
> +
> +Here is an example to render a simple AsciiDoc document.
> +
> +----
> +01: ################################################################################
> +02: #
> +03: # foo-document
> +04: #
> +05: ################################################################################
> +06:
> +07: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*))
> +08: $(eval $(call asciidoc-document))
> +----
> +
> +On line 7, the Makefile declares what the sources of the document are.
> +Currently, it is expected that the document's sources are only local;
> +Buildroot will not attempt to download anything to render a document.
> +Thus, you must indicate where the sources are. Usually, the string
> +above is sufficient for a document with no sub-directory structure.
> +
> +Finally, on line 8, we call the +asciidoc-document+ function, which
> +generates all the Makefile code necessary to render the document.

'Finally' is a bit an exaggeration here, as there was only one
described line above it :)

> +
> +==== +asciidoc-document+ reference
> +
> +The list of variables that can be set in a +.mk+ file to give metadata
> +information is (assuming the document name is +foo+) :
> +
> +* +FOO_SOURCES+, mandatory, defines the source files for the document.
> +
> +* +FOO_RESOURCES+, optional, may contain a space-separated list of paths
> +  to one or more directories containing so-called resources (CSS,
> +  images...) By default, empty.

Shouldn't there be a dot after the closing parentheses, to finish the sentence?

> +
> +There are also additional hooks (see xref:hooks[] for general information
> +on hooks), that a document may set to define extra actions to be done at
> +various steps:
> +
> +* +FOO_POST_RSYNC_HOOKS+ to run additional commands after the sources
> +  have been copied by Buildroot. This can be used for, for example,
> +  generating part of the manual with information extracted from the

I would write:
This can for example be used for ...

Best regards,
Thomas

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

[Yann E. MORIN]

Thomas, All,

On 2014-10-02 12:27 +0200, Thomas De Schampheleire spake thusly:
[--SNIP--]
> > +Finally, on line 8, we call the +asciidoc-document+ function, which
> > +generates all the Makefile code necessary to render the document.
> 
> 'Finally' is a bit an exaggeration here, as there was only one
> described line above it :)

I just mimicked what was done in the other package infras, to get as
consistent as possible. I'll rephrase.

> > +* +FOO_RESOURCES+, optional, may contain a space-separated list of paths
> > +  to one or more directories containing so-called resources (CSS,
> > +  images...) By default, empty.
> 
> Shouldn't there be a dot after the closing parentheses, to finish the sentence?

I was under the impression that a closing parenthses at the end of a
sentence would goble the punctuation mark.

So I checked a few on-line ressources.

It seems that (once not making it a rule), I was mislaid.

> > +There are also additional hooks (see xref:hooks[] for general information
> > +on hooks), that a document may set to define extra actions to be done at
> > +various steps:
> > +
> > +* +FOO_POST_RSYNC_HOOKS+ to run additional commands after the sources
> > +  have been copied by Buildroot. This can be used for, for example,
> > +  generating part of the manual with information extracted from the
> 
> I would write:
> This can for example be used for ...

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