Support managing or performing copy instructions for media files

src/guide/xml/ch03.xml

@@ -516,11 +516,13 @@ subdirectory.
 the desired results for each combination of input and output arrangements.</para>
 
 <note>
-<para>Remember that in each case, the questions are: can the
+<para>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.”</para>
+“not our problem.”
+But the stylesheets can help to manage or even perform the task
+of copying on demand. See <parameter>copyinstructions-uri</parameter>.</para>
 </note>
 
 <variablelist>

src/guide/xml/ch04.xml

@@ -406,7 +406,13 @@ will be to <uri>media/image.png</uri>.
 <para>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.</para>
+other process,
+unless you expressly request further assistance. 
+If the parameter <parameter>copyinstructions-uri</parameter> is set accordingly,
+a file with copy instructions is created at the specified location.
+If the function <code>file:copy</code> from <citation>EXPATH File</citation> 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.</para>
 </important>
 </section>
 </section>

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.</para>
 </refsection>
 </refentry>
+
+<refentry>
+  <refmeta>
+    <fieldsynopsis>
+      <type>xs:string?</type>
+      <varname>copyinstructions-uri</varname>
+    </fieldsynopsis>
+  </refmeta>
+  <refnamediv>
+    <refpurpose>URI for a file with copy instructions for image files</refpurpose>
+  </refnamediv>
+  <refsection>
+    <title>Description</title>
+    <para>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
+        <code>file:copy</code> function from <citation>EXPATH File</citation> is available during
+      the transformation:</para>
+    <orderedlist numeration="loweralpha">
+      <listitem>
+        <para>When <code>file:copy</code> is available, the stylesheets will copy the files to the
+          place where the generated HTML files expects them. In this case, the file at
+            <code>copyinstructions-uri</code> is a logfile with one entry for each copy
+          operation.</para>
+      </listitem>
+      <listitem>
+        <para>When <code>file:copy</code> is not available, the file at
+              <code>copyinstructions-uri</code> contains instructions which  should be executed in
+            some way independently of the stylesheets. The template
+              <template>t:write-copyinstructions</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.</para>
+      </listitem>
+    </orderedlist>
+      <para>When it is given as a relative path, it will be resolved against the current working
+        directory (see <function>ext:cwd</function>).</para>
+  </refsection>
+</refentry> 
 
 <refentry>
   <refmeta>

src/guide/xml/ref-templates.xml

@@ -624,6 +624,52 @@ to process footnotes at the bottom of a table.</para>
 chunking is performed, this should provide links between pages.</para>
 </refsection>
 </refentry>
+
+<refentry xml:id="t_write-copyinstructions">
+  <?db filenamme='t_write-copyinstructions'?>
+  <refmeta>
+    <refentrytitle>t:write-copyinstructions</refentrytitle>
+    <refmiscinfo>{http://docbook.org/ns/docbook/templates}write-copyinstructions</refmiscinfo>
+  </refmeta>
+  <refnamediv>
+    <refname>t:write-copyinstructions</refname>
+    <refpurpose>Writes copy instructions for media files</refpurpose>
+    <refclass>template</refclass>
+  </refnamediv>
+  <refsection>
+    <title>Description</title>
+    <para>This template is responsible for writing copy instructions for media files.
+    It is called when the parameter <parameter>copyinstructions-uri</parameter> is set.
+    The default implementation simply writes an XML filewith an <code>copy</code> element for each media file.
+    You may want to overwrite this template to produce a batch file for UNIX or Microsoft Windows environment.</para>
+
+    <para>It is called with three parameters:</para>
+    <variablelist>
+      <varlistentry>
+        <term>instructions: map(xs:anyURI, xs:anyURI)</term>
+        <listitem>
+          <para>A  map with one entry for every copy destination of some media file. 
+            <emphasis>key </emphasis>is destination, <emphasis>value</emphasis> 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.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>href: xs:anyURI</term>
+        <listitem>
+          <para>the absolute path for the file that is generated by this template.
+          Calculated from <parameter>copyinstructions-uri</parameter>.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>mediaobject-basedirectory: xs:anyURI?</term>
+        <listitem>
+          <para>The base directory for every media file.
+          Not required, only for documentation.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsection>
+</refentry>
 
 <refentry xml:id="t_video-fallback">
 <?db filename="t_video-fallback"?>

src/guide/xml/references.xml

@@ -118,6 +118,12 @@ W3C Recommendation. 8 June 2017.</bibliomixed>
 xlink:href="https://www.w3.org/TR/xsl/">Extensible Stylesheet
 Language (XSL) Version 1.1</citetitle>. Anders Berglund, Editor.
 W3C Recommendation. 5 December 2006.</bibliomixed>
+
+<bibliomixed>
+  <abbrev>EXPATH File</abbrev>
+  <citetitle xlink:href="http://expath.org/spec/file">File Module 1.0</citetitle>,
+  <pubdate>20 February 2015</pubdate>. Christian Grün, Editor.
+</bibliomixed>              
 
 </bibliography>
 

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 @@
   <xsl:variable name="result" as="document-node()">
     <xsl:sequence select="fp:run-transforms($result, $post-processing)"/>
   </xsl:variable>
+
+  <!-- Try to create or perform copy instructions for media files marked by @ghost:sourcefile -->
+  <xsl:if test="$copyinstructions-uri and exists($result//*[@ghost:sourcefile])">
+    <xsl:variable name="current-output-directory" as="xs:string?" select="
+        if (current-output-uri()) then
+          tokenize(current-output-uri(), '/')[position() lt last()] => string-join('/') => concat('/')
+        else
+          ()"/>
+    <xsl:call-template name="tp:mediaobjects-copyinstructions">
+      <xsl:with-param name="mediaobjects" select="$result//*[@ghost:sourcefile]"/>
+      <xsl:with-param name="current-output-directory" as="xs:string?" select="$current-output-directory"/>
+    </xsl:call-template>
+  </xsl:if>
+
+  <!-- Get rid of @ghost attributes -->
+  <xsl:variable name="result" as="document-node()">
+    <xsl:apply-templates select="$result" mode="mp:final-cleanup"/>
+  </xsl:variable>
 
   <xsl:choose>
     <xsl:when test="$return = 'raw-results'">
@@ -448,5 +467,10 @@
     </xsl:otherwise>
   </xsl:choose>
 </xsl:function>
+
+<!-- mp:final-cleanup removes attributes in the ghost namespace -->
+<xsl:mode name="mp:final-cleanup" on-no-match="shallow-copy"/>
+
+<xsl:template mode="mp:final-cleanup" match="@ghost:*"/>
 
 </xsl:stylesheet>

src/main/xslt/main.xsl

@@ -59,6 +59,7 @@
 <xsl:include href="modules/attributes.xsl"/>
 <xsl:include href="modules/publishers.xsl"/>
 <xsl:include href="modules/annotations.xsl"/>
+<xsl:include href="modules/copyinstructions.xsl"/>  
 
 <xsl:import href="modules/chunk.xsl"/>
 <xsl:import href="modules/chunk-cleanup.xsl"/>