← Back to branch summary

~ubuntu-branches/ubuntu/maverick/libcommons-digester-java/maverick

« back to all changes in this revision

Viewing changes to src/examples/api/document-markup/readme.txt

  • Committer: Bazaar Package Importer
  • Author(s): Wolfgang Baer
  • Date: 2006-01-15 16:51:19 UTC
  • mfrom: (0.1.2 upstream)
  • Revision ID: james.westby@ubuntu.com-20060115165119-e7cgj3f6o1fmvlg3
Tags: 1.7-2
* Kaffe compiler transition
* Remove Takashi from uploaders to reflect current maintainership

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/examples/api/document-markup/readme.txt
 
1
#########################################################################
 
2
# Copyright 2004 The Apache Software Foundation.
 
3
#  
 
4
# Licensed under the Apache License, Version 2.0 (the "License");
 
5
# you may not use this file except in compliance with the License.
 
6
# You may obtain a copy of the License at
 
7
#  
 
8
#      http://www.apache.org/licenses/LICENSE-2.0
 
9
#  
 
10
# Unless required by applicable law or agreed to in writing, software
 
11
# distributed under the License is distributed on an "AS IS" BASIS,
 
12
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 
13
# See the License for the specific language governing permissions and
 
14
# limitations under the License.
 
15
#########################################################################
 
16
 
 
17
== overview
 
18
 
 
19
The files in this directory are intended as an example of how to use
 
20
the Apache Digester to parse "document-markup" style xml. It also serves as an
 
21
example of how to subclass the main Digester class in order to extend
 
22
its functionality.
 
23
 
 
24
By "document-markup" xml, we mean input like XHTML, where the data is valid
 
25
xml and where some elements contain interleaved text and child elements.
 
26
 
 
27
For example, "<p>Hi, <i>this</i> is some <b>document-style</b> xml.</p>"
 
28
 
 
29
Topics covered:
 
30
* how to subclass digester
 
31
* how to process markup-style xml.
 
32
 
 
33
== compiling and running
 
34
 
 
35
First rename the build.properties.sample file in the parent directory
 
36
to build.properties and edit it to suit your environment. Then in this
 
37
directory:
 
38
 
 
39
* to compile:
 
40
  ant compile
 
41
 
 
42
* to run:
 
43
  ant run
 
44
 
 
45
Alternatively, you can set up your CLASSPATH appropriately, and
 
46
run the example directly. See the build.properties and build.xml
 
47
files for details.
 
48
 
 
49
== Notes
 
50
 
 
51
The primary use of the Digester is to process xml configuration files.
 
52
Such files do not typically interleave text and child elements in the
 
53
style encountered with document markup. The standard Digester behaviour is 
 
54
therefore to accumulate all text within an xml element's body (of which there is
 
55
expected to be only one "segment") and present it to a Rule or user method
 
56
as a single string.
 
57
 
 
58
While this significantly simplifies the implementation of Rule classes for
 
59
the primary Digester goal of parsing configuration files, this process of
 
60
simplifying all text within an element into a single string "loses" critical
 
61
information necessary to correctly parse "document-markup" xml.
 
62
 
 
63
This example shows one method of extending the Digester class to resolve
 
64
this issue..
 
65
 
 
66
At some time the ability to process "document-markup" style xml may be built 
 
67
into the standard Digester class.