I made some changes, the tasks are now generic and the base set name is
specified with a commandline option:
gradlew docbookHtml
will build the entire firebirddocs set (firebirddocs is the default
baseName)
gradlew docbookHtml --baseName=refdocs --docId=fblangref25
will build the Firebird 2.5 language reference
Same for docbookPdf and docbookMonohtml
I decided to include docbook in the task name in preparation of
supporting asciidoc in the future.
Due to incompatible changes with regard to how the stylesheets are
specified and resolved (specifically the imports), the Ant build doesn't
work. Using ant requires using relative paths, while the gradle-based
builds uses a catalog manager to resolve stylesheets by their URI.
For example to make ant work again, it is necessary to replace
<xsl:import
href="http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl"/>
with
<xsl:import href="../../../tools/docbook-stylesheets/fo/docbook.xsl"/>
I'm wondering if I should invest time to 'fix' that or not. I think it
is probably better to switch-over and tackle any issues that occur
instead of allowing both to exist side-by-side.
Mark
On 07-02-2020 18:26, Mark Rotteveel wrote:
I'm currently working on a gradle build to replace the current ant-based
build for the documentation.
It is a work-in-progress, but I'd really like some other eyes on its
output. So, could some of you please try it out, look at its output and
report any problems you see compared to the existing output of the ant
build, or with its usage?
The gradle version used requires Java 8 or higher.
You can find this work-in-progress in the branch gradle-conv-attempt-3
in my fork of the repository
https://github.com/mrotteveel/firebird-documentation
Some examples:
Building docs can be done with
gradlew firebirddocsHtml
building German docs can be done with
gradlew firebirddocsHtml --language=de
building the nullguide as PDF can be done with
gradlew firebirddocsPdf --docId=nullguide
(on Linux or MacOS you may have to use ./gradlew, in PowerShell, you may
have to use .\gradlew)
There are separate tasks for release notes, papers and reference docs.
Beware, the commandline parameters are per task, so if for example you
want html and pdf in German in one execute, you must use:
gradlew firebirddocsPdf --language=de firebirddocsHtml --language=de
To see all tasks:
gradlew tasks --group=documentation
Help for a specific task (is pretty sparse though):
gradlew help --task=rlsnotesHtml
Some important changes:
* The gradle build does not use the lib/ and tools/ folders (though the
XML currently still contains relative references to the tools folder,
which I want to fix once I'm done)
* The ant-build used some conditional behaviour that drove me a bit
crazy to replicate when implementing this, so I changed the following to
ensure consistency
** No more special handling for firebirddocs English set (so output is
in - for example - build/html-firebirddocs, and not in build/html, and
the root firebirddocs.xml has been moved into the firebirddocs/ folder)
** Every base-set now has an XSLT file (eg html-firebirddocs.xsl)
without falling back to html.xsl if such a file does not exist
* I removed the foxon usage, because it caused errors with newer
versions of Apache FOP, and it wasn't immediately clear to me what this
was for
* Build uses docbook XSL 1.79.1 (ant build uses 1.72.0)
* Apache FOP 2.4 (ant build uses 0.95-1 I think)
Some things that I haven't worked on yet:
* Language specific FOP configuration
* Rewriting the readme
* ... not verified everything
Important caveat: this is a work in progress. Naming of tasks and
options isn't final yet. For example, I am still considering changing
this to use a single task per output type instead of a task per (output
type) x (base name), and configure the base name through a commandline
option (eg gradlew html --baseName=rlsnotes instead of gradlew
rlsnotesHtml)
I made some changes to the ant build to make it consistent with the
changes I made for the firebirddocs base name, but I haven't actually
tested that yet.
Mark
--
Mark Rotteveel
_______________________________________________
Firebird-docs mailing list
Firebird-docs@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/firebird-docs
