making Bugzilla documentation PDF

[Michael G. Katzmann]

Can someone tell me the command line to create a PDF of the
Bugzilla 'docbook' SGML documentation. I presume docbook2pdf
should do it but I'm unfamiliar with the options etc.

I have all the tools to produce the html and txt docs.

Michael

--
|\ _,,,---,,_ Michael Katzmann
/,`.-'`' -. ;-;;,_ NV3Z / VK2BEA / G4NYV
|,4- ) )-,_. ,\ ( `'-'
'---''(_/--' `-'\_) michaelk at IEEE org

[Jacob Steenhagen]

Michael G. Katzmann wrote:
> Can someone tell me the command line to create a PDF of the
> Bugzilla 'docbook' SGML documentation. I presume docbook2pdf
> should do it but I'm unfamiliar with the options etc.

Truth be told, I'd like to know how to do that, too :) Right now, the
only PDF version is what can be found at tldp.org. I've fiddled w/it in
the past, but I could never get it work quite as well as tldp.org's PDF.

> I have all the tools to produce the html and txt docs.
>
> Michael

- Jake

[Arne Schirmacher]

Jacob Steenhagen <ja...@bugzilla.org> wrote in message news:<bcbbmo$da...@ripley.netscape.com>...

...

> Truth be told, I'd like to know how to do that, too :) Right now, the
> only PDF version is what can be found at tldp.org. I've fiddled w/it in
> the past, but I could never get it work quite as well as tldp.org's PDF.

Download this docbook environment (works on Windows too):

http://docbook.e-novative.de/

You can easily convert the Bugzilla SGML files to XML (only a couple
of typos in two or three files) and then use the docbook environment
to produce PDF or HTML.

[Don Fike]

This is what I do, your steps maybe different depending on your tools and
installation etc...

tex->dvi->ps->pdf

Output TEX
openjade -t tex -d
/usr/share/sgml/docbook/dsssl-stylesheets-1.76/print/docbook.dsl UG.sgm

Output DVI
jadetex UG.tex [may need to run up to 3 times]

Output PS
dvips -o UG.ps UG.dvi

Output PDF
ps2pdf UG.ps UG.pdf

Also;

Validate
onsgmls -sv -E 0 -c /etc/sgml/catalog UG.sgm

Output HTML
sgmltools -b html -s /usr/local/share/sgml/stylesheets/sgmltools/html.dsl
UG.sgm

Output RTF
openjade -t rtf -d
/usr/share/sgml/docbook/dsssl-stylesheets-1.76/print/docbook.dsl UG.sgm

[Michael Katzmann]

Don Fike wrote:
> This is what I do, your steps maybe different depending on your tools and
> installation etc...
>
> tex->dvi->ps->pdf
>
> Output TEX
> openjade -t tex -d
> /usr/share/sgml/docbook/dsssl-stylesheets-1.76/print/docbook.dsl UG.sgm
>
> Output DVI
> jadetex UG.tex [may need to run up to 3 times]
>
> Output PS
> dvips -o UG.ps UG.dvi
>
> Output PDF
> ps2pdf UG.ps UG.pdf
>

I misstated, the docs are in XML not sgml. Does that make much of a difference ?
When I try that with Bugzilla-Guide.xml I get 200 errors (before it give up) like:

openjade:/usr/share/sgml/docbook/xml-dtd-4.1.2-1.0-17/docbookx.dtd:74:17:E: "X20
AC" is not a function name
openjade:/usr/share/sgml/docbook/xml-dtd-4.1.2-1.0-17/ent/iso-amsa.ent:8:19:E: "
X21B6" is not a function name
openjade:/usr/share/sgml/docbook/xml-dtd-4.1.2-1.0-17/ent/iso-amsa.ent:9:19:E: "
X21B7" is not a function name

[Don Fike]

docBook can process both sgm and xml, I haven't worked with xml sources so
I'm not sure about any differences. I would think that the differences
would be handled in the background so you shouldn't have to make any changes
yourself. I think there is an -E option that handles error reporting,
setting it to zero will let it continue without stopping at the default 200
error limit. Many errors can be ignored but sometimes when your flooded
with errors it indicates that your catalog or dsssl spec isn't found. I
verified the Bugzilla docs using;

onsgmls -sv -E 0 -c /etc/sgml/catalog -ferrors.txt Bugzilla-Guide.xml

This reported over 900 errors in my environment. However I was still able
to produce the tex file using;

openjade -t tex -E 0 -d
/usr/share/sgml/docbook/dsssl-stylesheets-1.76/print/docbook.dsl
Bugzilla-Guide.xml

Hope this helps,

-----Original Message-----
From: Michael Katzmann [mailto:NOSPAM-...@IEEE.org]
Sent: Friday, June 13, 2003 10:46 AM
To: mozilla-...@mozilla.org
Subject: Re: making Bugzilla documentation PDF

[Dave Miller]

On 6/13/2003 11:30 AM -0400, Don Fike wrote:

> docBook can process both sgm and xml, I haven't worked with xml sources so
> I'm not sure about any differences. I would think that the differences
> would be handled in the background so you shouldn't have to make any changes
> yourself. I think there is an -E option that handles error reporting,
> setting it to zero will let it continue without stopping at the default 200
> error limit. Many errors can be ignored but sometimes when your flooded
> with errors it indicates that your catalog or dsssl spec isn't found. I
> verified the Bugzilla docs using;
>
> onsgmls -sv -E 0 -c /etc/sgml/catalog -ferrors.txt Bugzilla-Guide.xml
>
> This reported over 900 errors in my environment. However I was still able
> to produce the tex file using;

I believe the Bugzilla Guide uses a modified dsssl file. There's
instructions in docs/README.docs for the modifications you need to make.
--
Dave Miller Project Leader, Bugzilla Bug Tracking System
http://www.justdave.net/ http://www.bugzilla.org/

[Jacob Steenhagen]

Don Fike wrote:
> This is what I do, your steps maybe different depending on your tools and
> installation etc...
>
> tex->dvi->ps->pdf
>
> Output TEX
> openjade -t tex -d
> /usr/share/sgml/docbook/dsssl-stylesheets-1.76/print/docbook.dsl UG.sgm

Because we've been using LDP's stylesheet for the HTML I modified this
line slightly:
jade -t tex -d $LDP_HOME/ldp.dsl\#print $JADE_PUB/xml.dcl \
Bugzilla-Guide.xml

> Output DVI
> jadetex UG.tex [may need to run up to 3 times]

Running jadetex 3 times appears to be the key I was missing last time I
tried to do this. I could get the PDF output but the page numbers were
all ??. After running jadetex 3 times it outputs the page nums :)

