|
1 include homepage.en.yhtml2 |
|
2 |
|
3 page "The YML Toolchain" { |
|
4 h1 > The Toolchain |
|
5 |
|
6 p >> |
|
7 There are to possibilities to handle YML files: the YML compiler and the YML/YSLT |
|
8 processor. |
|
9 >> |
|
10 |
|
11 h2 id=compiler > The YML compiler |
|
12 |
|
13 p >> |
|
14 The YML ¬http://en.wikipedia.org/wiki/Compiler compiler¬ is a small |
|
15 ¬http://www.python.org Python script¬. It provides the |
|
16 ¬http://en.wikipedia.org/wiki/Command-line_interface command line¬ front end «yml2c». |
|
17 As default, it compiles your ¬http://en.wikipedia.org/wiki/Scripting_language script¬ |
|
18 and outputs to ¬http://en.wikipedia.org/wiki/Stdout#Standard_output_.28stdout.29 stdout¬, |
|
19 that usually is the ¬http://en.wikipedia.org/wiki/Computer_terminal terminal¬. |
|
20 Your ¬http://en.wikipedia.org/wiki/Shell_(computing) shell¬ provides options to redirect |
|
21 the output into a ¬http://en.wikipedia.org/wiki/Pipeline_(Unix) pipe¬ or |
|
22 a ¬http://en.wikipedia.org/wiki/Computer_file file¬. |
|
23 >> |
|
24 |
|
25 p > So to use it, just enter «yml2c» followed by the filename of your YML script: |
|
26 |
|
27 Code | % yml2c myscript.yml2 > myscript.result |
|
28 |
|
29 p > The «yml2c» command has the following options: |
|
30 |
|
31 h3 > -h, --help |
|
32 |
|
33 p > Show a help message and exit. |
|
34 |
|
35 h3 > -C, --old-syntax |
|
36 |
|
37 p > Use the syntax of YML 2 version 1.x (compatibility mode). |
|
38 |
|
39 h3 > -D, --emit-linenumbers |
|
40 |
|
41 p > Emit line numbers into the resulting XML for debugging purposes. |
|
42 |
|
43 h3 > -E ENCODING, --encoding ENCODING |
|
44 |
|
45 p > encoding of input files (default: UTF-8) |
|
46 |
|
47 h3 > -I INCLUDE_PATH, --include=INCLUDE_PATH |
|
48 |
|
49 p { "Precede " code > ¬features#ymlpath YML_PATH¬ |
|
50 " by a colon separated " code "INCLUDE_PATH"; " to search for include files." } |
|
51 |
|
52 h3 > -m, --omit-empty-parm-tags |
|
53 |
|
54 p >> |
|
55 Does nothing (only there for compatibility with older versions of «yml2c»). |
|
56 >> |
|
57 |
|
58 h3 > -n NORMALIZATION, --normalization=NORMALIZATION |
|
59 |
|
60 p >> |
|
61 Unicode normalization (none, NFD, NFKD, NFC, NFKC, FCD, default is NFC) |
|
62 >> |
|
63 |
|
64 h3 > -o FILE, --output=FILE |
|
65 |
|
66 p > Don't output to stdout, instead place output in file «FILE». |
|
67 |
|
68 h3 > -p, --parse-only |
|
69 |
|
70 p >> |
|
71 ¬http://fdik.org/pyPEG Parse¬ only, then output ¬http://fdik.org/pyPEG/#pyAST pyAST¬ |
|
72 as text to stdout. The pyAST is the |
|
73 ¬http://en.wikipedia.org/wiki/Abstract_syntax_tree Abstract Syntax Tree¬ |
|
74 of the parsed script as ¬http://docs.python.org/library/stdtypes.html Python data structure¬. |
|
75 >> |
|
76 |
|
77 h3 > -V, --version |
|
78 |
|
79 p >> |
|
80 Show version and ¬http://en.wikipedia.org/wiki/Copyleft Copyleft¬ information of |
|
81 the YML implementation. |
|
82 >> |
|
83 |
|
84 h3 > YML_PATH environment variable |
|
85 |
|
86 p >> |
|
87 If «YML_PATH» is set to a colon separated ¬http://en.wikipedia.org/wiki/Path_(computing) path¬ |
|
88 list, then the `a href="features#including" code "include";` statement searches these paths. |
|
89 If «YML_PATH» is not set, the local directory «.» is searched for files. |
|
90 >> |
|
91 |
|
92 h2 id=processor > The YML/YSLT processor |
|
93 |
|
94 p >> |
|
95 If you're processing more complex tasks, say, executing an YSLT script over some |
|
96 YML files, the YML/YSLT processor will possible fit better to your needs. |
|
97 >> |
|
98 |
|
99 p >> |
|
100 To use it, enter «yml2proc -y» followed by the filename of your YSLT script, |
|
101 followed by the filenames of your YML input files: |
|
102 >> |
|
103 |
|
104 Code | % yml2proc -y myscript.ysl2 inputfile.yml2 > myscript.result |
|
105 |
|
106 p > The YML/YSLT processor requires the ¬http://codespeak.net/lxml/ lxml Python library¬. |
|
107 |
|
108 p > The YML/YSLT processor has the following options: |
|
109 |
|
110 h3 > -h, --help |
|
111 |
|
112 p > Show a help message and exit. |
|
113 |
|
114 h3 > -C, --old-syntax |
|
115 |
|
116 p > Use the syntax of YML 2 version 1.x (compatibility mode). |
|
117 |
|
118 h3 > -D, --emit-linenumbers |
|
119 |
|
120 p > Emit line numbers into the resulting XML for debugging purposes. |
|
121 |
|
122 h3 id=debug > --debug |
|
123 |
|
124 p >> |
|
125 switch on debug tracing to stderr; this enables the functionality |
|
126 of the ¬yslt#debug debug(msg)¬ and ¬yslt#assert assert yml:assert(test, msg)¬ YSLT functions. |
|
127 >> |
|
128 |
|
129 h3 > -E ENCODING, --encoding ENCODING |
|
130 |
|
131 p > encoding of input files (default: UTF-8) |
|
132 |
|
133 h3 > -I INCLUDE_PATH, --include=INCLUDE_PATH |
|
134 |
|
135 p { "Precede " code > ¬features#ymlpath YML_PATH¬ |
|
136 " by a colon separated " code "INCLUDE_PATH"; " to search for include files." } |
|
137 |
|
138 h3 > -m, --omit-empty-parm-tags |
|
139 |
|
140 p >> |
|
141 Does nothing (only there for compatibility with older versions of «yml2proc»). |
|
142 >> |
|
143 |
|
144 h3 > -M, --empty-input-document |
|
145 |
|
146 p >> |
|
147 Use an empty input document for YSLT or XSLT processing |
|
148 >> |
|
149 |
|
150 h3 > -n NORMALIZATION, --normalization=NORMALIZATION |
|
151 |
|
152 p >> |
|
153 Unicode normalization (none, NFD, NFKD, NFC, NFKC, FCD, default is NFC) |
|
154 >> |
|
155 |
|
156 h3 > -o FILE, --output=FILE |
|
157 |
|
158 p > Don't output to stdout, instead place output in file «FILE». |
|
159 |
|
160 h3 > -p, --parse-only |
|
161 |
|
162 p >> |
|
163 ¬http://fdik.org/pyPEG Parse¬ only, then output ¬http://fdik.org/pyPEG/#pyAST pyAST¬ |
|
164 as text to stdout. The pyAST is the |
|
165 ¬http://en.wikipedia.org/wiki/Abstract_syntax_tree Abstract Syntax Tree¬ |
|
166 of the parsed script as ¬http://docs.python.org/library/stdtypes.html Python data structure¬. |
|
167 >> |
|
168 |
|
169 h3 > -e XPATH, --xpath=XPATH |
|
170 |
|
171 p > Execute XPath expression XPATH and print result |
|
172 |
|
173 p >> |
|
174 If you omit -y YSLTSCRIPT, then the result is printed. If you have an additional |
|
175 -y YSLTSCRIPT parameter, then your YSLT script is processing the result of the |
|
176 XPath expression only instead of processing the complete content of your input documents |
|
177 >> |
|
178 |
|
179 h3 > -P, --pretty |
|
180 |
|
181 p > Pretty print output adding whitespace |
|
182 |
|
183 h3 > -x, --xml |
|
184 |
|
185 p > Input documents are XML already, don't try to convert them from YML |
|
186 |
|
187 h3 > -y YSLTSCRIPT, --yslt=YSLTSCRIPT |
|
188 |
|
189 p > Execute YSLT script YSLTSCRIPT |
|
190 |
|
191 h3 > -X XSLTSCRIPT, --xslt=XSLTSCRIPT |
|
192 |
|
193 p > Execute XSLT script XSLTSCRIPT |
|
194 |
|
195 h3 > -d PARAMS, --paramdict=PARAMS |
|
196 |
|
197 p >> |
|
198 Call XSLT or YSLT script with dictionary PARAMS as XPath parameters. PARAMS is a Python |
|
199 expression which evaluates to a Python dictionary. |
|
200 >> |
|
201 |
|
202 p > Sample: |
|
203 |
|
204 p code > yml2proc -y myscript -d 'dict(a=3, b="element[@name=2]")' |
|
205 |
|
206 h3 > -s STRINGPARAMS, --stringparamdict=STRINGPARAMS |
|
207 |
|
208 p >> |
|
209 Call XSLT or YSLT script with dictionary STRINGPARAMS as string parameters. STRINGPARAMS |
|
210 is a Python expression which evaluates to a Python dictionary. |
|
211 >> |
|
212 |
|
213 p > Sample: |
|
214 |
|
215 p code > yml2proc -y myscript -s 'dict(forename="Hans", name="Meier")' |
|
216 |
|
217 h3 > -Y, --xml2yml |
|
218 |
|
219 p > Convert XML to normalized YML. Equivalent to -xy xml2yml.ysl2 |
|
220 |
|
221 p > The file xml2yml.ysl2 has to be in YML_PATH. |
|
222 |
|
223 h3 > -V, --version |
|
224 |
|
225 p >> |
|
226 Show version and ¬http://en.wikipedia.org/wiki/Copyleft Copyleft¬ information of |
|
227 the YML implementation and exit. |
|
228 >> |
|
229 |
|
230 h3 > YML_PATH environment variable |
|
231 |
|
232 p >> |
|
233 If «YML_PATH» is set to a colon separated ¬http://en.wikipedia.org/wiki/Path_(computing) path¬ |
|
234 list, then the `a href="features#including" code "include";` statement searches these paths. |
|
235 If «YML_PATH» is not set, the local directory «.» is searched for files. |
|
236 >> |
|
237 |
|
238 h2 id=recommended > Recommended external tools |
|
239 |
|
240 h3 > XSLT Processor |
|
241 |
|
242 p >> |
|
243 If you want to use ¬yslt YSLT¬ with «yml2c» instead of «yml2proc», you additionally need an |
|
244 ¬http://www.w3.org/TR/xslt XSLT¬ processor. |
|
245 >> |
|
246 |
|
247 p > For that case, I recommend the ¬http://xmlsoft.org/XSLT/xsltproc2.html xsltproc tool¬. |
|
248 |
|
249 p > To process YSLT, just use a pipe with the «xsltproc» command: |
|
250 |
|
251 Code | % yml2c customer.ysl2 | xsltproc - customer.xml > customer.html |
|
252 |
|
253 h3 > XML Renicing Tool |
|
254 |
|
255 p >> |
|
256 Sometimes, you may want to have more human readable output with «yml2c». So an |
|
257 ¬http://www.w3.org/XML/ XML¬ renicing tool can be helpful. |
|
258 >> |
|
259 |
|
260 p > The ¬http://xmlstar.sourceforge.net/ XMLStarlet¬ command line tool may be of interest. |
|
261 |
|
262 p > Have a look on its «fo» command. |
|
263 |
|
264 h3 > Windows tool chain |
|
265 |
|
266 p >> |
|
267 See also the tips for a |
|
268 ¬http://www.auchdieserschwachsinnmussinsinternet.de/2009-03/#s1236859037 Windows tool chain¬ |
|
269 for YML. |
|
270 >> |
|
271 |
|
272 h1 id=downloads > Downloads |
|
273 |
|
274 p > You can here ¬http://fdik.org/yml2.tar.bz2 download the newest release of YML¬. |
|
275 |
|
276 h2 > Older versions |
|
277 |
|
278 p >> |
|
279 ¬http://fdik.org/yml-2.5.2.tar.bz2 YML 2.5.2¬ |
|
280 >> |
|
281 |
|
282 p >> |
|
283 ¬http://fdik.org/yml-2.5.1.tar.bz2 YML 2.5.1¬ |
|
284 >> |
|
285 |
|
286 p >> |
|
287 ¬http://fdik.org/yml-2.5.0.tar.bz2 YML 2.5.0¬ |
|
288 >> |
|
289 |
|
290 p >> |
|
291 ¬http://fdik.org/yml-2.4.3.tar.bz2 YML 2.4.3¬ |
|
292 >> |
|
293 |
|
294 p >> |
|
295 ¬http://fdik.org/yml-2.3.12.tar.bz2 YML 2.3.12¬ |
|
296 >> |
|
297 |
|
298 p >> |
|
299 ¬http://fdik.org/yml-2.3.11.tar.bz2 YML 2.3.11¬ |
|
300 >> |
|
301 |
|
302 p >> |
|
303 ¬http://fdik.org/yml-2.3.10.tar.bz2 YML 2.3.10¬ |
|
304 >> |
|
305 |
|
306 p >> |
|
307 ¬http://fdik.org/yml-2.3.8.tar.bz2 YML 2.3.8¬ |
|
308 >> |
|
309 |
|
310 p >> |
|
311 ¬http://fdik.org/yml-2.3.7.tar.bz2 YML 2.3.7¬ |
|
312 >> |
|
313 |
|
314 p >> |
|
315 ¬http://fdik.org/yml-2.3.5.tar.bz2 YML 2.3.5¬ |
|
316 >> |
|
317 |
|
318 p >> |
|
319 ¬http://fdik.org/yml-2.2.4.tar.bz2 YML 2.2.4¬ |
|
320 >> |
|
321 |
|
322 p >> |
|
323 ¬http://fdik.org/yml-2.2.3.tar.bz2 YML 2.2.3¬ |
|
324 >> |
|
325 |
|
326 p >> |
|
327 ¬http://fdik.org/yml-2.2.1.tar.bz2 YML 2.2.1¬ |
|
328 >> |
|
329 |
|
330 p >> |
|
331 ¬http://fdik.org/yml-2.2.0.tar.bz2 YML 2.2.0¬ |
|
332 >> |
|
333 |
|
334 p >> |
|
335 ¬http://fdik.org/yml-2.1.17.tar.bz2 YML 2.1.17¬ |
|
336 >> |
|
337 |
|
338 p >> |
|
339 ¬http://fdik.org/yml-2.1.14.tar.bz2 YML 2.1.14¬ |
|
340 >> |
|
341 |
|
342 p >> |
|
343 ¬http://fdik.org/yml-2.1.13.tar.bz2 YML 2.1.13¬ |
|
344 >> |
|
345 |
|
346 p >> |
|
347 ¬http://fdik.org/yml-2.1.12.tar.bz2 YML 2.1.12¬ |
|
348 >> |
|
349 |
|
350 p >> |
|
351 ¬http://fdik.org/yml-2.1.7.tar.bz2 YML 2.1.7¬ |
|
352 >> |
|
353 |
|
354 p >> |
|
355 ¬http://fdik.org/yml-2.1.6.tar.bz2 YML 2.1.6¬ |
|
356 >> |
|
357 |
|
358 p >> |
|
359 ¬http://fdik.org/yml-2.1.5.tar.bz2 YML 2.1.5¬ |
|
360 >> |
|
361 |
|
362 p >> |
|
363 ¬http://fdik.org/yml-2.1.2.tar.bz2 YML 2.1.2¬ |
|
364 >> |
|
365 |
|
366 p >> |
|
367 ¬http://fdik.org/yml-2.0.36.tar.bz2 YML 2.0.36¬ |
|
368 >> |
|
369 p >> |
|
370 ¬http://fdik.org/yml-2.0.35.tar.bz2 YML 2.0.35¬ |
|
371 >> |
|
372 |
|
373 p > ¬http://fdik.org/yml1 To the Homepage of version 1 of YML...¬ |
|
374 |
|
375 div id=bottom { |
|
376 a href="yslt" "<< back to YSLT" " " |
|
377 a href="#top" "^Top^" " " |
|
378 a href="toolchain.en.yhtml2" "(source)" |
|
379 } |
|
380 } |