src/site/apt/usage.apt.vm

 ------
 Usage
 ------
 Vincent Siveton
 ------
 2010-07-28
 ------

~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License.  You may obtain a copy of the License at
~~
~~   http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.

~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html

Usage

 The following examples describe the basic usage of the Doxia Converter.

%{toc|section=1|fromDepth=2|toDepth=2}

* Command Line Help

+-----+
# java -jar target/apache-doxia-${project.version}-jar-with-dependencies.jar -h

usage: doxia [options] -in <arg> [-from <arg>] [-inEncoding <arg>] -out
             <arg> -to <arg> [-outEncoding <arg>]

Options:
 -e,--errors                         Produce execution error messages.
 -f,--format                         Format the output (actually only xml
                                     based outputs) to be human readable.
 -from <arg>                         From format. If not specified, try to
                                     autodetect it.
 -h,--help                           Display help information.
 -in,--input <arg>                   Input file or directory.
 -inEncoding,--inputEncoding <arg>   Input file encoding. If not
                                     specified, try to autodetect it.
 -out,--output <arg>                 Output file or directory.
 -outEncoding,--outputEncoding <arg>   Output file encoding. If not
                                       specified, use the input encoding (or detected).
 -to <arg>                           To format.
 -v,--version                        Display version information.
 -X,--debug                          Produce execution debug output.

Supported Formats:
from: apt, confluence, docbook, fml, twiki, xdoc, xhtml, xhtml5 or autodetect
out: apt, docbook, fo, itext, latex, rtf, xdoc, xhtml, xhtml5
Supported Encoding:
UTF-8, UTF-16BE, UTF-16LE, UTF-32BE, UTF-32LE, Shift_JIS, ISO-2022-JP, ISO-2022-CN, ISO-2022-KR, GB18030, EUC-JP, EUC-KR, Big5,
ISO-8859-1, ISO-8859-2, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8-I, ISO-8859-8, windows-1251, windows-1256, KOI8-R,
ISO-8859-9, IBM424_rtl, IBM424_ltr, IBM420_rtl, IBM420_ltr
+-----+

 <<Note>>: The input parameters (i.e. encoding and format) can be autodetected.

* Command Line Execution

+-----+
# java -jar target/apache-doxia-${project.version}-jar-with-dependencies.jar \
    -in /path/to/xhtml.file \
    -from xhtml \
    -out /path/to/outputdir \
    -to apt
+-----+

  <<Note>>: The <<<from>>> parameter can be empty. In that case, Doxia converter tries to autodetect the <<<from>>>
  input from the <<<in>>> file parameter.

* Java Usage

+-----+
String in = "...";
String from = "...";
String out = "...";
String to = "...";

Converter converter = new DefaultConverter();
try
{
    InputFileWrapper input = InputFileWrapper.valueOf( in, from, "ISO-8859-1", converter.getInputFormats() );
    OutputFileWrapper output = OutputFileWrapper.valueOf( out, to, "UTF-8", converter.getOutputFormats() );

    converter.convert( input, output );
}
catch ( UnsupportedFormatException e )
{
    e.printStackTrace();
}
catch ( ConverterException e )
{
    e.printStackTrace();
}
+-----+

* Ant Usage

+---
 <target name="doxia-convert">
     <java
         jar="./lib/doxia-converter-${project.version}-jar-with-dependencies.jar"
         dir="."
         fork="true"
         failonerror="true"
         >

         <arg value="-in"/>
         <arg value="${tdi.apt}"/>

         <arg value="-out"/>
         <arg value="./doc/${tdi.apt}.${doxia.out.extension}"/>

         <arg value="-to"/>
         <arg value="${doxia.out.format}"/>


         <arg value="-from"/>
         <arg value="apt"/>

         <arg value="-f"/>
     </java>
 </target>

 <target name="doc.xhtml">
     <antcall target="doxia-convert">
         <param name = "doxia.out.format" value = "xhtml"/>
         <param name = "doxia.out.extension" value = "html"/>
     </antcall>
 </target>
 <target name="doc.docbook">
     <antcall target="doxia-convert">
         <param name = "doxia.out.format" value = "docbook"/>
         <param name = "doxia.out.extension" value = "xml"/>
     </antcall>
 </target>
 <target name="doc.rtf">
     <antcall target="doxia-convert">
         <param name = "doxia.out.format" value = "rtf"/>
         <param name = "doxia.out.extension" value = "rtf"/>
     </antcall>
 </target>
 <target name="doc.latex">
     <antcall target="doxia-convert">
         <param name = "doxia.out.format" value = "latex"/>
         <param name = "doxia.out.extension" value = "tex"/>
     </antcall>
 </target>

 <target name="doc">
     <antcall target="doc.xhtml" />
     <antcall target="doc.docbook" />
     <antcall target="doc.rtf" />
     <antcall target="doc.latex" />
 </target>
+---