source-git / dblatex

Clone
Source Code
GIT

Blame docs/xhtml/manual/sec-specs.html

c8 c8s master
  1.   76cb0294bf8109d8642ba4628f1ec896b1b7195b
  2.   docs
  3.   xhtml
  4.   manual
  5.   sec-specs.html
Blob History Raw
Packit Service 76cb02
Packit Service 76cb02
Packit Service 76cb02 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Dblatex Configuration File</title><link rel="stylesheet" type="text/css" href="manual.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /><link rel="home" href="index.html" title="DocBook to LaTeX Publishing" /><link rel="up" href="sec-custom.html" title="Chapter 4. Customization" /><link rel="prev" href="sec-texpost.html" title="Latex post process script" /><link rel="next" href="ch04s08.html" title="Customization Precedence" /></head><body>
Dblatex Configuration File
Prev Chapter 4. Customization Next
Dblatex Configuration File
XML Configuration File Format
Deprecated Text Configuration File Format
Style Paths
Packit Service 76cb02 
   A configuration file, also called a specification file, can be used
Packit Service 76cb02 
   to list all the customizations and options to apply. Such a file is passed
Packit Service 76cb02 
   by using the
Packit Service 76cb02 
   option -S config_file. Several
Packit Service 76cb02 
   configuration files can be specified if needed; it can be usefull to have a
Packit Service 76cb02 
   default setup and additional setup for specific needs that override or
Packit Service 76cb02 
   complete the default configuration.
Packit Service 76cb02 
  
XML Configuration File Format
<config>
<latex>
<xslt>
<engine>
<imagedata>
<converter>
<command>
<options>
Packit Service 76cb02 
   You should use the XML format to configure dblatex. It contains more
Packit Service 76cb02 
   features than the text format used up to the 0.3.7 release that is now
Packit Service 76cb02 
   deprecated. The principle remains the same, that is, most of the
Packit Service 76cb02 
   configuration parameters correspond to a command line option.
Packit Service 76cb02
Packit Service 76cb02 
  Here is a full example of a configuration file. In the next sections the
Packit Service 76cb02 
  meaning and use of the configuration tags are detailed.
Packit Service 76cb02 
  
<?xml version="1.0" encoding="utf-8"?>
Packit Service 76cb02 
<!-- ======================================================= -->
Packit Service 76cb02 
<!-- Dblatex Configuration example for building a book       -->
Packit Service 76cb02 
<!-- ======================================================= -->
Packit Service 76cb02 
<config xmlns="http://dblatex.sourceforge.net/config" version="1.0">
Packit Service 76cb02 
  <latex>
Packit Service 76cb02 
    <backend use="xetex"/>
Packit Service 76cb02 
    <texstyle use="dbsimple"/>
Packit Service 76cb02 
    <texpost fileref="dblatex-postprocess"/>
Packit Service 76cb02 
    <indexstyle fileref="../myindexstyle.ist"/>
Packit Service 76cb02 
    <texinputs>../mystyledir:/etc/texmf/userfont</texinputs>
Packit Service 76cb02 
  </latex>
Packit Service 76cb02 
  <xslt>
Packit Service 76cb02 
    <stylesheet fileref="user_param.xsl"/>
Packit Service 76cb02 
    <stylesheet fileref="xetex_param.xsl"/>
Packit Service 76cb02 
    <stylesheet fileref="pdf.xsl"/>
Packit Service 76cb02 
  </xslt>
Packit Service 76cb02 
  <imagedata>
Packit Service 76cb02 
    <converter src="svg" dst="*" docformat="pdf">
Packit Service 76cb02 
      <command>
Packit Service 76cb02 
        inkscape -z -D --export-dpi=600 --export-%(dst)s=%(output)s %(input)s
Packit Service 76cb02 
      </command>
Packit Service 76cb02 
    </converter>
Packit Service 76cb02 
  </imagedata>
Packit Service 76cb02 
  <options>-X -V</options>
Packit Service 76cb02 
</config>
Packit Service 76cb02
Packit Service 76cb02
Packit Service 76cb02 
   Another example, much simpler, is the configuration file used for
Packit Service 76cb02 
   this manual.
Packit Service 76cb02 
  
Example 4.5. User Manual Configuration File
<?xml version="1.0" ?>
Packit Service 76cb02 
<!--
Packit Service 76cb02 
  ====================================================================
Packit Service 76cb02 
  Configuration file for dblatex documentation (manual, release notes)
Packit Service 76cb02 
  ====================================================================
Packit Service 76cb02 
-->
Packit Service 76cb02 
<config xmlns="http://dblatex.sourceforge.net/config">
Packit Service 76cb02 
  <latex>
