xmlto

XMLTO(1)                             xmlto                            XMLTO(1)

NAME

       xmlto - apply an XSL stylesheet to an XML document

SYNOPSIS

       xmlto [-o output_dir] [-x custom_xsl] [-m xsl_fragment] [-v]
             [-p postprocessor_opts] [--extensions] [--searchpath path]
             [--skip-validation] {format} {file}

       xmlto {--help | --version}

DESCRIPTION

       The  purpose  of  xmlto is to convert an XML file to the desired format
       using whatever means necessary. This may involve two steps:


       1. The application of an appropriate XSL stylesheet using an XSL-T pro-
          cessor.

       2. Further processing with other tools. This step may not be necessary.



       To decide which stylesheet to use and what, if any, needs to be done to
       post-process  the  output, xmlto makes use of format scripts, which are
       simple shell scripts that xmlto calls during the conversion.


       The appropriate format script is selected based on the type of XML file
       and the desired output format. xmlto comes with some format scripts for
       converting DocBook XML files to a variety of formats. You  may  specify
       your  own format script by using an absolute filename for format on the
       command line.


       Firstly, if xmlto has not been told explicitly which stylesheet to  use
       (with  the  -x option), the format script will be called with $1 set to
       stylesheet. The environment variable XSLT_PROCESSOR contains  the  base
       name of the executable that will be used to perform the XSL-T transfor-
       mation (for example xsltproc), and  the  environment  variable  XSL_DIR
       contains  the  path to the directory containing some useful stylesheets
       that come with xmlto. The format script should write the  name  of  the
       stylesheet  to  use  to  standard output and exit successfully, or exit
       with a non-zero return code if there is no  appropriate  stylesheet  to
       use (for example, if the only available stylesheet is known not to work
       with the XSL-T processor that will be used). If nothing is  written  to
       standard output but the script exits successfully, no XSL-T transforma-
       tion will be performed.


       Secondly, after an XSL-T processor has been run using  the  stylesheet,
       the  format  script  will  be  called  again,  this time with $1 set to
       post-process. The format script should perform any necessary  steps  to
       translate  the  XSL-T  processed output into the desired output format,
       including copying the output  to  the  desired  output  directory.  For
       post-processing, the format script is run in a temporary directory con-
       taining just the processed output (whose name is  stored  in  XSLT_PRO-
       CESSED  and  whose  basename  is that of the original XML file with any
       filename extension replaced with .proc). INPUT_FILE is set to the  name
       of the original XML file, OUTPUT_DIR is set to the name of the directo-
       ry that the output (and only the output) must end up in, and SEARCHPATH
       is  set  to  a  colon-separate list of fallback directories in which to
       look for input (for images, for example). If this step is  unsuccessful
       the format script should exit with a non-zero return code.


       -v     Be verbose (-vv for very verbose).


       -x stylesheet
              Use  stylesheet  instead  of  asking the format script to choose
              one.


       -m fragment
              Use the provided XSL fragment to modify the stylesheet.


       -o directory
              Put output in the specified directory  instead  of  the  current
              working directory.


       -p postprocessor_opts
              Pass  postprocessor_opts  to  processing stages after stylesheet
              application (e.g. lynx or links when going through HTML to text,
              or  xmltex  when going from through TeX to DVI). If -p is speci-
              fied a second time, the options specified will be passed to sec-
              ond-stage postprocessing; presently this is only applicable when
              going through xmltex and dvips to PostScript.


       --extensions
              Turn on stylesheet extensions for the tool chain in use (for ex-
              ample,  this  might turn on passivetex.extensions and use.exten-
              sions if PassiveTeX is being used). The variables turned on  are
              the ones used by Norman Walsh’s DocBook XSL stylesheets.


       --searchpath path
              Add  the colon-separated list of directories in path as fallback
              directories for including input.


       --skip-validation
              Skip the validation step that is normally performed.


       --help Display a short usage message. It will describe xmlto’s options,
              and the available output formats.


       --version
              Display the version number of xmlto.

EXAMPLES

       To convert a DocBook XML document to PDF, use:


              xmlto pdf mydoc.xml


       To  convert a DocBook XML document to HTML and store the resulting HTML
       files in a separate directory use:


              xmlto -o html-dir html mydoc.xml


       To convert a DocBook XML document to a single HTML file use:


              xmlto html-nochunks mydoc.xml


       To modify the output using an XSL fragment use:


              xmlto -m ulink.xsl pdf mydoc.xml


       To specify which stylesheet to use (overriding the one that the  format
       script would choose) use:


              xmlto -x mystylesheet.xsl pdf mydoc.xml

AUTHOR

       Tim Waugh <twaugh@redhat.com>.



Linux                            October 2002                         XMLTO(1)