> Also;
>
> Validate
> onsgmls -sv -E 0 -c /etc/sgml/catalog UG.sgm
>
> Output HTML
> sgmltools -b html -s /usr/local/share/sgml/stylesheets/sgmltools/html.dsl
> UG.sgm
>
> Output RTF
> openjade -t rtf -d
> /usr/share/sgml/docbook/dsssl-stylesheets-1.76/print/docbook.dsl UG.sgm
>

Is the point of this sequence just to output RTF?

[Jacob Steenhagen]

Dave Miller wrote:
> I believe the Bugzilla Guide uses a modified dsssl file. There's
> instructions in docs/README.docs for the modifications you need to make.

I'm pretty sure the -d line we use in makedocs.pl allows us to not need
to modify the the dsssl file... at least I don't recally modifying it
when I set up this environment.

I'll probably modify makedocs.pl to optionally create the PDF version.

[Michael Katzmann]

Jacob Steenhagen wrote:

> I'm pretty sure the -d line we use in makedocs.pl allows us to not need
> to modify the the dsssl file... at least I don't recally modifying it
> when I set up this environment.
>
> I'll probably modify makedocs.pl to optionally create the PDF version.
>

That all worked well ( apart from a couple of lines and boxes that
ran off the page )

FYI.
I noticed that the top margin was missing on the PDF (the top line was
hard against the top of the page).
I checked with Adobe distiller and it was fine, so this was a ps2pdf
problem.

I found this wrapper for ps2pdf that fixed it.

#!/bin/sh
ISPS=`head -1 ${1} | grep '^%!PS'`
if [ ! $ISPS ]; then
# if not a PostScript file then exit
echo here
exit 1
else
BASENAME=`basename ${1} .ps`
PDFNAME=`echo $BASENAME.pdf`
BBOX=`head -20 ${1} | grep BoundingBox`
SIZE=`echo $BBOX | awk '{MAXX = 2642; MINX = 595;
MAXY = 129600; MINY = 595;
X=$2+$4; Y=$3+$5;
if (X > MAXX) X=MAXX
else if ( X < MINX ) X=MINX
if (Y > MAXY) Y=MAXY
else if ( Y < MINY ) Y=MINY
print X+100,Y+100}'`
sed "/EndComments/a\\
<< /PageSize [ ${SIZE} ] /ImagingBBox null \ >> setpagedevice" ${1} \
| ps2pdf - $PDFNAME
fi

Michael

|\ _,,,---,,_ - Michael Katzmann

/,`.-'`' -. ;-;;,_

|,4- ) )-,_. ,\ ( `'-'

'---''(_/--' `-'\_) - michaelk at IEEE org