Packit Service 76cb02 
    <texinputs>../latex//</texinputs>
Packit Service 76cb02 
    <texstyle use="docbook"/>
Packit Service 76cb02 
    <backend use="pdftex"/>
Packit Service 76cb02 
  </latex>
Packit Service 76cb02 
  <xslt>
Packit Service 76cb02 
    <stylesheet fileref="manual.xsl"/>
Packit Service 76cb02 
  </xslt>
Packit Service 76cb02 
</config>
Packit Service 76cb02 

The following sections detail the meaning of each tag. Note that
Packit Service 76cb02 
  dblatex provides some schema that you can use to validate your configuration
Packit Service 76cb02 
  file.
<config>
It is the root element of a configuration file. A valid configuration
Packit Service 76cb02 
  file must have a config root element.
Attributes:
Packit Service 76cb02 
  
xmlns
The namespace to use for a dblatex configuration file is:
Packit Service 76cb02 
      http://dblatex.sourceforge.net/config.
Packit Service 76cb02
Packit Service 76cb02 
  The following elements occur in config:
Packit Service 76cb02 
  latex, xslt,
Packit Service 76cb02 
  imagedata, options.
Packit Service 76cb02 
  
<latex>
The latex element contains the configuration data related to the latex
Packit Service 76cb02 
  processing.
Attributes: none
Packit Service 76cb02 
  The following elements occur in latex:
Packit Service 76cb02 
  
backend
It defines the latex engine to use, like the option
Packit Service 76cb02 
      --backend does. The backend name is specified through the
Packit Service 76cb02 
      use attribute.
texstyle
It defines the docbook latex style to use, like the option
Packit Service 76cb02 
      --texstyle does. The latex package is specified through the
Packit Service 76cb02 
      use attribute.
texpost
It defines the latex post-processing script to use, like the
Packit Service 76cb02 
      option --texpost does. The script name is specified through the
Packit Service 76cb02 
      use attribute or the fileref
Packit Service 76cb02 
      attribute.
indexstyle
It defines index style file (.ist) to use, like the
Packit Service 76cb02 
      option --indexstyle does. The filename is
Packit Service 76cb02 
      specified through the fileref
Packit Service 76cb02 
      attribute.
texinputs
The element text defines the extra paths to add to TEXINPUTS,
Packit Service 76cb02 
      like the option --texinputs does.
bibinputs
The element text defines the lookup paths of BIBINPUTS,
Packit Service 76cb02 
      like you would do by successive use of the option --bib-path.
Packit Service 76cb02 
      
bstinputs
The element text defines the lookup paths of BSTINPUTS,
Packit Service 76cb02 
      like you would do by successive use of the option --bst-path.
Packit Service 76cb02
Packit Service 76cb02 
  
<xslt>
The xslt element contains the configuration data related to the XSL
Packit Service 76cb02 
  processing.
Attributes: none
Packit Service 76cb02 
  The following elements occur in xslt:
Packit Service 76cb02 
  
stylesheet
It defines a user stylesheet to use, like the option
Packit Service 76cb02 
      --xsl-user does. The stylesheet name is specified through the
Packit Service 76cb02 
      fileref attribute. If several
Packit Service 76cb02 
      stylesheet elements are set, the precedence is the same
Packit Service 76cb02 
      like using the option --xsl-user several times.
engine
See engine.
Packit Service 76cb02 
  
<engine>
It defines the XSLT processor to use; it can be either a predefined
Packit Service 76cb02 
  engine, or a user-defined command to run.
When the attribute
Packit Service 76cb02 
  use is used, it works like the option
Packit Service 76cb02 
  --xslt. The engine name is specified through the
Packit Service 76cb02 
  use attribute.
Packit Service 76cb02 
  When the element contains the command or
Packit Service 76cb02 
  commandchain child element it defines the command(s)
Packit Service 76cb02 
  to run to perform the XSLT processing. The core keywords defined in
Packit Service 76cb02 
  command apply. The additional keywords of an XSLT
Packit Service 76cb02 
  engine command are the following:
Packit Service 76cb02 
  
%(xmlfile)s
Replaced by the XML source file to
Packit Service 76cb02 
      process.
%(stylesheet)s
Replaced by the stylesheet to use to process the
Packit Service 76cb02 
      XML file xmlfile.
%(param_list)s
Replaced by the list of the XSL parameters to set.
Packit Service 76cb02 
      The parameter pair formatting (the parameter name and its value) is
Packit Service 76cb02 
      specified through the param-format attribute
Packit Service 76cb02 
      given to the engine element.
Packit Service 76cb02 
  
