| Message ID | 4285f37298bb4361de1ca8f82f42e37c4bc4d7d4.1410692670.git.yann.morin.1998@free.fr |
|---|---|
| State | Changes Requested |
| Headers | show |
On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote: > From: Samuel Martin <s.martin49@gmail.com> > > The PDF manual generation reaches the default xsltproc's template > recursion limit when processing the target package list; this makes the > PDF manual generation fail [1-3]. > > This limit can be raised with the '--maxvars' option. Unfortunately, > this option is not correctly handled in the latest xsltproc/libxslt > release (1.1.28), but this bug is already fixed in the libxslt > repository [4]. > > This patch disables the PDF manual generation (makes it fail with a > meaningful error message) when the xsltproc program found in the PATH > does not support the --maxvars option. > So, one can still generate the PDF manual if he/she extends PATH with > the location of a working xsltproc, by running: > > $ PATH=/path/to/custom-xsltproc/bin:${PATH} make manual-pdf > > [1] http://lists.busybox.net/pipermail/buildroot/2014-August/104390.html > [2] http://lists.busybox.net/pipermail/buildroot/2014-August/104418.html > [3] http://lists.busybox.net/pipermail/buildroot/2014-August/104421.html > [4] https://gitorious.org/libxslt/libxslt/commit/5af7ad745323004984287e48b42712e7305de35c > > Reported-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com> > Cc: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> > Signed-off-by: Samuel Martin <s.martin49@gmail.com> > [yann.morin.1998@free.fr: move the assignment block out of GENDOC_INNER, no > need to retest for each type of each document: it's always the same answer] > Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr> > --- > docs/manual/manual.mk | 28 +++++++++++++++++++++++++++- > 1 file changed, 27 insertions(+), 1 deletion(-) > > diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk > index 09d8b18..b5856b9 100644 > --- a/docs/manual/manual.mk > +++ b/docs/manual/manual.mk > @@ -41,6 +41,20 @@ manual-check-dependencies-lists: > exit 1; \ > fi > > +# PDF manual generation is broken because of a bug in xsltproc program provided > +# by libxslt <=1.1.28, which does not honor an option we need to set. > +# Fortunately, this bug is already fixed upstream: > +# https://gitorious.org/libxslt/libxslt/commit/5af7ad745323004984287e48b42712e7305de35c > +# > +# So, bail out when trying to build the pdf manual using a buggy version of the > +# xsltproc program. > +# > +# So, to overcome this issue and being able to build the pdf manual, you can > +# build xsltproc from it source repository, then run: > +# $ PATH=/path/to/custom-xsltproc/bin:${PATH} make manual > +MANUAL_XSLTPROC_IS_BROKEN = \ > + $(shell xsltproc --maxvars 0 >/dev/null 2>/dev/null || echo y) > + > ################################################################################ > # GENDOC_INNER -- generates the make targets needed to build a specific type of > # asciidoc documentation. > @@ -83,6 +97,14 @@ define MANUAL_$(2)_INSTALL_CMDS > endef > endif > > +ifeq ($(4)-$$(MANUAL_XSLTPROC_IS_BROKEN),pdf-y) > +$$(O)/docs/$(1)/$(1).$(4): > + $$(error PDF manual generation is disabled because of a bug in \ > + xsltproc. To be able to generate the PDF manual, you should \ > + build xsltproc from the libxslt sources >=1.1.29 and pass it \ > + to make through the command line: \ > + 'PATH=/path/to/custom-xsltproc/bin:$$$${PATH} make manual-pdf') I think this should be $(warning) instead of $(error), because if you run 'make manual' with a broken xsltproc, then the manual generation will stop at the pdf manual, even though the following manuals (text and ePUB) could have been built without issue.
Thomas, All, On 2014-09-19 22:00 +0200, Thomas De Schampheleire spake thusly: > On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote: > > From: Samuel Martin <s.martin49@gmail.com> > > > > The PDF manual generation reaches the default xsltproc's template > > recursion limit when processing the target package list; this makes the > > PDF manual generation fail [1-3]. [--SNIP--] > > ################################################################################ > > # GENDOC_INNER -- generates the make targets needed to build a specific type of > > # asciidoc documentation. > > @@ -83,6 +97,14 @@ define MANUAL_$(2)_INSTALL_CMDS > > endef > > endif > > > > +ifeq ($(4)-$$(MANUAL_XSLTPROC_IS_BROKEN),pdf-y) > > +$$(O)/docs/$(1)/$(1).$(4): > > + $$(error PDF manual generation is disabled because of a bug in \ > > + xsltproc. To be able to generate the PDF manual, you should \ > > + build xsltproc from the libxslt sources >=1.1.29 and pass it \ > > + to make through the command line: \ > > + 'PATH=/path/to/custom-xsltproc/bin:$$$${PATH} make manual-pdf') > > I think this should be $(warning) instead of $(error), because if you > run 'make manual' with a broken xsltproc, then the manual generation > will stop at the pdf manual, even though the following manuals (text > and ePUB) could have been built without issue. Yup, it always bothered me. But we can just skip it, indeed. Another point about this hunk: the indentation of $(error...) is wrong: it is not the commands of the rule. I.e. it is not interpreted by the shell for the $$(O)/docs/$(1)/$(1).$(4) rule, but really by make itself. So, we should probably have this instead: ifeq ($(4)-$$(MANUAL_XSLTPROC_IS_BROKEN),pdf-y) $$(error ........) $$(O)/docs/$(1)/$(1).$(4): else $$(O)/docs/$(1)/$(1).$(4): a2x .... endif Regards, Yann E. MORIN.
On Fri, Sep 19, 2014 at 10:15 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote: > Thomas, All, > > On 2014-09-19 22:00 +0200, Thomas De Schampheleire spake thusly: >> On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote: >> > From: Samuel Martin <s.martin49@gmail.com> >> > >> > The PDF manual generation reaches the default xsltproc's template >> > recursion limit when processing the target package list; this makes the >> > PDF manual generation fail [1-3]. > [--SNIP--] >> > ################################################################################ >> > # GENDOC_INNER -- generates the make targets needed to build a specific type of >> > # asciidoc documentation. >> > @@ -83,6 +97,14 @@ define MANUAL_$(2)_INSTALL_CMDS >> > endef >> > endif >> > >> > +ifeq ($(4)-$$(MANUAL_XSLTPROC_IS_BROKEN),pdf-y) >> > +$$(O)/docs/$(1)/$(1).$(4): >> > + $$(error PDF manual generation is disabled because of a bug in \ >> > + xsltproc. To be able to generate the PDF manual, you should \ >> > + build xsltproc from the libxslt sources >=1.1.29 and pass it \ >> > + to make through the command line: \ >> > + 'PATH=/path/to/custom-xsltproc/bin:$$$${PATH} make manual-pdf') >> >> I think this should be $(warning) instead of $(error), because if you >> run 'make manual' with a broken xsltproc, then the manual generation >> will stop at the pdf manual, even though the following manuals (text >> and ePUB) could have been built without issue. > > Yup, it always bothered me. But we can just skip it, indeed. > > Another point about this hunk: the indentation of $(error...) is wrong: > it is not the commands of the rule. I.e. it is not interpreted by the > shell for the $$(O)/docs/$(1)/$(1).$(4) rule, but really by make itself. > > So, we should probably have this instead: > > ifeq ($(4)-$$(MANUAL_XSLTPROC_IS_BROKEN),pdf-y) > $$(error ........) > $$(O)/docs/$(1)/$(1).$(4): > else > $$(O)/docs/$(1)/$(1).$(4): > a2x .... > endif Yes, but with $(warning) then... Best regards, Thomas
diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk index 09d8b18..b5856b9 100644 --- a/docs/manual/manual.mk +++ b/docs/manual/manual.mk @@ -41,6 +41,20 @@ manual-check-dependencies-lists: exit 1; \ fi +# PDF manual generation is broken because of a bug in xsltproc program provided +# by libxslt <=1.1.28, which does not honor an option we need to set. +# Fortunately, this bug is already fixed upstream: +# https://gitorious.org/libxslt/libxslt/commit/5af7ad745323004984287e48b42712e7305de35c +# +# So, bail out when trying to build the pdf manual using a buggy version of the +# xsltproc program. +# +# So, to overcome this issue and being able to build the pdf manual, you can +# build xsltproc from it source repository, then run: +# $ PATH=/path/to/custom-xsltproc/bin:${PATH} make manual +MANUAL_XSLTPROC_IS_BROKEN = \ + $(shell xsltproc --maxvars 0 >/dev/null 2>/dev/null || echo y) + ################################################################################ # GENDOC_INNER -- generates the make targets needed to build a specific type of # asciidoc documentation. @@ -83,6 +97,14 @@ define MANUAL_$(2)_INSTALL_CMDS endef endif +ifeq ($(4)-$$(MANUAL_XSLTPROC_IS_BROKEN),pdf-y) +$$(O)/docs/$(1)/$(1).$(4): + $$(error PDF manual generation is disabled because of a bug in \ + xsltproc. To be able to generate the PDF manual, you should \ + build xsltproc from the libxslt sources >=1.1.29 and pass it \ + to make through the command line: \ + 'PATH=/path/to/custom-xsltproc/bin:$$$${PATH} make manual-pdf') +else $$(O)/docs/$(1)/$(1).$(4): docs/$(1)/$(1).txt \ $$($$(call UPPERCASE,$(1))_SOURCES) \ manual-check-dependencies \ @@ -96,6 +118,7 @@ $$(O)/docs/$(1)/$(1).$(4): docs/$(1)/$(1).txt \ $$(BUILD_DIR)/$(1)/$(1).txt # install the generated manual $$(MANUAL_$(2)_INSTALL_CMDS) +endif endef ################################################################################ @@ -111,8 +134,11 @@ $(call GENDOC_INNER,$(pkgname),xhtml,html,html,HTML,\ --xsltproc-opts "--stringparam toc.section.depth 1") $(call GENDOC_INNER,$(pkgname),chunked,split-html,chunked,split HTML,\ --xsltproc-opts "--stringparam toc.section.depth 1") +# dblatex needs to pass the '--maxvars ...' option to xsltproc to prevent it +# from reaching the template recursion limit when processing the (long) target +# package table and bailing out. $(call GENDOC_INNER,$(pkgname),pdf,pdf,pdf,PDF,\ - --dblatex-opts "-P latex.output.revhistory=0") + --dblatex-opts "-P latex.output.revhistory=0 -x '--maxvars 100000'") $(call GENDOC_INNER,$(pkgname),text,text,text,text) $(call GENDOC_INNER,$(pkgname),epub,epub,epub,ePUB) clean: $(pkgname)-clean