[Buildroot] [PATCH 0 of 2 v2] manual generation: misc changes

[Buildroot] [PATCH 0 of 2 v2] manual generation: misc changes

[Thomas De Schampheleire]

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

---

 Makefile                                    |   4 +-
 docs/manual/make-tips.txt                   |   3 +-
 docs/manual/manual.mk                       |  32 ++++++++++++++++++++++++-
 docs/manual/prerequisite.txt                |   5 +++-
 support/dependencies/check-host-asciidoc.sh |  36 +++++++++++++++++++++++++++++
 5 files changed, 73 insertions(+), 7 deletions(-)

[Buildroot] [PATCH 1 of 2 v2] manual generation: check dependencies first

[Thomas De Schampheleire]

To generate the manual, you need a few tools. If these are not present,
pretty cryptic error messages are given.
This patch adds a simple check for these dependencies, before attempting to
build the manual.

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

---
v2:
- update manual with the list of tools (comment Ryan)
- add check for dblatex and python-argparse (comment Samuel)
- check minimal version of asciidoc, using suitable-host-package mechanism

 docs/manual/make-tips.txt                   |   3 +--
 docs/manual/manual.mk                       |  30 +++++++++++++++++++++++++++++-
 docs/manual/prerequisite.txt                |   5 ++++-
 support/dependencies/check-host-asciidoc.sh |  36 ++++++++++++++++++++++++++++++++++++
 4 files changed, 70 insertions(+), 4 deletions(-)

diff --git a/docs/manual/make-tips.txt b/docs/manual/make-tips.txt
--- a/docs/manual/make-tips.txt
+++ b/docs/manual/make-tips.txt
@@ -66,9 +66,8 @@ To generate the manual:
 The manual outputs will be generated in 'output/docs/manual'.
 
 .Notes