Attributes:
Packit Service 76cb02 
  
param-format
This attribute is mandatory when the engine is specified
Packit Service 76cb02 
      through a command. It tells how a parameter name and
Packit Service 76cb02 
      value pair shall be formatted when added to the XSLT engine command.
Packit Service 76cb02 
      The formatting is given by a string containing the keywords replaced by
Packit Service 76cb02 
      the name or value of the parameter to set:
Packit Service 76cb02
Packit Service 76cb02 
      
%(param_name)s
Replaced by the name of the
Packit Service 76cb02 
          parameter to set.
%(param_value)s
Replaced by the value to set to the
Packit Service 76cb02 
          parameter.
Packit Service 76cb02
Packit Service 76cb02 
  The following example re-writes with a user-defined command the Saxon engine
Packit Service 76cb02 
  with an additional -T option:
Packit Service 76cb02 
  





Packit Service
76cb02

<xslt>





Packit Service
76cb02

  <engine param-format="%(param_name)s=%(param_value)s">





Packit Service
76cb02

    <command>





Packit Service
76cb02

    saxon-xslt -T -o %(output)s %(xmlfile)s





Packit Service
76cb02

                                %(stylesheet)s %(param_list)s</command>





Packit Service
76cb02

  </engine>





Packit Service
76cb02

</xslt>





Packit Service
76cb02

  
<imagedata>
The imagedata element contains the rules and commands to convert





Packit Service
76cb02

  on the fly the images included in the docbook document.
Attributes: none





Packit Service
76cb02

  The following elements occur in imagedata:





Packit Service
76cb02

  
figpath
It defines a path where to find the images, like the





Packit Service
76cb02

      option --fig-path does.
figformat
It defines the default image format when no suffix is





Packit Service
76cb02

      available to deduce the actual format, like 





Packit Service
76cb02

      --fig-format does.
formatrule
It specifies in which format an image must be 





Packit Service
76cb02

      converted, depending on the context, given by some attributes:





Packit Service
76cb02

      
docformat
The output document for which the rule





Packit Service
76cb02

          applies. When not set the rule applies for any format
backend
The rule applies only when this backend is





Packit Service
76cb02

          used
dst
When the conditions are met the image shall be





Packit Service
76cb02

          converted to this format.





Packit Service
76cb02

      
The following example:





Packit Service
76cb02

      
<formatrule docformat="pdf" backend="xetex" dst="pdf"/>





Packit Service
76cb02

      tells that when a PDF document is built with the xetex backend, the





Packit Service
76cb02

      graphics not natively supported shall be converted to PDF.





Packit Service
76cb02

      
converter
It defines an image transformation rule. See 





Packit Service
76cb02

      converter for more





Packit Service
76cb02

      details.





Packit Service
76cb02

  
<converter>
The converter element defines a rule about how to convert on the fly





Packit Service
76cb02

  an image in a docbook document to the corresponding image used in the built





Packit Service
76cb02

  latex file. The





Packit Service
76cb02

  goal is to have an image format compatible with the latex engine, whatever the





Packit Service
76cb02

  original format is. Dblatex has a default set of rules, but





Packit Service
76cb02

  one can overwrite or add some rules.
Attributes:





Packit Service
76cb02

  
src
Format of the original image referenced in the XML





Packit Service
76cb02

      document. The converter only applies to the images matching this format.





Packit Service
76cb02

      
dst
Target format once converted. The converter only applies





Packit Service
76cb02

      to the original images having the format src and that





Packit Service
76cb02

      need to be converted to the format dst.





Packit Service
76cb02

      dst can take the special value "*"





Packit Service
76cb02

      meaning that the rule applies for all





Packit Service
76cb02

      the possible target formats (e.g. eps, pdf, png).
docformat
Specify for which document output format the converter





Packit Service
76cb02

      applies. For example, if docformat is set to "pdf",





Packit Service
76cb02

      it means that





Packit Service
76cb02

      the converter applies only if the document output format is PDF. The





Packit Service
76cb02

      converter will not apply if you want to build a PostScript or DVI





Packit Service
76cb02

      document.
backend
The converter applies only if it is this latex engine that





Packit Service
76cb02

      is used. For example, it is usefull if you want to convert an image in a





Packit Service
76cb02

      specific way only when xetex is used.





Packit Service
76cb02

  
The following elements occur in converter:





Packit Service
76cb02

  
commandchain
List of the commands to run. A





Packit Service
76cb02

      commandchain contains one or more





Packit Service
76cb02

      command elements.





Packit Service
76cb02

      
command
command to execute to perform the conversion, or a part of





Packit Service
76cb02

      the conversion if several commands are chained. See





