Re: [Firebird-docs] Questions about documentation build

[Mark R. <ma...@la...>]

On 8-7-2018 15:28, Paul Vinkenoog wrote:
> Mark Rotteveel wrote:
>> 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?

No, I saw some oddities in how it worked, and if it wasn't used, it 
wouldn't make sense to sort that out.

>> 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.

I'll see if there exists a dependency with that version, otherwise I may 
just depend on the existing zip file from the Firebird site. Or we may 
need to spend time to update (and I'm not sure if that is worth it).

> 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.

No, that is not how it would work in the new setup. I add a dependency 
on zip files with the XSL and DTD files, and define a catalog manager 
which will make the XSLT engine use the XSL files from the jar file: the 
URL is just used as a unique identifier, not the actual resource 
location (URI vs URL).

> 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).

I'll try to find a way to approach this. Personally, I think the 
Firebird documentation style could use with some freshing up. On the 
other hand, spending time to do that, would be an investment that might 
lead away from migrating to asciidoc in the long term.

> 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.

The internet link is only necessary when the zipfile(s) with xsl and/or 
dtd is not yet in the local gradle cache. Afterwards, bar certain cache 
refreshes/clean ups, it will always refer to the local cache. The 
advantage on the other hand is that it reduces the manual steps 
necessary to get the documentation build to work, which will make it 
easier. It will also allow for creating an automated build that can be 
executed on each commit and that would work the same as a local build.

>> 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 ;-)

Not if the catalog manager is correctly configured :)

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

It would be a dependency on a zip-file that is downloaded automatically 
but kept in cache.

>> 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.

My suggestion to automatically unzip was more for when something outside 
the build needed the files; the build wouldn't be needing it as it would 
use a zip-file on its classpath.

Mark
-- 
Mark Rotteveel