Uploaded image for project: 'LaTeX'
  1. LaTeX
  2. LATEX-97

Add ability to include files and images in custom latex templates

    Details

    • Type: New Feature
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: 1.10
    • Fix Version/s: 1.11
    • Component/s: Filter, Syntax
    • Labels:
      None
    • Difficulty:
      Unknown
    • Documentation in Release Notes:
      N/A
    • Similar issues:

      Description

      Right now it's not possible to have a custom template that will for example display an image since that image also needs to be copied to the latex zip or in the generated PDF.

      The idea is to add a $latex.resourceConverter binding in the velocity execution context to be able to do that:

      @Role
      public interface LaTeXResourceConverter
      {
          /**
           * @param currentReference the current document reference, used to resolve references to absolute references
           * @param outputStream the stream to which copied resources should be written to
           */
          void initialize(EntityReference currentReference, OutputStream outputStream);
      
          /**
           * Convert a {@link ResourceReference}'s reference so that it has the right reference when serialized into the
           * LaTeX output. For example this can mean converting the reference of an image attachment reference into a
           * filesystem file reference (by copying the image located into an attachment of a wiki page to the file system).
           *
           * @param reference the resource reference to convert (a link reference or an image reference)
           * @param baseResourceReference the base reference of the current XDOM block, used to resolve the resource
           *        reference into an absolute reference. Can be relative, in which case the current reference is used to
           *        make it absolute. Can be null in which was the current reference is used.
           * @param forceDownload if true, then convert external references (like URL references) into local references. For
           *        examples image reference by URLs can be downloaded locally and the reference swapped for a local
           *        filesystem reference.
           * @return the converted reference
           */
          ResourceReference convert(ResourceReference reference, String baseResourceReference, boolean forceDownload);
      
          /**
           * Convert a {@link ResourceReference}'s reference so that it has the right reference when serialized into the
           * LaTeX output. For example this can mean converting the reference of an image attachment reference into a
           * filesystem file reference (by copying the image located into an attachment of a wiki page to the file system).
           *
           * @param reference the resource reference to convert (a link reference or an image reference)
           * @param forceDownload if true, then convert external references (like URL references) into local references. For
           *        examples image reference by URLs can be downloaded locally and the reference swapped for a local
           *        filesystem reference.
           * @return the converted reference
           */
          ResourceReference convert(ResourceReference reference, boolean forceDownload);
      
          /**
           * @param linkBlock the link resource to convert. The closest base reference from the passed link block will be
           *        used to resolve local references
           * @return the converted reference
           */
          ResourceReference convert(LinkBlock linkBlock);
      
          /**
           * @param imageBlock the image resource to convert. The closest base reference from the passed image block will be
           *        used to resolve local references
           * @return the converted reference
           */
          ResourceReference convert(ImageBlock imageBlock);
      }
      

      Example usage (from LinkBlock):

      #set ($linkBlock = $latex.block)
      ## Convert the image to a local image to embed it in the result
      #set ($resourceReference = $latex.resourceConverter.convert($linkBlock))
      #set ($type = $resourceReference.type.scheme)
      ## Consider that we're on a local link when the reference is empty and anchor is not empty
      #set ($reference = $resourceReference.reference)
      #set ($anchor = $latex.block.reference.getParameter('anchor'))
      #if ($type == 'doc')
        #if ("$!reference" == '' && "$!anchor" != '')
          #if ($latex.block.getChildren().isEmpty())
            \ref{${anchor}}##
          #else
            \hyperref[${anchor}]{${latex.processor.process($latex.block.getChildren())}}##
          #end
        #else
          ## Ignore links that are not local, just display the label if there's one or the reference otherwise
          #if ($latex.block.getChildren().isEmpty())
            $latex.tool.escape($reference)##
          #else
            ${latex.processor.process($latex.block.getChildren())}##
          #end
        #end
      #elseif ($type == 'url' || $type == 'path')
        #if ($latex.block.getChildren().isEmpty())
          \url{${reference}}##
        #else
          \href{${reference}}{${latex.processor.process($latex.block.getChildren())}}##
        #end
      #elseif ($type == 'mailto')
        #if ($latex.block.getChildren().isEmpty())
          \href{mailto:${reference}}{$latex.tool.escape($reference)}##
        #else
          \href{mailto:${reference}}{${latex.processor.process($latex.block.getChildren())}}##
        #end
      #elseif ($type == 'attach')
        #set ($escapedReference = $latex.tool.escape($reference))
        #if ($latex.block.getChildren().isEmpty())
          ## Use a default icon when no label is provided. Another option would be to use the filename as text.
          \attachfile{$latex.tool.escape($reference)}##
        #else
          \textattachfile{$latex.tool.escape($reference)}{${latex.processor.process($latex.block.getChildren())}}##
        #end
      #end
      

      Example from Index:

      \documentclass{$latex.properties.documentClass}
      \usepackage{standalone}
      
      ## Commands that can be overridden by users in a custom Preamble
      \newcommand{\xwikidate}[1]{
        ${SP}${SP}\date{\DTMdate{#1}}}
      \newcommand{\xwikititle}[1]{
        ${SP}${SP}\title{#1}}
      \newcommand{\xwikiauthor}[1]{
        ${SP}${SP}\author{#1}}
      
      $latex.processor.render('Preamble')
      
      ## Needs to be put after the babel package
      #if ("$!latex.properties.date" != '' && $latex.properties.coverPage)
        % Used to format the date for the cover page
        \usepackage[useregional]{datetime2}
      
      #end
      \begin{document}
      
      #set ($shouldClearPage = false)
      ## Display numbers in TOC and list of tables/figures using the roman style
      #if ($latex.properties.pageNumbering && $latex.properties.coverPage && $latex.properties.toc || $latex.properties.listOfFigures || $latex.properties.listOfTables)
        \pagenumbering{Roman}
      #elseif (!$latex.properties.pageNumbering)
        \pagenumbering{gobble}
      #end
      #if ($latex.properties.coverPage && "$!latex.properties.title" != '')
        #if ("$!latex.properties.title" != '')
          #if ("$!latex.properties.subtitle" != '')
            \xwikititle{%
              ${SP}${SP}$latex.tool.escape($latex.properties.title)\\
              ${SP}${SP}\large ${latex.properties.subtitle}}
          #else
            \xwikititle{$latex.tool.escape($latex.properties.title)}
          #end
        #end
        #if ("$!latex.properties.author" != '')
          \xwikiauthor{$latex.tool.escape($latex.properties.author)}
        #end
        #if ("$!latex.properties.date" != '')
          \xwikidate{$latex.tool.escape($datetool.format('yyyy-MM-dd', $latex.properties.date))}
        #end
        #if ("$!latex.properties.coverPageImage" != '')
          \begin{center}
          \includegraphics{$latex.tool.escape($latex.resourceConverter.convert($latex.properties.coverPageImage, true).reference)}
          \end{center}
        #end
        \maketitle
      #end
      #if ($latex.properties.toc)
        \setcounter{tocdepth}{3}
        \tableofcontents
        ## Make sure no page numbers are printed in the TOC
        #if (!$latex.properties.pageNumbering)
          \addtocontents{toc}{\protect\thispagestyle{empty}}
        #end
        #set ($shouldClearPage = true)
      #end
      #if ($latex.properties.listOfFigures)
        \listoffigures
        #set ($shouldClearPage = true)
      #end
      #if ($latex.properties.listOfTables)
        \listoftables
        #set ($shouldClearPage = true)
      #end
      #if ($shouldClearPage)
        \clearpage
      #end
      ## Reset page counter so that first page of the doc starts at 1
      #if ($latex.properties.pageNumbering && $latex.properties.coverPage && $latex.properties.toc || $latex.properties.listOfFigures || $latex.properties.listOfTables)
        \setcounter{page}{0}
        ## Display numbers on pages using the arabic style
        \pagenumbering{arabic}
      #end
      #if ("$!latex.includes" != '')
      
        #foreach ($latexPageInclude in $latex.includes)
          ## Don't escape the page since LaTeX doesn't support escapes in paths and the path has already been cleaned.
          \include{$latexPageInclude}
        #end
      #end
      
      \end{document}
      

        Attachments

          Activity

            People

            • Assignee:
              vmassol Vincent Massol
              Reporter:
              vmassol Vincent Massol
            • Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: