manual generation: misc changes

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 <[email protected]>

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

docs/manual/make-tips.txt +1 -2

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

docs/manual/manual.mk +25 -1

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

docs/manual/manual.mk +4 -0

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

docs/manual/prerequisite.txt +3 -1

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

docs/manual/prerequisite.txt +1 -0

+** +dblatex+ (required for the pdf manual only)

support/dependencies/check-host-asciidoc.sh new file +26 -0

new file mode 100755
@@ -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

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

build the manual.

Signed-off-by Thomas De Schampheleire

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

Quoted 1 line

Quoted 1 line

Quoted 1 line

Quoted 1 line

"Thomas" == Thomas De Schampheleire <[email protected]> writes:

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 <[email protected]>

Dear Thomas De Schampheleire,

Quoted 1 line · Thomas De Schampheleire

The output extension and the generation messages refer to 'text', but

the make

Quoted 4 lines

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 <[email protected]>