README
1This testsuite is used in conjunction with the 'xmlroff-testing'
2package to test xmlroff.
3
4This is part of the xmlroff XSL Formatter project.
5
6-----------------------------------------------------------------------
7xmlroff is a fast, free, high-quality, multi-platform XSL formatter
8that aims to excel at DocBook formatting and that integrates easily
9with other programs and with scripting languages.
10
11The xmlroff XSL Formatter is a library -- libfo -- and a command-line
12program -- xmlroff -- for formatting XML according to the XSL 1.0
13Recommendation.
14
15See http://xmlroff.org/.
16-----------------------------------------------------------------------
17
18The version numbers of 'testsuite' releases are the same as the
19version of xmlroff that is current at the time of the 'testsuite'
20release. However, any version of this package may be used with any
21version of xmlroff, although using the newest 'testsuite' version is
22recommended since new versions tend to have more tests, bug fixes and,
23occasionally, better documentation.
24
25
26Structure
27=========
28
29The directory structure, and the <testcases> structure in
30testsuite.xml, mostly mirrors the section structure of the XSL 1.0
31Recommendation. There's also additional 'structure' and 'multiple'
32directories for tests that don't fit into the divisions within the XSL
33spec.
34
35
36testsuite.xml
37=============
38
39This conforms to the DTD for testsuites developed for the Candidate
40Recommendation phase testing of the XSL 1.0 spec.
41
42Every test is described by a <test> element.
43
44<test> elements are grouped into <testcases> elements, which may also
45be grouped into another <testcases> element or the overall <testsuite>
46element.
47
48Every test should have a unique id.
49
50
51Writing a new test
52==================
53
54 - Add the test to testsuite.xml.
55
56 - Test one FO or property per test.
57
58 - Try to include a block of text explaining what the test tests.
59
60 - Try to use yellow and gray for the 'color' and 'background-color'
61 properties (or vice-versa) so you can see the extent of blocks.
62
63 - It's okay to write tests that are expected to fail even when the FO
64 or property is implemented correctly. Just make sure the
65 description in testsuite.xml makes it clear that the test is
66 expected to fail.
67
68 - Except when testing non-basic properties, use properties from the
69 'basic' conformance level in preference to using shorthands,
70 whenever possible.
71
72 Even when xmlroff supports a shorthand, you don't want to be also
73 testing xmlroff's shorthand support when you're testing another FO
74 or property, plus using 'basic' properties makes the testsuite more
75 useful for other XSL formatters that may not implement the same set
76 of shorthands as xmlroff does.
77
78 - Keep the test simple.
79
80 - If you can't keep the test simple, put it in the 'multiple'
81 directory and testcases.
82
83 - Use 8in x 11in paper size so the result isn't shrunk if it's
84 printed on either A4 or letter size paper.
85
86
87License
88=======
89
90The stylesheets and other content are licensed under a BSD-style
91license. See the file COPYING for details.
92
93
94Tony Graham
9512 July 2007
96
97