Re: CVS PDF-docs

[Bart Veer <bartv at ecoscentric dot com>]

>>>>> "Jifl" == Jonathan Larmour <jifl@eCosCentric.com> writes:

    Jifl> Andrew Lunn wrote:
    >>> What patch is this? I don't see anything on the lists.
    >> 
    >> 
    >> Its not been on the list yet...
    >> 
    >> You also need a file called jadetex.cfg in doc/sgml and its
    >> subdirectories. It should contain:
    >> 
    >> \hypersetup{pdfpagemode=None,  pdfauthor=eCos (pdfjadetex) ,  colorlinks=true,
    >> linkcolor=blue,  pdfstartview=FitH}

    Jifl> Wouldn't the link stuff be in a stylesheet? And other than
    Jifl> pdfauthor (which I wouldn't have thought would be used) what
    Jifl> are the other bits for.

    >> \def\Gin@extensions{.pdf,.png,.jpg,.mps,.tif,.gif}

    Jifl> Why is this needed? It should work without that surely...
    Jifl> The names are specified in the ENTITIES.

This jadetex.cfg stuff does not feel right. It seems like a workaround
for problems in the current implementation of the stylesheets and
pdfjadetex. Adding lots of new jadetex.cfg files seems especially
ugly, a single centralized file would be much more acceptable.

    Jifl> And in the patch below, why the subst .html? The .sgml,
    Jifl> .html and starting page of the .pdf should all have the same
    Jifl> prefixes (even though it's based on the <TITLE>). And the
    Jifl> .html file may not exist.

Agreed, the new rules for MAIN_PDF does not seem to achieve anything.

    Jifl> Although anyway this should probably be posted on
    Jifl> ecos-patches and discussed there. I know Bart takes quite an
    Jifl> interest in documentation generation and I wouldn't want him
    Jifl> to be excluded if he wants to have a say. In fact, I think
    Jifl> I'll CC it now anyway.

The basic problem is that the various tools involved (jade/openjade,
pdfjadetex) have undergone significant development in the last couple
of years. So different Linux distributions use significantly different
versions, and makefile rules which work for one person may not work
for another. I suspect there is still ongoing development, addressing
e.g. problems with picture files being included or not.

For example, the patch switches from using jade/jadetex/dvips/ps2pdf
to jade/pdfjadetex. This may seem like a sensible change, it gets you
to the end product more quickly and with fewer intermediate steps that
can lose data. Unfortunately when I first started working with DocBook
pdfjadetex was unreliable, hence the current rules.doc file uses
alternative tools.

In the past I have tended to use recent Red Hat Linux releases on my
various machines, keeping things simple. I am in the process of
installing Debian 3.0 on one of them, to allow me to test code in more
varied environments. However there will still be people who use older
distributions, and hence may not have usable tools.

I think we need to do one of:

  1) insist that everybody uses a specific version of the various
     tools, or >= a specific version. This would need to be enforced
     by rules.doc, so people who are using older tools get told to
     upgrade rather than have the build fail or produce incorrect
     output.

  2) or, detect the versions being used and adapt as appropriate.
     That suggests autoconf/automake, but I am not sure we want to
     start using those for documentation.

Bart