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/doxia-converter-${project.version}-shaded.jar -h

usage: doxia-converter [-e] [-f] [-from <arg>] [-h] [-in <arg>] [-inEncoding <arg>] [-out <arg>] [-outEncoding <arg>] [-to
       <arg>] [-v] [-X]

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 <arg>     Input file encoding. If not specified, try to autodetect it (only works if input is a single file)
 -out,--output <arg>   Output file or directory.
 -outEncoding <arg>    Output file encoding. If not specified, use the input encoding (or autodetected).
 -to <arg>             To format.
 -v,--version          Display version information.
 -X,--debug            Produce execution debug output.

Supported Formats:
 from: apt, fml, xdoc, xhtml or auto
 to:   apt, xdoc, xhtml, markdown


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/doxia-converter-${project.version}-shaded.jar \
    -in /path/to/xhtml.file \
    -from xhtml \
    -out /path/to/outputdir \
    -to markdown
-------

  <<Note>>: The <<<from>>> parameter can be empty. In that case, Doxia converter tries to autodetect the <<<from>>>
  input from the <<<in>>> file parameter, this only works when the input is a file (and not a directory).

* 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}-shaded.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">
     <antcall target="doc.xhtml" />
 </target>
+-----+