Re: DOCBOOK-APPS: Problem converting DB to PDF...

[Nik Clayton <nik@nothing-going-on.demon.co.uk>]

On Tue, Feb 20, 2001 at 12:01:32PM -0500, Adam Di Carlo wrote:
[...]

> In some ways, your needs seem pretty specific to what you are doing.
> I mean, there's a lot of talk about library images and repository
> images and stuff, based on your CVS structure (or at least it seemed
> on a glance).

It's specific to FreeBSD, yes, but I've tried to model it so there are
very few FreeBSD specific requirements.  I know other documentation
efforts (like the Open Source Writers Group) are using the model we have
in FreeBSD.

Basically, we have system components and Doc. Proj. components, and we
try to keep them separate.  

The system components are things like the DocBook DTD, Norm's
stylesheets, associated DTDs and entity files, and so on.  These can be
anywhere on the system, as long as there are one or more catalogs that
point to them.  This also includes things like Jade, TeX, w3m, and so
forth.

The Doc. Proj. components are things like freebsd.dsl, the .mk
infrastructure, documentation boilerplate (like the license text) that's
shared between lots of documents, and so forth.

You can subdivide the Doc. Proj. components further.  There are some
things (like the FreeBSD DTD) that are shared between all the documents.
There are some things (like the boilerplate, or library images) that are 
on a per-language or encoding basis, and some things (like the document 
itself, obviously) that are per document.

So the directory structure for the FDP is this:

   doc
    +- share
    |   +--- mk
    |   +--- sgml
    |   `--- web2c
    +- en_US.ISO_8859-1
    |   +--- books
    |   |     +--- handbook
    |   |     +--- faq
    |   |     ...
    |   |--- articles
    |   |     ...
    |   `--- share
    |         +--- images
    |         `--- sgml
    |
    ...

doc/share contains the project specific stuff.  doc/en_US.ISO_8859-1/
contains the English stuff (with it's own English specific directory).
Other languages and encodings also hang off doc/.
doc/en_US.ISO_8859-1/share/ contains the stuff shared between all the
English docs.  For example, the boilerplate SGML files live in
share/sgml, and the images that are shared between the English docs
(like the numbered callouts, or the warning/tip/note images) live there.

share/images, in this context, is the "Image library" mentioned in the
Makefiles.

The FDP Makefile's do assume chunks of this structure.  For example, it
is assumed that you can reach doc/share from any of the documents by
going ../../../share/.  But we do make sure that assumptions like these
are covered by variables, and that the user can override them.

For example, suppose you check out the doc/share hierarchy under
/usr/doc, and then you check out a language hierarchy in $HOME/docs/...

The Makefiles (by default) assume that they can reach $HOME/docs/share/,
but you can change that by setting the DOC_PREFIX variable.  So in this
example you might do

    % cd ~/docs/en_US.ISO_8859-1/books/faq
    % make DOC_PREFIX=/usr/doc book.html

and everything will work.

> You guys use BSD make and we use GNU make.  If we standardized, I
> would think it would be reasonable to standardize on SYSV make, but
> you guys might not find that acceptable.  

Any pointers to SYSV make?

> OTOH, if we went with a
> makefile-maker system like preheat uses, I could see us being able to
> support either SYSV or BSD make without too much problems.

Could do.  I don't have sufficient free time to look at preheat if it's
completely undocumented.  But if you've got docs that can get me started
then I'll give it a go ASAP.

> Even if we can't, I would like to be sure that we are at least
> consistent between each other in the jade -V and -i switches that we
> pass to indicate the output format.

Absolutely.

> > I discovered that if I convert PNG images to EPS files and then run them
> > through TeX they appear about twice the size they should do.  For
> > example, an 80x24 xterm takes up almost half the page.
> 
> Is this some sort of TeX problem?  'convert' problem?  Is the EPS
> itself that large?

If I convert the PNG to EPS it appears about twice the size I want in
the output.

If I run pdftex (which can read PNG images directly) the images also
appear about twice the size.  I suspect it's because the image's DPI is
too low (72 DPI instead of 144 DPI, or something like that).

The problem was, while I could pass command line flags to the PNG -> EPS
conversion process to double the density (and thereby halve the image
size), this doesn't work for the PDF stuff, because the PDF and HTML
formats share the same image file.  Either I shrink the PDF file (and
then the HTML output looks wrong), or I had to find a way to get DocBook
/ TeX to scale the image for me -- preferably without forcing the author
to write " ... scale='50' ... " for every single image.

> > Then redefine the Graphic handling in the stylesheet, like so;
> > 
> >     (define ($graphic$ fileref
> 
> [...]
> 
> See, in preheat I can't do things like this since I can't rely on
> specific DSSSL customizations.

preheat has to be able to point to a DSSSL stylesheet though, right?

As it stands, if you process the FreeBSD docs through Norm's stylesheets
they come out OK.  Some of the images will be too big, and a few other
bits and pieces will be off, but it works.

> > What's the best way to make sure that you guys are informed when changes
> > are committed?
> 
> Can you have the CVS commitlog for just that file email to me ?

Possibly.  I'll ask our CVS repo-meisters.

N
-- 
Internet connection, $19.95 a month.  Computer, $799.95.  Modem, $149.95.
Telephone line, $24.95 a month.  Software, free.  USENET transmission,
hundreds if not thousands of dollars.  Thinking before posting, priceless.
Somethings in life you can't buy.  For everything else, there's MasterCard.
  -- Graham Reed, in the Scary Devil Monastery