Packit Service
76cb02

      command.





Packit Service
76cb02

      





Packit Service
76cb02

  
<command>
The command element contains the arguments of the command to run.





Packit Service
76cb02

  The arguments can contain some predefined keywords that are replaced by the





Packit Service
76cb02

  actual values when the command is executed. The known core keywords





Packit Service
76cb02

  are:
%(src)s
Replaced by the src value (original





Packit Service
76cb02

      image format).
%(dst)s
Replaced by the dst value (target





Packit Service
76cb02

      image format).
%(input)s
Replaced by the input file required by the command. In the





Packit Service
76cb02

      case of an image conversion, it is the filename of the original image to





Packit Service
76cb02

      convert.
%(output)s
Replaced by the name of the ouput file required by the





Packit Service
76cb02

      command. In the case of an image conversion, it is the filename of the





Packit Service
76cb02

      output image once converted.
Attributes:





Packit Service
76cb02

  
input
Standard input of the command to run. It can specify a





Packit Service
76cb02

      file or it can specify to use the output of the preceding command if the





Packit Service
76cb02

      keyword "PIPE" is used.
output
Standard output of the command to run. It can specify a





Packit Service
76cb02

      file or it can specify that the output shall be redirected to the next





Packit Service
76cb02

      command if the keyword "PIPE" is used.
shell
When set to "1" or "true", the command is run in a shell 





Packit Service
76cb02

      environment.





Packit Service
76cb02

  
<options>
The options element lists the extra arguments to pass to





Packit Service
76cb02

  dblatex.
Deprecated Text Configuration File Format





Packit Service
76cb02

   The format of the file is the following:





Packit Service
76cb02

  





Packit Service
76cb02

   Every comment starts with a “#”, and is ignored.





Packit Service
76cb02

   
    		• 

    

    
Packit Service
76cb02

       The file must contain one parameter by line.
    		

    

    
Packit Service
76cb02

       
    		• 

    

    
Packit Service
76cb02

       The format of a parameter is the following:
    		

    

    
Packit Service
76cb02

       
    		

    

    
Packit Service
76cb02

    <keyword>: <value>
    		

    

    
Packit Service
76cb02

       
    		• 

    

    
Packit Service
76cb02

       Every parameter is mapped to an option that can be passed to dblatex.
    		

    

    
Packit Service
76cb02

       
    		• 

    

    
Packit Service
76cb02

       An unknown parameter is silently ignored (the whole line is dropped).
    		

    

    
Packit Service
76cb02

       
    		• 

    

    
Packit Service
76cb02

       The parameters defining a path (a file or a directory) can take absolute or relative paths. A relative path must be defined from the specification file itself. For instance, a specification file under /the/spec/directory/ with a parameter describing the file ../where/this/file/is/myfile points to /the/spec/where/this/file/is/myfile.
    		

    

    
Packit Service
76cb02

       
    		

    

    
Packit Service
76cb02

       The following table lists the supported parameters and the corresponding command line option.
    		

    

    
Packit Service
76cb02

      
    KeywordValueCorresponding optionDescription
    TexInputsDirectories--texinputsDefines extra path to add to TEXINPUTS
    TexStyleLatex package name--texstyleDefines the LaTeX style package to use.
    TexPostScript file name--texpostDefines the LaTeX post process script to use.
    XslParamParameter file name-pDefines the parameter file to use.
    FigInputsDirectories-IDefines the extra figures path.
    OptionsCommand line optionsNoneLists command options to use by default when using the tool. The
    		

    

    
Packit Service
76cb02

    options specified by the parameter are directly passed to
    		

    

    
Packit Service
76cb02

    dblatex
    Style Paths
    By default dblatex tries to find the configuration
    		

    

    
Packit Service
76cb02

      files related to a style (specified with option -T) in the
    		

    

    
Packit Service
76cb02

      following paths, in respect of the order:
    1. The current directory
    2. $HOME/.dblatex
    3. /etc/dblatex
    4. The dblatex package configuration directories.
    You can add some extra paths where to look for by setting the
    		

    

    
Packit Service
76cb02

      DBLATEX_CONFIG_FILES environment variable. The paths are
    		

    

    
Packit Service
76cb02

      separated by ":" in Unix like systems, and by ";" on Windows. These paths
    		

    

    
Packit Service
76cb02

      are used only when nothing is found in the default paths.
    Prev Up Next
    Latex post process script Home Customization Precedence
    </body></html>
    		

    

    
  
    
 
     



    
    
    

        
    
        
    
            
    
         Powered by
          Pagure
          5.13.3
            
    
            
    SSH Hostkey/Fingerprint | Documentation