Annotation of 2002/css-validator/html/Readme.java, revision 1.1
1.1 ! plehegar 1: /*
! 2: * Readme.java
! 3: *
! 4: * $Id$
! 5: *
! 6: * @author Vincent Mallet (Vincent.Mallet@sophia.inria.fr)
! 7: * @version $Revision$
! 8: */
! 9:
! 10: package html;
! 11:
! 12: import html.parser.*; // imports are usefull for "see also" doc tags
! 13: import html.tags.*;
! 14: import html.tree.*;
! 15:
! 16: /**
! 17: * <H2>Introduction</H2>
! 18: *
! 19: * This is the <code>html</code> Package Readme. This is
! 20: * not java code, this is only some docs to help you use this
! 21: * package while using the standard javadoc presentation.<br><br>
! 22: *
! 23: * The <code>html</code> package is a DTD driven HTML parser
! 24: * designed to parse HTML files following specific DTDs and
! 25: * construct corresponding abstract HTML trees that can be
! 26: * used by applications. The parser can also be used directly
! 27: * to avoid the tree construction if necessary.<BR><BR>
! 28:
! 29: * The HTML parser is composed of five different packages:
! 30: * <DL>
! 31:
! 32: * <DT><code>html.css</code>
! 33: * <DD><i>Deprecated.</i> This package was used to parse
! 34: * <A HREF="http://w3c1.inria.fr/TR/REC-CSS1">Cascading
! 35: * Style Sheets level 1</A>. It will soon be replaced by the new CSS
! 36: * parser done by <a href="mailto:Philippe.Le_Hegaret@sophia.inria.fr">
! 37: * Philippe Le Hégaret</a>. Actually not so soon because the
! 38: * values cannot be easily extracted from Philippe's parser properties,
! 39: * so this old-buggy-incorrect css parser will stay there a little
! 40: * while..
! 41:
! 42:
! 43: * <DT><code>html.parser</code>
! 44: * <DD>This is the actual parser, based on the parser done
! 45: * by <A HREF="mailto:avh@eng.sun.com">Arthur Van Hoff</A>
! 46: * from Sun. It does nothing but the actual parsing of the file.
! 47:
! 48: * <DT><code>html.tags</code>
! 49: * <DD>This is the HtmlParser. It is based on top of the parser
! 50: * raw parser and introduces the building of an Html tree and
! 51: * the ParserListener technique. This makes the task of using
! 52: * the Html parser much simpler. It has been written by
! 53: * <a href="mailto:Jean-Michel.Leon@sophia.inria.fr">Jean-Michel
! 54: * Leon</A>, and has been modified by
! 55: * <a href="mailto:Vincent.Mallet@sophia.inria.fr"> Vincent Mallet</A>
! 56: * so as to handle all the CSS data properly (using the CSS
! 57: * parser, see above).
! 58:
! 59: * <DT><code>html.tree</code>
! 60: * <DD>This is the tree built by the HtmlParser. It provides
! 61: * the TreeListener interface so all the tree construction can
! 62: * be followed without modifying or subclassing these classes.
! 63:
! 64: * <DT><code>html.util</code>
! 65: * <DD>Some utility classes.
! 66:
! 67: * </DL>
! 68:
! 69:
! 70: * <H2>Using the HTML Parser</H2>
! 71:
! 72: * Using the HTML parser in your own code should not be
! 73: * something too difficult. You have two ways of doing it:
! 74: * using the listener technique (recommanded), and subclassing
! 75: * the raw parser classes (much work in perspective).
! 76: * Subclassing the raw parser implies the abstract tree will
! 77: * not be constructed during parsing.
! 78:
! 79: * <P><U><I>Using the listeners</I></U>
! 80:
! 81: * <P>This is the easiest way of using the parser. The classes
! 82: * to look at are <code>html.tags.HtmlParser</code>,
! 83: * <code>html.tags.HtmlParserListener</code> and
! 84: * <code>html.tree.TreeListener</code>.
! 85:
! 86: * <UL>
! 87:
! 88: * <LI>First create an instance of the HtmlParser, specifying what
! 89: * DTD to use and what file to parse. The DTDs should be located
! 90: * in the html/parser/dtds directory.
! 91:
! 92: * <LI>Add one (or more) <code>HtmlParserListener</code> to the
! 93: * parser. This <code>HtmlParserListener</code> will be notified
! 94: * of the tree creation and of the end of parsing.
! 95:
! 96:
! 97: * <LI>If you want to use the HTML tree you can do it at two
! 98: * different moments@@CHECKME:
! 99: * <UL>
! 100: * <LI> After the tree has been built. This is the simplest way to
! 101: * go. When the parser is finished, it invokes the method
! 102: * <code>notifyEnd()</code> of the <code>HtmlParserListener</code>
! 103: * interface and the only parameter given is the root of the tree.
! 104: * Just walk the tree the way you like.
! 105: * <LI> While the tree is being constructed. To do this, you have
! 106: * to register a TreeListener when the parser notifies of the creation
! 107: * of the tree root. The TreeListener must be added to the tree root
! 108: * given as a parameter to the <code>notifyCreateRoot</code> method
! 109: * of the <code>HtmlParserListener</code> interface.
! 110: * </UL>
! 111: * </UL>
! 112:
! 113: * <P>Example 1: here's some really simple code that shows how to
! 114: * start the parser in the current thread and parse the content of
! 115: * a web page. The HTML tree built is used at the end of parsing
! 116: * only. See next example to see how to use it while it's being
! 117: * constructed.
! 118:
! 119: * <P><BlockQuote><Pre>
! 120: *
! 121: * public class Sample implements HtmlParserListener { <br>
! 122: *
! 123: * public Sample() {
! 124: * String globaldtd = "html4";
! 125: * String urlname = "http://www.w3.org/";
! 126: * HtmlParser parser;<br>
! 127: *
! 128: * try {
! 129: * parser = new HtmlParser(globaldtd, urlname);
! 130: * }
! 131: * catch(ParserException e) {
! 132: * // The parser could not initialize...
! 133: * // do whatever is appropriate
! 134: * return;
! 135: * } <br>
! 136: *
! 137: * // add a parser listener - us
! 138: * parser.addParserListener(this);<br>
! 139: *
! 140: * // parse the url in the current thread
! 141: * parser.run();<br>
! 142: *
! 143: * // that's all!
! 144: * }<br>
! 145: *
! 146: * public static void main(String args[]) {
! 147: * new Sample();
! 148: * }<br><br>
! 149: *
! 150: *
! 151: * // implements HtmlParserListener<br>
! 152: *
! 153: * public void notifyCreateRoot(URL url, HtmlTag root) {
! 154: * // invoked when the root of the Html tree is created.
! 155: * }<br>
! 156: *
! 157: * public void notifyEnd(HtmlTag root) {
! 158: * // invoked when the parser has finished the job.
! 159: * System.out.println("Wow - parsed the file! root=" + root);
! 160: * }<br>
! 161: *
! 162: * public void notifyConnection(URLConnection cnx) { }
! 163: * public void notifyFatalError(HtmlTag root, Exception x, String s) { }
! 164: * public void notifyActivity(int a, long b) { }<br>
! 165: *
! 166: * }
! 167: *
! 168: * </Pre></BlockQuote>
! 169:
! 170: * <P>Example 2: [Another example here]
! 171:
! 172: * <P><I>Subclassing the parser</I>
! 173: * <P>[Fill Me]
! 174: * <P>[Example here]
! 175:
! 176: * <H2>Copyrights</H2>
! 177: * <P>[Fill Me]
! 178:
! 179: * @see parser
! 180: * @see HtmlParserListener
! 181: * @see TreeListener
! 182: * @see HtmlTree
! 183: *
! 184: * @author Vincent Mallet (Vincent.Mallet@sophia.inria.fr)
! 185: *
! 186: * @version $Revision$
! 187: */
! 188: public abstract class Readme {
! 189: /* This class intentionaly left empty */
! 190:
! 191: /**
! 192: * No, don't read me.. Read the Class description instead :)
! 193: */
! 194: private Readme() { }
! 195: }
Webmaster
![[BACK]](/prx/000/https/dev.w3.org/cvsweb/icons/back.gif,_ANDesc=img,){kind=icon}
Return to Readme.java CVS log ![[TXT]](/prx/000/https/dev.w3.org/cvsweb/icons/text.gif,_ANDesc=img,){kind=icon}
![[DIR]](/prx/000/https/dev.w3.org/cvsweb/icons/dir.gif,_ANDesc=img,){kind=icon}
Up to [Public] / 2002 / css-validator / html