Re: [Firebird-docs] Questions about documentation build

[Paul V. <pa...@vi...>]

Mark Rotteveel wrote:

> As I mentioned before, I'm reworking the build to gradle so that
>
> 1. We can do away with the old ant version that is not compatible with 
> recent Java versions
> 2. Automatically get the necessary libraries and other dependencies (so 
> no more manually getting the lib folder (and hopefully: tools)) to build
>
> However, I'm running into a number of things that I'd like some input on.
>
> 1. Is the monohtml task ever actually used? If so for which documents?

Helen used it for the Release Notes and some other documents. But she
seems to have switched completely to chunked HTML now.

Monohtml might still be useful for small howtos, fact sheets etc.
Would it mean a lot of extra work to keep it?

> 2. In src/docs/xsl/ some of the stylesheets (eg fo.xsl, html.xsl and 
> htmlbase.xsl) have relative paths to the stylesheets in 
> docbook-stylesheets. If I want to be able to automatically get the 
> necessary stylesheets, I need to be able to use the catalog definition, 
> eg instead of
>
> <xsl:import 
> href="../../../tools/docbook-stylesheets/html/chunk-common.xsl"/>
>
> it would use
>
> <xsl:import 
> href="http://docbook.sourceforge.net/release/xsl/current/html/chunk-common.xsl"/>
>
> And then the catalog file from the stylesheet dependency would resolve 
> that to the correct files. Is there any other reason for the use of 
> these relative paths other than the build itself?

Our stylesheet customisations are based on a specific version of the
DocBook stylesheets (currently 1.72.0 - eleven years old but works for us).
By keeping those in a local copy we ensure that everything keeps working
- and looking - as expected no matter what happens on the DocBook side.

It also means we can build our targets even when docbook.sourceforge.net
is down or slow, or if our own Internet connection is down.

Previous updates of the DocBook stylesheets have been known to break
some of our customisations or cause unwanted layout effects. That's OK
as long as these updates (and whether we apply them or not) are under
our control. But if we just link to the current online version these
things will surprise us (and we may not even notice them immediately
if we build a big document).

Of course we can link to a specific version (after testing it and
possibly having to adapt some of our own templates). This prevents
unpleasant surprises, but we still depend on an Internet link (OK,
or browser cache) to build the docs. Personally I always try to
avoid such dependencies as much as possible.

> 3. Similarly, the xml sources define relative paths to the DTD:
>
> <!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
> "../../tools/docbook-dtd/docbookx.dtd">
>
> If I'm going to do away with the tools folder, these become invalid.
> Is that a problem?

Well, it would break the build, for one thing ;-)

But we could link to the online version (again introducing a dependency
on an Internet link and the availability of an online resource).

> Otherwise I can always add a task that automatically downloads and
> unzips this to that location.

If it's not too much work, I would like that. That way we would have our
local cache.

I guess the same could be done with the DocBook stylesheets - if it's
not too much work.

Cheers,
Paul