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
it would use
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:
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
--
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
___
Firebird-docs mailing list
Firebird-docs@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/firebird-docs
