Bug 593

Summary: bitbake manual fails to build
Product: [Documentation] Reference Reporter: Darren Hart <dvhart>
Component: handbookAssignee: Darren Hart <dvhart>
Status: RESOLVED FIXED QA Contact:
Severity: normal    
Priority: High CC: ke.yu, poky.doc.watcher, poky.watcher, richard.purdie, sgw
Version: 1.0   
Target Milestone: 1.0 PointRelease   
Hardware: x86   
OS: Multiple   
Whiteboard:
OS type for building Yocto: --- Type of Regression: ---
Verified: Documentation change: ---

Description Darren Hart 2010-12-14 11:02:21 UTC
This is for the bitbake manual, but there isn't an appropriate component.

$ make
XMLLINT ./usermanual.xml
XMLTO pdf ./usermanual.xml
Making portrait pages on letter paper (215.9mmx279.4mm)
make: *** [pdf] Error 1

dvhart@doubt:manual$ pwd
/home/dvhart/source/poky.git/bitbake/doc/manual
dvhart@doubt:manual$ tree
.
├── Makefile
├── html.css
├── pdf
└── usermanual.xml

1 directory, 3 files
Comment 1 Scott Rifenbark 2011-01-28 09:50:13 UTC
I need some time to investigate this bug.  I am getting the same error when I run Make on the manual.  The make file is not the same as for the YP documentation.  It is using xmltex tools.
Comment 2 Darren Hart 2011-03-09 11:37:24 UTC
Took a quick look and found that 'make txt' succeeds, 'make pdf' fails. Adding ps and dvi to the types in the Makefile allows the running of 'make ps' or 'make dvi', both of which fail in the same way as pdf. They fail at:

xmlto --extensions -o ./pdf pdf ./usermanual.xml
Making portrait pages on letter paper (215.9mmx279.4mm)

(where pdf is pdf, dvi, or ps, depending on the target).

Enabling DEBUG in the Makefile yields:

This is pdfTeX, Version 3.1415926-1.40.10 (TeX Live 2009/Debian)
 restricted \write18 enabled.
entering extended mode
(./tmp.fo
LaTeX2e <2009/09/24>
Babel <v3.8l> and hyphenation patterns for english, usenglishmax, dumylang, noh
yphenation, loaded.
xmltex version: 2002/06/25 v1.9 (Exp):
(/usr/share/texmf/tex/xmltex/config/xmltex.cfg) 
No File: tmp.cfg (/usr/share/texmf/tex/xmltex/passivetex/fotex.xmt)
(/usr/share/texmf-texlive/tex/latex/base/article.cls
Document Class: article 2007/10/19 v1.4h Standard LaTeX document class
(/usr/share/texmf-texlive/tex/latex/base/size10.clo))
(/usr/share/texmf/tex/xmltex/passivetex/fotex.sty
)
No file tmp.aux.
(/usr/share/texmf/tex/latex/tipa/t3ptm.fd)
(/usr/share/texmf-texlive/tex/latex/base/ts1cmr.fd)
(/usr/share/texmf-texlive/tex/latex/psnfss/t1ptm.fd)
(/usr/share/texmf-texlive/tex/context/base/supp-pdf.mkii
[Loading MPS to PDF converter (version 2006.09.02).]
)
No file tmp.out.
No file tmp.out.
INFO: Using normal, i.e. nonfrench-spacing in document
(/usr/share/texmf-texlive/tex/latex/psnfss/t1phv.fd) [1{/var/lib/texmf/fonts/ma
p/pdftex/updmap/pdftex.map}]
(/usr/share/texmf-texlive/tex/latex/psnfss/ts1ptm.fd)
Overfull \hbox (9.40834pt too wide) in paragraph at lines 205--205
[]\T1/ptm/m/n/8 This work is li-censed un-der the Cre-ative Com-mons At-tri-bu-
tion Li-cense. To view a copy of this li-cense, visit []http://creativecommons.
org/licenses/by/2.5/[]
[2] (/usr/share/texmf-texlive/tex/latex/amsfonts/umsa.fd)
(/usr/share/texmf-texlive/tex/latex/amsfonts/umsb.fd)
(/usr/share/texmf-texlive/tex/latex/wasysym/uwasy.fd)
(/usr/share/texmf-texlive/tex/latex/psnfss/t1pcr.fd) [3] [4]

! LaTeX Error: Something's wrong--perhaps a missing \item.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.464 ..." hyphenation-remain-character-count="2">
                                                  Chapter 1. Introduction<...

? 
! Emergency stop.
 ...                                              
                                                  
l.464 ..." hyphenation-remain-character-count="2">
                                                  Chapter 1. Introduction<...

!  ==> Fatal error occurred, no output PDF file produced!
Transcript written on tmp.log.
make: *** [pdf] Error 1


So there appears to be a problem either in our usage of or the implementation of the xmlto tool's latex mechanism.
Comment 3 Darren Hart 2011-03-09 11:53:23 UTC
Using dblatex to do the conversion to pdf, ps, and dvi, but requires the addition of the following packages (on Ubuntu 10.10):

dblatex texlive-bibtex-extra{a} texlive-math-extra{a}

The following patch resolves the issue - but it does require additional packages, which is clearly not ideal. Tested for both txt and pdf targets, which are both affected by the patch.

diff --git a/bitbake/doc/manual/Makefile b/bitbake/doc/manual/Makefile
index a43c025..6a432f8 100644
--- a/bitbake/doc/manual/Makefile
+++ b/bitbake/doc/manual/Makefile
@@ -12,6 +12,7 @@ htmlcss = $(topdir)/html.css
 # htmlcss =
 cleanfiles = $(foreach i,$(types),$(topdir)/$(i))
 
+DEBUG := 1
 ifdef DEBUG
 define command
        $(1)
@@ -45,7 +46,7 @@ endif
        $(call command,xsltproc --stringparam base.dir $@/ $(if $(htmlcssfile),-
 
 $(xmltotypes): $(manual)
-       $(call command,xmlto --extensions -o $(topdir)/$@ $@ $(manual),XMLTO $@ 
+       $(call command,xmlto --with-dblatex --extensions -o $(topdir)/$@ $@ $(ma
 
 clean:
        rm -rf $(cleanfiles)
Comment 4 Darren Hart 2011-03-09 12:03:30 UTC
Even a simple xml file fails to build:

$ cat simple.xml 
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
]>
<book lang="en">
  <bookinfo>
    <title>Test</title>
  </bookinfo>
  <chapter>
    <title>Test chapter</title>
    <para>Test</para>
  </chapter>
</book>

$ xmlto pdf simple.xml
results in the same output as the bitbake manual including:

! LaTeX Error: Something's wrong--perhaps a missing \item.

I'm seeing a few of these bugs reported having gone stale with no resolution, perhaps the dblatex solution is the way to go.
Comment 5 Darren Hart 2011-03-09 14:06:37 UTC
Patch submitted to poky list. Addition of dblatex dependency considered acceptable.
Comment 6 Darren Hart 2011-03-16 08:51:35 UTC
Reopening until the patch is pulled into master.