vb@0: include homepage.en.yhtml2
vb@0: 
vb@0: page "The YML Toolchain" {
vb@0:     h1 > The Toolchain
vb@0: 
vb@0:     p   >>
vb@0:         There are to possibilities to handle YML files: the YML compiler and the YML/YSLT
vb@0:         processor.
vb@0:         >>
vb@0: 
vb@0:     h2 id=compiler > The YML compiler
vb@0: 
vb@0:     p   >>
vb@0:         The YML ¬http://en.wikipedia.org/wiki/Compiler compiler¬ is a small
vb@0:         ¬http://www.python.org Python script¬. It provides the
vb@0:         ¬http://en.wikipedia.org/wiki/Command-line_interface command line¬ front end «yml2c».
vb@0:         As default, it compiles your ¬http://en.wikipedia.org/wiki/Scripting_language script¬
vb@0:         and outputs to ¬http://en.wikipedia.org/wiki/Stdout#Standard_output_.28stdout.29 stdout¬,
vb@0:         that usually is the ¬http://en.wikipedia.org/wiki/Computer_terminal terminal¬.
vb@0:         Your ¬http://en.wikipedia.org/wiki/Shell_(computing) shell¬ provides options to redirect
vb@0:         the output into a ¬http://en.wikipedia.org/wiki/Pipeline_(Unix) pipe¬ or
vb@0:         a ¬http://en.wikipedia.org/wiki/Computer_file file¬.
vb@0:         >>
vb@0: 
vb@0:     p > So to use it, just enter «yml2c» followed by the filename of your YML script:
vb@0: 
vb@0:     Code | % yml2c myscript.yml2 > myscript.result
vb@0: 
vb@0:     p > The «yml2c» command has the following options:
vb@0: 
vb@0:     h3 > -h, --help
vb@0: 
vb@0:     p > Show a help message and exit.
vb@0: 
vb@0:     h3 > -C, --old-syntax
vb@0: 
vb@0:     p > Use the syntax of YML 2 version 1.x (compatibility mode).
vb@0: 
vb@0:     h3 > -D, --emit-linenumbers
vb@0: 
vb@0:     p > Emit line numbers into the resulting XML for debugging purposes.
vb@0: 
vb@0:     h3 > -E ENCODING, --encoding ENCODING
vb@0: 
vb@0:     p > encoding of input files (default: UTF-8)
vb@0: 
vb@0:     h3 > -I INCLUDE_PATH, --include=INCLUDE_PATH
vb@0: 
vb@0:     p { "Precede " code > ¬features#ymlpath YML_PATH¬
vb@0:       " by a colon separated " code "INCLUDE_PATH"; " to search for include files." }
vb@0: 
vb@0:     h3 > -m, --omit-empty-parm-tags
vb@0:     
vb@0:     p   >>
vb@0:         Does nothing (only there for compatibility with older versions of «yml2c»).
vb@0:         >>
vb@0: 
vb@0:     h3 > -n NORMALIZATION, --normalization=NORMALIZATION
vb@0: 
vb@0:     p   >>
vb@0:         Unicode normalization (none, NFD, NFKD, NFC, NFKC, FCD, default is NFC)
vb@0:         >>
vb@0: 
vb@0:     h3 > -o FILE, --output=FILE
vb@0: 
vb@0:     p > Don't output to stdout, instead place output in file «FILE».
vb@0: 
vb@0:     h3 > -p, --parse-only
vb@0: 
vb@0:     p   >>
vb@0:         ¬http://fdik.org/pyPEG Parse¬ only, then output ¬http://fdik.org/pyPEG/#pyAST pyAST¬
vb@0:         as text to stdout. The pyAST is the
vb@0:         ¬http://en.wikipedia.org/wiki/Abstract_syntax_tree Abstract Syntax Tree¬
vb@0:         of the parsed script as ¬http://docs.python.org/library/stdtypes.html Python data structure¬.
vb@0:         >>
vb@0: 
vb@0:     h3 > -V, --version
vb@0: 
vb@0:     p   >>
vb@0:         Show version and ¬http://en.wikipedia.org/wiki/Copyleft Copyleft¬ information of
vb@0:         the YML implementation.
vb@0:         >>
vb@0: 
vb@0:     h3 > YML_PATH environment variable
vb@0: 
vb@0:     p   >>
vb@0:         If «YML_PATH» is set to a colon separated ¬http://en.wikipedia.org/wiki/Path_(computing) path¬
vb@0:         list, then the `a href="features#including" code "include";` statement searches these paths.
vb@0:         If «YML_PATH» is not set, the local directory «.» is searched for files.
vb@0:         >>
vb@0: 
vb@0:     h2 id=processor > The YML/YSLT processor
vb@0: 
vb@0:     p   >>
vb@0:         If you're processing more complex tasks, say, executing an YSLT script over some
vb@0:         YML files, the YML/YSLT processor will possible fit better to your needs.
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         To use it, enter «yml2proc -y» followed by the filename of your YSLT script,
vb@0:         followed by the filenames of your YML input files:
vb@0:         >>
vb@0: 
vb@0:     Code | % yml2proc -y myscript.ysl2 inputfile.yml2 > myscript.result
vb@0: 
vb@0:     p > The YML/YSLT processor requires the ¬http://codespeak.net/lxml/ lxml Python library¬.
vb@0: 
vb@0:     p > The YML/YSLT processor has the following options:
vb@0: 
vb@0:     h3 > -h, --help
vb@0: 
vb@0:     p > Show a help message and exit.
vb@0: 
vb@0:     h3 > -C, --old-syntax
vb@0: 
vb@0:     p > Use the syntax of YML 2 version 1.x (compatibility mode).
vb@0: 
vb@0:     h3 > -D, --emit-linenumbers
vb@0: 
vb@0:     p > Emit line numbers into the resulting XML for debugging purposes.
vb@0: 
vb@0:     h3 id=debug > --debug
vb@0: 
vb@0:     p   >>
vb@0:         switch on debug tracing to stderr; this enables the functionality
vb@0:         of the ¬yslt#debug debug(msg)¬ and ¬yslt#assert assert yml:assert(test, msg)¬ YSLT functions.
vb@0:         >>
vb@0: 
vb@0:     h3 > -E ENCODING, --encoding ENCODING
vb@0: 
vb@0:     p > encoding of input files (default: UTF-8)
vb@0: 
vb@0:     h3 > -I INCLUDE_PATH, --include=INCLUDE_PATH
vb@0: 
vb@0:     p { "Precede " code > ¬features#ymlpath YML_PATH¬
vb@0:       " by a colon separated " code "INCLUDE_PATH"; " to search for include files." }
vb@0: 
vb@0:     h3 > -m, --omit-empty-parm-tags
vb@0:     
vb@0:     p   >>
vb@0:         Does nothing (only there for compatibility with older versions of «yml2proc»).
vb@0:         >>
vb@0: 
vb@0:     h3 > -M, --empty-input-document
vb@0: 
vb@0:     p   >>
vb@0:         Use an empty input document for YSLT or XSLT processing
vb@0:         >>
vb@0: 
vb@0:     h3 > -n NORMALIZATION, --normalization=NORMALIZATION
vb@0: 
vb@0:     p   >>
vb@0:         Unicode normalization (none, NFD, NFKD, NFC, NFKC, FCD, default is NFC)
vb@0:         >>
vb@0: 
vb@0:     h3 > -o FILE, --output=FILE
vb@0: 
vb@0:     p > Don't output to stdout, instead place output in file «FILE».
vb@0: 
vb@0:     h3 > -p, --parse-only
vb@0: 
vb@0:     p   >>
vb@0:         ¬http://fdik.org/pyPEG Parse¬ only, then output ¬http://fdik.org/pyPEG/#pyAST pyAST¬
vb@0:         as text to stdout. The pyAST is the
vb@0:         ¬http://en.wikipedia.org/wiki/Abstract_syntax_tree Abstract Syntax Tree¬
vb@0:         of the parsed script as ¬http://docs.python.org/library/stdtypes.html Python data structure¬.
vb@0:         >>
vb@0: 
vb@0:     h3 > -e XPATH, --xpath=XPATH
vb@0: 
vb@0:     p > Execute XPath expression XPATH and print result
vb@0: 
vb@0:     p   >>
vb@0:         If you omit -y YSLTSCRIPT, then the result is printed. If you have an additional
vb@0:         -y YSLTSCRIPT parameter, then your YSLT script is processing the result of the
vb@0:         XPath expression only instead of processing the complete content of your input documents
vb@0:         >>
vb@0: 
vb@0:     h3 > -P, --pretty
vb@0:     
vb@0:     p > Pretty print output adding whitespace
vb@0: 
vb@0:     h3 > -x, --xml
vb@0:     
vb@0:     p > Input documents are XML already, don't try to convert them from YML
vb@0: 
vb@0:     h3 > -y YSLTSCRIPT, --yslt=YSLTSCRIPT
vb@0: 
vb@0:     p > Execute YSLT script YSLTSCRIPT
vb@0: 
vb@0:     h3 > -X XSLTSCRIPT, --xslt=XSLTSCRIPT
vb@0: 
vb@0:     p > Execute XSLT script XSLTSCRIPT
vb@0: 
vb@0:     h3 > -d PARAMS, --paramdict=PARAMS
vb@0: 
vb@0:     p   >>
vb@0:         Call XSLT or YSLT script with dictionary PARAMS as XPath parameters. PARAMS is a Python
vb@0:         expression which evaluates to a Python dictionary.
vb@0:         >>
vb@0: 
vb@0:     p > Sample:
vb@0: 
vb@0:     p code > yml2proc -y myscript -d 'dict(a=3, b="element[@name=2]")'
vb@0: 
vb@0:     h3 > -s STRINGPARAMS, --stringparamdict=STRINGPARAMS
vb@0: 
vb@0:     p   >>
vb@0:         Call XSLT or YSLT script with dictionary STRINGPARAMS as string parameters. STRINGPARAMS
vb@0:         is a Python expression which evaluates to a Python dictionary.
vb@0:         >>  
vb@0: 
vb@0:     p > Sample:
vb@0: 
vb@0:     p code > yml2proc -y myscript -s 'dict(forename="Hans", name="Meier")'
vb@0: 
vb@0:     h3 > -Y, --xml2yml
vb@0: 
vb@0:     p > Convert XML to normalized YML. Equivalent to -xy xml2yml.ysl2
vb@0: 
vb@0:     p > The file xml2yml.ysl2 has to be in YML_PATH.
vb@0: 
vb@0:     h3 > -V, --version
vb@0: 
vb@0:     p   >>
vb@0:         Show version and ¬http://en.wikipedia.org/wiki/Copyleft Copyleft¬ information of
vb@0:         the YML implementation and exit.
vb@0:         >>
vb@0: 
vb@0:     h3 > YML_PATH environment variable
vb@0: 
vb@0:     p   >>
vb@0:         If «YML_PATH» is set to a colon separated ¬http://en.wikipedia.org/wiki/Path_(computing) path¬
vb@0:         list, then the `a href="features#including" code "include";` statement searches these paths.
vb@0:         If «YML_PATH» is not set, the local directory «.» is searched for files.
vb@0:         >>
vb@0:     
vb@0:     h2 id=recommended > Recommended external tools
vb@0: 
vb@0:     h3 > XSLT Processor
vb@0: 
vb@0:     p   >>
vb@0:         If you want to use ¬yslt YSLT¬ with «yml2c» instead of «yml2proc», you additionally need an
vb@0:         ¬http://www.w3.org/TR/xslt XSLT¬ processor.
vb@0:         >>
vb@0: 
vb@0:     p > For that case, I recommend the ¬http://xmlsoft.org/XSLT/xsltproc2.html xsltproc tool¬.
vb@0: 
vb@0:     p > To process YSLT, just use a pipe with the «xsltproc» command:
vb@0: 
vb@0:     Code | % yml2c customer.ysl2 | xsltproc - customer.xml > customer.html
vb@0: 
vb@0:     h3 > XML Renicing Tool
vb@0: 
vb@0:     p   >>
vb@0:         Sometimes, you may want to have more human readable output with «yml2c». So an
vb@0:         ¬http://www.w3.org/XML/ XML¬ renicing tool can be helpful.
vb@0:         >>
vb@0: 
vb@0:     p > The ¬http://xmlstar.sourceforge.net/ XMLStarlet¬ command line tool may be of interest.
vb@0: 
vb@0:     p > Have a look on its «fo» command.
vb@0: 
vb@0:     h3 > Windows tool chain
vb@0: 
vb@0:     p   >>
vb@0:         See also the tips for a
vb@0:         ¬http://www.auchdieserschwachsinnmussinsinternet.de/2009-03/#s1236859037 Windows tool chain¬
vb@0:         for YML.
vb@0:         >>
vb@0: 
vb@0:     h1 id=downloads > Downloads
vb@0: 
vb@0:     p > You can here ¬http://fdik.org/yml2.tar.bz2 download the newest release of YML¬.
vb@0: 
vb@0:     h2 > Older versions
vb@0: 
vb@0:     p   >>
vb@0:         ¬http://fdik.org/yml-2.5.2.tar.bz2 YML 2.5.2¬
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         ¬http://fdik.org/yml-2.5.1.tar.bz2 YML 2.5.1¬
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         ¬http://fdik.org/yml-2.5.0.tar.bz2 YML 2.5.0¬
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         ¬http://fdik.org/yml-2.4.3.tar.bz2 YML 2.4.3¬
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         ¬http://fdik.org/yml-2.3.12.tar.bz2 YML 2.3.12¬
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         ¬http://fdik.org/yml-2.3.11.tar.bz2 YML 2.3.11¬
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         ¬http://fdik.org/yml-2.3.10.tar.bz2 YML 2.3.10¬
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         ¬http://fdik.org/yml-2.3.8.tar.bz2 YML 2.3.8¬
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         ¬http://fdik.org/yml-2.3.7.tar.bz2 YML 2.3.7¬
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         ¬http://fdik.org/yml-2.3.5.tar.bz2 YML 2.3.5¬
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         ¬http://fdik.org/yml-2.2.4.tar.bz2 YML 2.2.4¬
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         ¬http://fdik.org/yml-2.2.3.tar.bz2 YML 2.2.3¬
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         ¬http://fdik.org/yml-2.2.1.tar.bz2 YML 2.2.1¬
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         ¬http://fdik.org/yml-2.2.0.tar.bz2 YML 2.2.0¬
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         ¬http://fdik.org/yml-2.1.17.tar.bz2 YML 2.1.17¬
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         ¬http://fdik.org/yml-2.1.14.tar.bz2 YML 2.1.14¬
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         ¬http://fdik.org/yml-2.1.13.tar.bz2 YML 2.1.13¬
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         ¬http://fdik.org/yml-2.1.12.tar.bz2 YML 2.1.12¬
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         ¬http://fdik.org/yml-2.1.7.tar.bz2 YML 2.1.7¬
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         ¬http://fdik.org/yml-2.1.6.tar.bz2 YML 2.1.6¬
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         ¬http://fdik.org/yml-2.1.5.tar.bz2 YML 2.1.5¬
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         ¬http://fdik.org/yml-2.1.2.tar.bz2 YML 2.1.2¬
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         ¬http://fdik.org/yml-2.0.36.tar.bz2 YML 2.0.36¬
vb@0:         >>
vb@0:     p   >>
vb@0:         ¬http://fdik.org/yml-2.0.35.tar.bz2 YML 2.0.35¬
vb@0:         >>
vb@0: 
vb@0:     p > ¬http://fdik.org/yml1 To the Homepage of version 1 of YML...¬
vb@0: 
vb@0:     div id=bottom {
vb@0:         a href="yslt" "<< back to YSLT" " "
vb@0:         a href="#top" "^Top^" " "
vb@0:         a href="toolchain.en.yhtml2" "(source)"
vb@0:     }
vb@0: }