diff --git a/src/guide/xml/ch03.xml b/src/guide/xml/ch03.xml index 7e2dc1d17..841a96168 100644 --- a/src/guide/xml/ch03.xml +++ b/src/guide/xml/ch03.xml @@ -516,11 +516,13 @@ subdirectory. the desired results for each combination of input and output arrangements. -Remember that in each case, the questions are: can the +Remember that in each case, the question is: can the stylesheets find the media files to query them and are the correct HTML references produced? Actually copying the media files from where they are in the source system to where they need to be in the HTML is -“not our problem.” +“not our problem.” +But the stylesheets can help to manage or even perform the task +of copying on demand. See copyinstructions-uri. diff --git a/src/guide/xml/ch04.xml b/src/guide/xml/ch04.xml index 3487d9576..f990225ab 100644 --- a/src/guide/xml/ch04.xml +++ b/src/guide/xml/ch04.xml @@ -406,7 +406,13 @@ will be to media/image.png. The stylesheets are not responsible for actually copying the media files into the correct locations in the output. The stylesheets only generate the HTML files and the references. You must copy the images and other media with some -other process. +other process, +unless you expressly request further assistance. +If the parameter copyinstructions-uri is set accordingly, +a file with copy instructions is created at the specified location. +If the function file:copy from EXPATH File is available +(which is the case when you are using Saxon PE or EE), +the stylesheets will actually perform these instructions and copy the files. diff --git a/src/guide/xml/ref-params.xml b/src/guide/xml/ref-params.xml index 57031b4e5..9af67ac19 100644 --- a/src/guide/xml/ref-params.xml +++ b/src/guide/xml/ref-params.xml @@ -904,6 +904,44 @@ this script will be added to the document. This script must contain the JavaScri necessary to support the theme controls. + + + + + xs:string? + copyinstructions-uri + + + + URI for a file with copy instructions for image files + + + Description + This parameter is empty by default. If this parameter contains a valid file path, this + means that support for copying image files is requested (should be media files in general, + but only image files are implemented yet). The level of support depends on whether the + file:copy function from EXPATH File is available during + the transformation: + + + When file:copy is available, the stylesheets will copy the files to the + place where the generated HTML files expects them. In this case, the file at + copyinstructions-uri is a logfile with one entry for each copy + operation. + + + When file:copy is not available, the file at + copyinstructions-uri contains instructions which should be executed in + some way independently of the stylesheets. The template + is responsible for writing the file, it + determines the format of the "instructions". You may want to override it to generate a + batch file in UNIX® or Windows style. + + + When it is given as a relative path, it will be resolved against the current working + directory (see ext:cwd). + + diff --git a/src/guide/xml/ref-templates.xml b/src/guide/xml/ref-templates.xml index da040b117..9665421e9 100644 --- a/src/guide/xml/ref-templates.xml +++ b/src/guide/xml/ref-templates.xml @@ -624,6 +624,52 @@ to process footnotes at the bottom of a table. chunking is performed, this should provide links between pages. + + + + + t:write-copyinstructions + {http://docbook.org/ns/docbook/templates}write-copyinstructions + + + t:write-copyinstructions + Writes copy instructions for media files + template + + + Description + This template is responsible for writing copy instructions for media files. + It is called when the parameter copyinstructions-uri is set. + The default implementation simply writes an XML filewith an copy element for each media file. + You may want to overwrite this template to produce a batch file for UNIX or Microsoft Windows environment. + + It is called with three parameters: + + + instructions: map(xs:anyURI, xs:anyURI) + + A map with one entry for every copy destination of some media file. + key is destination, value is source of media file. + This ensures that we have only on copy instruction, even if the media file is references many times in the document. + + + + href: xs:anyURI + + the absolute path for the file that is generated by this template. + Calculated from copyinstructions-uri. + + + + mediaobject-basedirectory: xs:anyURI? + + The base directory for every media file. + Not required, only for documentation. + + + + + diff --git a/src/guide/xml/references.xml b/src/guide/xml/references.xml index 1456d77e4..b72e66188 100644 --- a/src/guide/xml/references.xml +++ b/src/guide/xml/references.xml @@ -118,6 +118,12 @@ W3C Recommendation. 8 June 2017. xlink:href="https://www.w3.org/TR/xsl/">Extensible Stylesheet Language (XSL) Version 1.1. Anders Berglund, Editor. W3C Recommendation. 5 December 2006. + + + EXPATH File + File Module 1.0, + 20 February 2015. Christian Grün, Editor. + diff --git a/src/main/xslt/docbook.xsl b/src/main/xslt/docbook.xsl index 82f9d7341..13c50a9a2 100644 --- a/src/main/xslt/docbook.xsl +++ b/src/main/xslt/docbook.xsl @@ -5,6 +5,7 @@ xmlns:err='http://www.w3.org/2005/xqt-errors' xmlns:ext="http://docbook.org/extensions/xslt" xmlns:f="http://docbook.org/ns/docbook/functions" + xmlns:ghost="http://docbook.org/ns/docbook/ephemeral" xmlns:fp="http://docbook.org/ns/docbook/functions/private" xmlns:h="http://www.w3.org/1999/xhtml" xmlns:m="http://docbook.org/ns/docbook/modes" @@ -275,6 +276,24 @@ + + + + + + + + + + + + + + @@ -448,5 +467,10 @@ + + + + + diff --git a/src/main/xslt/main.xsl b/src/main/xslt/main.xsl index 2f30f8b5f..ef725fe73 100644 --- a/src/main/xslt/main.xsl +++ b/src/main/xslt/main.xsl @@ -59,6 +59,7 @@ + diff --git a/src/main/xslt/modules/copyinstructions.xsl b/src/main/xslt/modules/copyinstructions.xsl new file mode 100644 index 000000000..4683cf3d0 --- /dev/null +++ b/src/main/xslt/modules/copyinstructions.xsl @@ -0,0 +1,209 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/main/xslt/modules/objects.xsl b/src/main/xslt/modules/objects.xsl index 70c8b1009..07640a644 100644 --- a/src/main/xslt/modules/objects.xsl +++ b/src/main/xslt/modules/objects.xsl @@ -5,6 +5,7 @@ xmlns:ext="http://docbook.org/extensions/xslt" xmlns:f="http://docbook.org/ns/docbook/functions" xmlns:fp="http://docbook.org/ns/docbook/functions/private" + xmlns:ghost="http://docbook.org/ns/docbook/ephemeral" xmlns:h="http://www.w3.org/1999/xhtml" xmlns:m="http://docbook.org/ns/docbook/modes" xmlns:map="http://www.w3.org/2005/xpath-functions/map" @@ -756,7 +757,9 @@ + + @@ -767,12 +770,13 @@ + - +