-- +asciidoc+ is required to build the documentation (see:
+- A few tools are required to build the documentation (see:
   xref:requirement-optional[]).
-- There is a known issue that you can't build it under Debian Squeeze.
 
 .Reseting Buildroot for a new target:
 
diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -1,8 +1,32 @@
-manual-update-lists:
+manual-update-lists: manual-check-dependencies-lists
 	$(Q)$(call MESSAGE,"Updating the manual lists...")
 	$(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(O)/docs/manual/.build \
 		$(TOPDIR)/support/scripts/gen-manual-lists.py
 
+manual-check-dependencies:
+	$(Q)if [ -z "$(call suitable-host-package,asciidoc,)" ]; then \
+		echo "You need a sufficiently recent asciidoc on your host" \
+			"to generate the manual"; \
+		exit 1; \
+	fi
+	$(Q)if [ -z "`which w3m 2>/dev/null`" ]; then \
+		echo "You need w3m on your host to generate the manual"; \
+		exit 1; \
+	fi
+
+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"; \
+		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
+
 ################################################################################
 # GENDOC -- generates the make targets needed to build a specific type of
 #           asciidoc documentation.
@@ -22,8 +46,12 @@ define GENDOC_INNER
 .PHONY: $(1)-$(3)
 $(1)-$(3): $$(O)/docs/$(1)/$(1).$(4)
 
+manual-check-dependencies-$(3):
+
 $$(O)/docs/$(1)/$(1).$(4): docs/$(1)/$(1).txt \
 			   $$($(call UPPERCASE,$(1))_SOURCES) \
+			   manual-check-dependencies \
+			   manual-check-dependencies-$(3) \
 			   manual-update-lists
 	$(Q)$(call MESSAGE,"Generating $(5) $(1)...")
 	$(Q)mkdir -p $$(@D)/.build
diff --git a/docs/manual/prerequisite.txt b/docs/manual/prerequisite.txt
--- a/docs/manual/prerequisite.txt
+++ b/docs/manual/prerequisite.txt
@@ -76,4 +76,7 @@ development context (further details: re
 ** The +jar+ tool
 
 * Documentation generation tools:
-** +asciidoc+
+** +asciidoc+, version 8.6.3 or higher
+** +w3m+
+** +python+ with the +argparse+ module (automatically present in 2.7+ and 3.2+)
+** +dblatex+ (required for the pdf manual only)
diff --git a/support/dependencies/check-host-asciidoc.sh b/support/dependencies/check-host-asciidoc.sh
new file mode 100755
--- /dev/null
+++ b/support/dependencies/check-host-asciidoc.sh
@@ -0,0 +1,36 @@
+#!/bin/sh
+
+candidate="$1" #ignored
+
+asciidoc=`which asciidoc`
+if [ ! -x "$asciidoc" ]; then
+	# echo nothing: no suitable asciidoc found
+	exit 1
+fi
+
+# Output of 'asciidoc --version' examples:
+# asciidoc 8.6.7
+version=`$asciidoc --version | cut -d\  -f2`
+major=`echo "$version" | cut -d. -f1`
+minor=`echo "$version" | cut -d. -f2`
+bugfix=`echo "$version" | cut -d. -f3`
+
+# To generate the manual, we need asciidoc >= 8.6.3
+major_min=8
+minor_min=6
+bugfix_min=3
+if [ $major -gt $major_min ]; then
+	echo $asciidoc
+else
+	if [ $major -eq $major_min -a $minor -ge $minor_min ]; then
+		echo $asciidoc
+	else
+		if [ $major -eq $major_min -a $minor -eq $minor_min \
+			-a $bugfix -ge $bugfix_min ]; then
+			echo $asciidoc
+		else
+			# echo nothing: no suitable asciidoc found
+			exit 1
+		fi
+	fi
+fi

[Buildroot] [PATCH 2 of 2 v2] manual generation: rename manual-txt into manual-text

[Thomas De Schampheleire]

The output extension and the generation messages refer to 'text', but the make
target was confusingly 'txt'. This patch changes the make target for
consistency.

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

---
v2: fix missing rename in Makefile (thanks ThomasP)

 Makefile              |  4 ++--
 docs/manual/manual.mk |  2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Makefile b/Makefile
--- a/Makefile
+++ b/Makefile
@@ -815,7 +815,7 @@ endif
 	@echo '  manual-html            - build manual in HTML'
 	@echo '  manual-split-html      - build manual in split HTML'
 	@echo '  manual-pdf             - build manual in PDF'
-	@echo '  manual-txt             - build manual in txt'
+	@echo '  manual-text            - build manual in text'
 	@echo '  manual-epub            - build manual in ePub'
 	@echo
 	@echo 'Miscellaneous:'
@@ -839,7 +839,7 @@ release: OUT=buildroot-$(BR2_VERSION)
 # documentation to the git output
 release:
 	git archive --format=tar --prefix=$(OUT)/ HEAD > $(OUT).tar
-	$(MAKE) O=$(OUT) manual-html manual-txt manual-pdf
+	$(MAKE) O=$(OUT) manual-html manual-text manual-pdf
 	tar rf $(OUT).tar $(OUT)
 	gzip -9 -c < $(OUT).tar > $(OUT).tar.gz
 	bzip2 -9 -c < $(OUT).tar > $(OUT).tar.bz2
diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -73,7 +73,7 @@ define GENDOC
 $(call GENDOC_INNER,$(1),xhtml,html,html,HTML,--xsltproc-opts "--stringparam toc.section.depth 4")
 $(call GENDOC_INNER,$(1),chunked,split-html,chunked,split HTML,--xsltproc-opts "--stringparam toc.section.depth 4")
 $(call GENDOC_INNER,$(1),pdf,pdf,pdf,PDF,--dblatex-opts "-P latex.output.revhistory=0")
-$(call GENDOC_INNER,$(1),text,txt,text,text)
+$(call GENDOC_INNER,$(1),text,text,text,text)
 $(call GENDOC_INNER,$(1),epub,epub,epub,ePUB)
 clean: $(1)-clean
 $(1)-clean:

[Buildroot] [PATCH 2 of 2 v2] manual generation: rename manual-txt into manual-text

[Thomas Petazzoni]

Dear Thomas De Schampheleire,

On Sat, 21 Sep 2013 13:06:54 +0200, Thomas De Schampheleire wrote:
> The output extension and the generation messages refer to 'text', but the make
> target was confusingly 'txt'. This patch changes the make target for
> consistency.
> 
> Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

Acked-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
-- 
Thomas Petazzoni, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com

[Buildroot] [PATCH 1 of 2 v2] manual generation: check dependencies first

[Samuel Martin]

2013/9/21 Thomas De Schampheleire <patrickdepinguin@gmail.com>

> To generate the manual, you need a few tools. If these are not present,
> pretty cryptic error messages are given.
> This patch adds a simple check for these dependencies, before attempting to
> build the manual.
>
> Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
>
Acked-by: Samuel Martin <s.martin49@gmail.com>


> ---
> v2:
> - update manual with the list of tools (comment Ryan)
> - add check for dblatex and python-argparse (comment Samuel)
> - check minimal version of asciidoc, using suitable-host-package mechanism
>
>  docs/manual/make-tips.txt                   |   3 +--
>  docs/manual/manual.mk                       |  30
> +++++++++++++++++++++++++++++-
>  docs/manual/prerequisite.txt                |   5 ++++-
>  support/dependencies/check-host-asciidoc.sh |  36
> ++++++++++++++++++++++++++++++++++++
>  4 files changed, 70 insertions(+), 4 deletions(-)
>
> diff --git a/docs/manual/make-tips.txt b/docs/manual/make-tips.txt
> --- a/docs/manual/make-tips.txt
> +++ b/docs/manual/make-tips.txt
> @@ -66,9 +66,8 @@ To generate the manual:
>  The manual outputs will be generated in 'output/docs/manual'.
>
>  .Notes
> -- +asciidoc+ is required to build the documentation (see:
> +- A few tools are required to build the documentation (see:
>    xref:requirement-optional[]).
> -- There is a known issue that you can't build it under Debian Squeeze.
>
>  .Reseting Buildroot for a new target:
>
> diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
> --- a/docs/manual/manual.mk
> +++ b/docs/manual/manual.mk
> @@ -1,8 +1,32 @@
> -manual-update-lists:
> +manual-update-lists: manual-check-dependencies-lists
>         $(Q)$(call MESSAGE,"Updating the manual lists...")
>         $(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(O)/docs/manual/.build \
>                 $(TOPDIR)/support/scripts/gen-manual-lists.py
>
> +manual-check-dependencies:
> +       $(Q)if [ -z "$(call suitable-host-package,asciidoc,)" ]; then \
> +               echo "You need a sufficiently recent asciidoc on your
> host" \
> +                       "to generate the manual"; \
> +               exit 1; \
> +       fi
> +       $(Q)if [ -z "`which w3m 2>/dev/null`" ]; then \
> +               echo "You need w3m on your host to generate the manual"; \
> +               exit 1; \
> +       fi
> +
> +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"; \
> +               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
> +
>
>  ################################################################################
>  # GENDOC -- generates the make targets needed to build a specific type of
>  #           asciidoc documentation.
> @@ -22,8 +46,12 @@ define GENDOC_INNER
>  .PHONY: $(1)-$(3)
>  $(1)-$(3): $$(O)/docs/$(1)/$(1).$(4)
>
> +manual-check-dependencies-$(3):
> +
>  $$(O)/docs/$(1)/$(1).$(4): docs/$(1)/$(1).txt \
>                            $$($(call UPPERCASE,$(1))_SOURCES) \
> +                          manual-check-dependencies \
> +                          manual-check-dependencies-$(3) \
>                            manual-update-lists
>         $(Q)$(call MESSAGE,"Generating $(5) $(1)...")
>         $(Q)mkdir -p $$(@D)/.build
> diff --git a/docs/manual/prerequisite.txt b/docs/manual/prerequisite.txt
> --- a/docs/manual/prerequisite.txt
> +++ b/docs/manual/prerequisite.txt
> @@ -76,4 +76,7 @@ development context (further details: re
>  ** The +jar+ tool
>
>  * Documentation generation tools:
> -** +asciidoc+
> +** +asciidoc+, version 8.6.3 or higher
> +** +w3m+
> +** +python+ with the +argparse+ module (automatically present in 2.7+ and
> 3.2+)
> +** +dblatex+ (required for the pdf manual only)
> diff --git a/support/dependencies/check-host-asciidoc.sh
> b/support/dependencies/check-host-asciidoc.sh
> new file mode 100755
> --- /dev/null
> +++ b/support/dependencies/check-host-asciidoc.sh
> @@ -0,0 +1,36 @@
> +#!/bin/sh
> +
> +candidate="$1" #ignored
> +
> +asciidoc=`which asciidoc`
> +if [ ! -x "$asciidoc" ]; then
> +       # echo nothing: no suitable asciidoc found
> +       exit 1
> +fi
> +
> +# Output of 'asciidoc --version' examples:
> +# asciidoc 8.6.7
> +version=`$asciidoc --version | cut -d\  -f2`
> +major=`echo "$version" | cut -d. -f1`
> +minor=`echo "$version" | cut -d. -f2`
> +bugfix=`echo "$version" | cut -d. -f3`
> +
> +# To generate the manual, we need asciidoc >= 8.6.3
> +major_min=8
> +minor_min=6
> +bugfix_min=3
> +if [ $major -gt $major_min ]; then
> +       echo $asciidoc
> +else
> +       if [ $major -eq $major_min -a $minor -ge $minor_min ]; then
> +               echo $asciidoc
> +       else
> +               if [ $major -eq $major_min -a $minor -eq $minor_min \
> +                       -a $bugfix -ge $bugfix_min ]; then
> +                       echo $asciidoc
> +               else
> +                       # echo nothing: no suitable asciidoc found
> +                       exit 1
> +               fi
> +       fi
> +fi
>


Regards,

-- 
Samuel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.busybox.net/pipermail/buildroot/attachments/20130922/2a930a7d/attachment.html>

[Buildroot] [PATCH 2 of 2 v2] manual generation: rename manual-txt into manual-text

[Samuel Martin]

2013/9/22 Thomas Petazzoni <thomas.petazzoni@free-electrons.com>

> Dear Thomas De Schampheleire,
>
> On Sat, 21 Sep 2013 13:06:54 +0200, Thomas De Schampheleire wrote:
> > The output extension and the generation messages refer to 'text', but
> the make
> > target was confusingly 'txt'. This patch changes the make target for
> > consistency.
> >
> > Signed-off-by: Thomas De Schampheleire <
> thomas.de.schampheleire at gmail.com>
>
> Acked-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
>
Acked-by: Samuel Martin <s.martin49@gmail.com>

Regards,

-- 
Samuel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.busybox.net/pipermail/buildroot/attachments/20130922/2490f151/attachment.html>

[Buildroot] [PATCH 1 of 2 v2] manual generation: check dependencies first

[Ryan Barnett]

Thomas De Schampheleire <patrickdepinguin@gmail.com> wrote on 09/21/2013 
06:06:53 AM:

> To generate the manual, you need a few tools. If these are not present,
> pretty cryptic error messages are given.
> This patch adds a simple check for these dependencies, before attempting 
to
> build the manual.
> 
> Signed-off-by: Thomas De Schampheleire 
<thomas.de.schampheleire@gmail.com>
> 
> ---
> v2:
> - update manual with the list of tools (comment Ryan)
> - add check for dblatex and python-argparse (comment Samuel)
> - check minimal version of asciidoc, using suitable-host-package 
mechanism
> 
Acked-by: Ryan Barnett <rjbarnet@rockwellcollins.com>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.busybox.net/pipermail/buildroot/attachments/20130923/e484f54b/attachment.html>

[Buildroot] [PATCH 1 of 2 v2] manual generation: check dependencies first

[Peter Korsgaard]

>>>>> "Thomas" == Thomas De Schampheleire <patrickdepinguin@gmail.com> writes:

 Thomas> To generate the manual, you need a few tools. If these are not present,
 Thomas> pretty cryptic error messages are given.
 Thomas> This patch adds a simple check for these dependencies, before attempting to
 Thomas> build the manual.

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

 Thomas> ---
 Thomas> v2:
 Thomas> - update manual with the list of tools (comment Ryan)
 Thomas> - add check for dblatex and python-argparse (comment Samuel)
 Thomas> - check minimal version of asciidoc, using suitable-host-package mechanism

 Thomas>  docs/manual/make-tips.txt                   |   3 +--
 Thomas>  docs/manual/manual.mk                       |  30 +++++++++++++++++++++++++++++-
 Thomas>  docs/manual/prerequisite.txt                |   5 ++++-
 Thomas>  support/dependencies/check-host-asciidoc.sh |  36 ++++++++++++++++++++++++++++++++++++
 Thomas>  4 files changed, 70 insertions(+), 4 deletions(-)

 Thomas> diff --git a/docs/manual/make-tips.txt b/docs/manual/make-tips.txt
 Thomas> --- a/docs/manual/make-tips.txt
 Thomas> +++ b/docs/manual/make-tips.txt
 Thomas> @@ -66,9 +66,8 @@ To generate the manual:
 Thomas>  The manual outputs will be generated in 'output/docs/manual'.
 
 Thomas>  .Notes
 Thomas> -- +asciidoc+ is required to build the documentation (see:
 Thomas> +- A few tools are required to build the documentation (see:
 Thomas>    xref:requirement-optional[]).
 Thomas> -- There is a known issue that you can't build it under Debian Squeeze.
 
 Thomas>  .Reseting Buildroot for a new target:
 
 Thomas> diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
 Thomas> --- a/docs/manual/manual.mk
 Thomas> +++ b/docs/manual/manual.mk
 Thomas> @@ -1,8 +1,32 @@
 Thomas> -manual-update-lists:
 Thomas> +manual-update-lists: manual-check-dependencies-lists
 Thomas>  	$(Q)$(call MESSAGE,"Updating the manual lists...")
 Thomas>  	$(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(O)/docs/manual/.build \
 Thomas>  		$(TOPDIR)/support/scripts/gen-manual-lists.py
 
 Thomas> +manual-check-dependencies:
 Thomas> +	$(Q)if [ -z "$(call suitable-host-package,asciidoc,)" ]; then \
 Thomas> +		echo "You need a sufficiently recent asciidoc on your host" \
 Thomas> +			"to generate the manual"; \
 Thomas> +		exit 1; \
 Thomas> +	fi

This breaks 'make release' as it is a noconfig_target, so we don't
include dependencies.mk for the suitable-host-package.

You don't really need to use suitable-host-package, perhaps you could
directly call check-host-asciidoc.sh instead?

-- 
Bye, Peter Korsgaard