Author: ltheussl
Date: Wed Apr 30 04:07:20 2008
New Revision: 652322
URL: http://svn.apache.org/viewvc?rev=652322&view=rev
Log:
[DOXIA-236] further clarifications and clean-ups
Modified:
maven/doxia/doxia/trunk/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/Sink.java
Modified:
maven/doxia/doxia/trunk/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/Sink.java
URL:
http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/Sink.java?rev=652322&r1=652321&r2=652322&view=diff
==============================================================================
---
maven/doxia/doxia/trunk/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/Sink.java
(original)
+++
maven/doxia/doxia/trunk/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/Sink.java
Wed Apr 30 04:07:20 2008
@@ -130,6 +130,7 @@
/**
* Starts the head element.
+ *
* <p>
* This contains information about the current document, (eg its title)
that is not
* considered document content. The head element is optional but if it
exists, it has to be
@@ -157,14 +158,18 @@
* sink.head_();
* </pre>
* <p>
- * but none of the enclosed events is required.
- * However, if they exist they have to be unique and occur in the order
shown.
+ * but none of the enclosed events is required. However, if they exist
they have to occur
+ * in the order shown, and the title() and date() events have to be
unique (author() events
+ * may occur any number of times).
* </p>
* <p>
- * Supported attributes are: "profile", DIR, LANG.
+ * Supported attributes are:
* </p>
+ * <blockquote>
+ * [EMAIL PROTECTED] SinkEventAttributes#PROFILE PROFILE}, [EMAIL
PROTECTED] SinkEventAttributes#LANG LANG}.
+ * </blockquote>
*
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
*/
void head( SinkEventAttributes attributes );
@@ -182,11 +187,12 @@
/**
* Starts the title element. This is used to identify the document.
+ *
* <p>
* Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes}.
* </p>
*
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
* @see #head(SinkEventAttributes).
*/
void title( SinkEventAttributes attributes );
@@ -197,25 +203,26 @@
void title_();
/**
- * Starts the author element.
+ * Starts an author element.
*
* @see #author(SinkEventAttributes).
*/
void author();
/**
- * Starts the author element. This is used to identify the author of the
document.
+ * Starts an author element. This is used to identify the author of the
document.
+ *
* <p>
- * Supported attributes are: "email".
+ * Supported attributes are: [EMAIL PROTECTED] SinkEventAttributes#EMAIL
EMAIL}.
* </p>
*
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
* @see #head(SinkEventAttributes).
*/
void author( SinkEventAttributes attributes );
/**
- * Ends the author element.
+ * Ends an author element.
*/
void author_();
@@ -228,11 +235,12 @@
/**
* Starts the date element. This is used to identify the date of the
document.
+ *
* <p>
* Supported attributes are: none.
* </p>
*
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
* @see #head(SinkEventAttributes).
*/
void date( SinkEventAttributes attributes );
@@ -251,11 +259,12 @@
/**
* Starts the body of a document. This contains the document's content.
+ *
* <p>
* Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes}.
* </p>
*
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
* @see #head(SinkEventAttributes).
*/
void body( SinkEventAttributes attributes );
@@ -288,8 +297,8 @@
void section1_();
/**
- * Starts a first title heading element.
- * This has to be contained within a [EMAIL PROTECTED] #section1()}
element.
+ * Starts a first title heading element. This element is optional, but if
it exists,
+ * it has to be contained, and be the first element, within a [EMAIL
PROTECTED] #section1()} element.
*
* @see #sectionTitle(int,SinkEventAttributes).
*/
@@ -314,8 +323,8 @@
void section2_();
/**
- * Starts a second title heading element.
- * This has to be contained within a [EMAIL PROTECTED] #section2()}
element.
+ * Starts a second title heading element. This element is optional, but if
it exists,
+ * it has to be contained, and be the first element, within a [EMAIL
PROTECTED] #section2()} element.
*
* @see #sectionTitle(int,SinkEventAttributes).
*/
@@ -340,8 +349,8 @@
void section3_();
/**
- * Starts a third title heading element.
- * This has to be contained within a [EMAIL PROTECTED] #section3()}
element.
+ * Starts a third title heading element. This element is optional, but if
it exists,
+ * it has to be contained, and be the first element, within a [EMAIL
PROTECTED] #section3()} element.
*
* @see #sectionTitle(int,SinkEventAttributes).
*/
@@ -366,8 +375,8 @@
void section4_();
/**
- * Starts a 4th title heading element.
- * This has to be contained within a [EMAIL PROTECTED] #section4()}
element.
+ * Starts a 4th title heading element. This element is optional, but if it
exists,
+ * it has to be contained, and be the first element, within a [EMAIL
PROTECTED] #section4()} element.
*
* @see #sectionTitle(int,SinkEventAttributes).
*/
@@ -392,8 +401,8 @@
void section5_();
/**
- * Starts a 5th title heading element.
- * This has to be contained within a [EMAIL PROTECTED] #section5()}
element.
+ * Starts a 5th title heading element. This element is optional, but if it
exists,
+ * it has to be contained, and be the first element, within a [EMAIL
PROTECTED] #section5()} element.
*
* @see #sectionTitle(int,SinkEventAttributes).
*/
@@ -405,14 +414,17 @@
void sectionTitle5_();
/**
- * Start a new section at the given level. Sections with higher level
should
- * be contained within sections of lower level.
+ * Start a new section at the given level.
+ *
+ * <p>
+ * Sections with higher level have to be entirely contained within
sections of lower level.
+ * </p>
* <p>
* Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes}.
* </p>
*
* @param level the section level.
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
*/
void section( int level, SinkEventAttributes attributes );
@@ -425,12 +437,27 @@
/**
* Start a new section title at the given level.
+ *
* <p>
- * Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes} and ALIGN.
+ * This element is optional, but if it exists, it has to be contained,
and be the first
+ * element, within a corresponding [EMAIL PROTECTED]
#section(int,SinkEventAttributes) section}
+ * element of the same level.
+ * </p>
+ * <p>
+ * <b>NOTE:</b> It is strongly recommended not to make section titles
implicit anchors.
+ * Neither Parsers nor Sinks should insert any content that is not
explicitly present
+ * in the original source document, as this would lead to undefined
behaviour for
+ * multi-format processing chains. However, while Parsers <b>must
never</b> emit anchors
+ * for section titles, some specialised Sinks may implement such a
feature if the resulting
+ * output documents are not going to be further processed (and this is
properly documented).
+ * </p>
+ * <p>
+ * Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes} plus
+ * [EMAIL PROTECTED] SinkEventAttributes#ALIGN ALIGN}.
* </p>
*
* @param level the section title level.
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
*/
void sectionTitle( int level, SinkEventAttributes attributes );
@@ -450,11 +477,12 @@
/**
* Starts an unordered list.
+ *
* <p>
* Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes}.
* </p>
*
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
*/
void list( SinkEventAttributes attributes );
@@ -472,11 +500,12 @@
/**
* Starts a list item element within an unordered list.
+ *
* <p>
* Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes}.
* </p>
*
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
*/
void listItem( SinkEventAttributes attributes );
@@ -495,12 +524,13 @@
/**
* Starts an ordered list element.
+ *
* <p>
* Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes}.
* </p>
*
* @param numbering the numbering style.
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
* @see #NUMBERING_DECIMAL
* @see #NUMBERING_LOWER_ALPHA
* @see #NUMBERING_LOWER_ROMAN
@@ -523,11 +553,12 @@
/**
* Starts a list item element within an ordered list.
+ *
* <p>
* Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes}.
* </p>
*
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
*/
void numberedListItem( SinkEventAttributes attributes );
@@ -545,11 +576,12 @@
/**
* Starts a definition list.
+ *
* <p>
* Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes}.
* </p>
*
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
*/
void definitionList( SinkEventAttributes attributes );
@@ -566,14 +598,17 @@
void definitionListItem();
/**
- * Starts a list item element within a definition list. Every
definitionListItem has to
- * contain exactly one [EMAIL PROTECTED]
#definedTerm(SinkEventAttributes)} and one
- * [EMAIL PROTECTED] #definition(SinkEventAttributes)}, in this order.
+ * Starts a list item element within a definition list.
+ *
+ * <p>
+ * Every definitionListItem has to contain exactly one [EMAIL PROTECTED]
#definedTerm(SinkEventAttributes)}
+ * and one [EMAIL PROTECTED] #definition(SinkEventAttributes)}, in this
order.
+ * </p>
* <p>
* Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes}.
* </p>
*
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
*/
void definitionListItem( SinkEventAttributes attributes );
@@ -591,11 +626,12 @@
/**
* Starts a definition element within a definition list.
+ *
* <p>
* Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes}.
* </p>
*
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
*/
void definition( SinkEventAttributes attributes );
@@ -613,11 +649,12 @@
/**
* Starts a definition term element within a definition list.
+ *
* <p>
* Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes}.
* </p>
*
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
*/
void definedTerm( SinkEventAttributes attributes );
@@ -635,6 +672,7 @@
/**
* Starts a basic image embedding element.
+ *
* <p>
* The canonical sequence of events for the figure element is:
* </p>
@@ -668,7 +706,7 @@
* Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes}.
* </p>
*
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
*/
void figure( SinkEventAttributes attributes );
@@ -686,11 +724,12 @@
/**
* Starts a figure caption.
+ *
* <p>
* Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes}.
* </p>
*
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
* @see #figure(SinkEventAttributes).
*/
void figureCaption( SinkEventAttributes attributes );
@@ -709,6 +748,7 @@
/**
* Adds a graphic element.
+ *
* <p>
* The <code>src</code> parameter should be a valid link, ie it can be
an absolute
* URL or a link relative to the current source document.
@@ -717,15 +757,19 @@
* Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes} plus:
* </p>
* <blockquote>
- * SRC, ALT, WIDTH, HEIGHT, ALIGN, BORDER, HSPACE, VSPACE, ISMAP, USEMAP.
+ * [EMAIL PROTECTED] SinkEventAttributes#SRC SRC}, [EMAIL PROTECTED]
SinkEventAttributes#ALT ALT},
+ * [EMAIL PROTECTED] SinkEventAttributes#WIDTH WIDTH}, [EMAIL PROTECTED]
SinkEventAttributes#HEIGHT HEIGHT},
+ * [EMAIL PROTECTED] SinkEventAttributes#ALIGN ALIGN}, [EMAIL PROTECTED]
SinkEventAttributes#BORDER BORDER},
+ * [EMAIL PROTECTED] SinkEventAttributes#HSPACE HSPACE}, [EMAIL
PROTECTED] SinkEventAttributes#VSPACE VSPACE},
+ * [EMAIL PROTECTED] SinkEventAttributes#ISMAP ISMAP}, [EMAIL PROTECTED]
SinkEventAttributes#USEMAP USEMAP}.
* </blockquote>
* <p>
- * If the [EMAIL PROTECTED] SinkEventAttributes#SRC SRC} attribute is
specified in SinkEventAttributes,
- * it will be overidden by the <code>src</code> parameter.
+ * If the [EMAIL PROTECTED] SinkEventAttributes#SRC SRC} attribute is
specified in SinkEventAttributes,
+ * it will be overidden by the <code>src</code> parameter.
* </p>
*
* @param src the image source, a valid URL.
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
* @see #figure(SinkEventAttributes).
*/
void figureGraphics( String src, SinkEventAttributes attributes );
@@ -739,6 +783,7 @@
/**
* Starts a table.
+ *
* <p>
* The canonical sequence of events for the table element is:
* </p>
@@ -778,10 +823,14 @@
* Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes} plus:
* </p>
* <blockquote>
- * ALIGN, BGCOLOR, BORDER, CELLPADDING, CELLSPACING, "frame", "rules",
"summary", WIDTH.
+ * [EMAIL PROTECTED] SinkEventAttributes#ALIGN ALIGN}, [EMAIL PROTECTED]
SinkEventAttributes#BGCOLOR BGCOLOR},
+ * [EMAIL PROTECTED] SinkEventAttributes#BORDER BORDER}, [EMAIL
PROTECTED] SinkEventAttributes#CELLPADDING CELLPADDING},
+ * [EMAIL PROTECTED] SinkEventAttributes#CELLSPACING CELLSPACING},
[EMAIL PROTECTED] SinkEventAttributes#FRAME FRAME},
+ * [EMAIL PROTECTED] SinkEventAttributes#RULES RULES}, [EMAIL PROTECTED]
SinkEventAttributes#SUMMARY SUMMARY},
+ * [EMAIL PROTECTED] SinkEventAttributes#WIDTH WIDTH}.
* </blockquote>
*
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
*/
void table( SinkEventAttributes attributes );
@@ -817,12 +866,16 @@
/**
* Starts a table row.
+ *
* <p>
* Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes} plus:
* </p>
- * <blockquote>ALIGN, BGCOLOR, VALIGN.</blockquote>
+ * <blockquote>
+ * [EMAIL PROTECTED] SinkEventAttributes#ALIGN ALIGN}, [EMAIL PROTECTED]
SinkEventAttributes#BGCOLOR BGCOLOR},
+ * [EMAIL PROTECTED] SinkEventAttributes#VALIGN VALIGN}.
+ * </blockquote>
*
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
*/
void tableRow( SinkEventAttributes attributes );
@@ -848,13 +901,20 @@
/**
* Starts a table cell.
+ *
* <p>
* Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes} plus:
* </p>
- * <blockquote>"abbrv", ALIGN, "axis", BGCOLOR, COLSPAN, "headers",
- * HEIGHT, NOWRAP, ROWSPAN, "scope", VALIGN, WIDTH.</blockquote>
+ * <blockquote>
+ * [EMAIL PROTECTED] SinkEventAttributes#ABBRV ABBRV}, [EMAIL PROTECTED]
SinkEventAttributes#ALIGN ALIGN},
+ * [EMAIL PROTECTED] SinkEventAttributes#AXIS AXIS}, [EMAIL PROTECTED]
SinkEventAttributes#BGCOLOR BGCOLOR},
+ * [EMAIL PROTECTED] SinkEventAttributes#COLSPAN COLSPAN}, [EMAIL
PROTECTED] SinkEventAttributes#HEADERS HEADERS},
+ * [EMAIL PROTECTED] SinkEventAttributes#HEIGHT HEIGHT}, [EMAIL
PROTECTED] SinkEventAttributes#NOWRAP NOWRAP},
+ * [EMAIL PROTECTED] SinkEventAttributes#ROWSPAN ROWSPAN}, [EMAIL
PROTECTED] SinkEventAttributes#SCOPE SCOPE},
+ * [EMAIL PROTECTED] SinkEventAttributes#VALIGN VALIGN}, [EMAIL
PROTECTED] SinkEventAttributes#WIDTH WIDTH}.
+ * </blockquote>
*
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
*/
void tableCell( SinkEventAttributes attributes );
@@ -880,13 +940,12 @@
/**
* Starts a table header cell.
+ *
* <p>
- * Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes} plus:
+ * Supported attributes are the same as for [EMAIL PROTECTED]
#tableCell(SinkEventAttributes) tableCell}.
* </p>
- * <blockquote>"abbrv", ALIGN, "axis", BGCOLOR, COLSPAN, "headers",
- * HEIGHT, NOWRAP, ROWSPAN, "scope", VALIGN, WIDTH.</blockquote>
*
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
*/
void tableHeaderCell( SinkEventAttributes attributes );
@@ -904,6 +963,7 @@
/**
* Starts a table caption.
+ *
* <p>
* Note that the order of tableCaption and
* [EMAIL PROTECTED] #tableRows(int[],boolean)} events is arbitrary,
@@ -911,10 +971,11 @@
* Implementing sinks should be prepared to handle both possibilities.
* </p>
* <p>
- * Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes} plus ALIGN.
+ * Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes}
+ * plus [EMAIL PROTECTED] SinkEventAttributes#ALIGN ALIGN}.
* </p>
*
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
* @see #table(SinkEventAttributes).
*/
void tableCaption( SinkEventAttributes attributes );
@@ -933,11 +994,13 @@
/**
* Starts a paragraph.
+ *
* <p>
- * Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes} plus ALIGN.
+ * Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes}
+ * plus [EMAIL PROTECTED] SinkEventAttributes#ALIGN ALIGN}.
* </p>
*
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
*/
void paragraph( SinkEventAttributes attributes );
@@ -956,12 +1019,16 @@
/**
* Starts a verbatim block, ie a block where whitespace has semantic
relevance.
+ *
* <p>
* Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes} plus:
* </p>
- * DECORATION (value: "boxed"), ALIGN, WIDTH.
+ * <blockquote>
+ * [EMAIL PROTECTED] SinkEventAttributes#DECORATION DECORATION} (value:
"boxed"),
+ * [EMAIL PROTECTED] SinkEventAttributes#ALIGN ALIGN}, [EMAIL PROTECTED]
SinkEventAttributes#WIDTH WIDTH}.
+ * </blockquote>
*
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
*/
void verbatim( SinkEventAttributes attributes );
@@ -979,12 +1046,16 @@
/**
* Adds a horizontal separator rule.
+ *
* <p>
* Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes} plus:
* </p>
- * ALIGN, NOSHADE, SIZE, WIDTH.
+ * <blockquote>
+ * [EMAIL PROTECTED] SinkEventAttributes#ALIGN ALIGN}, [EMAIL PROTECTED]
SinkEventAttributes#NOSHADE NOSHADE},
+ * [EMAIL PROTECTED] SinkEventAttributes#SIZE SIZE}, [EMAIL PROTECTED]
SinkEventAttributes#WIDTH WIDTH}.
+ * </blockquote>
*
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
*/
void horizontalRule( SinkEventAttributes attributes );
@@ -1003,8 +1074,9 @@
/**
* Starts an element which defines an anchor.
+ *
* <p>
- * The <code>name</code> parameter should be a valid SGML NAME token.
+ * The <code>name</code> parameter has to be a valid SGML NAME token.
* According to the <a
href="http://www.w3.org/TR/html4/types.html#type-name";>
* HTML 4.01 specification section 6.2 SGML basic types</a>:
* </p>
@@ -1019,8 +1091,8 @@
* it will be overwritten by the <code>name</code> parameter.
* </p>
*
- * @param name the name of the anchor. This should be a valid SGML NAME
token.
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param name the name of the anchor. This has to be a valid SGML NAME
token.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
*/
void anchor( String name, SinkEventAttributes attributes );
@@ -1039,8 +1111,9 @@
/**
* Starts a link.
+ *
* <p>
- * The <code>name</code> parameter should be a valid html
<code>href</code>
+ * The <code>name</code> parameter has to be a valid html
<code>href</code>
* parameter, ie for internal links (links to an anchor within the same
source
* document), <code>name</code> should start with the character "#".
* </p>
@@ -1048,7 +1121,11 @@
* Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes} plus:
* </p>
* <blockquote>
- * "charset", COORDS, HREF, "hreflang", REL, REV, SHAPE, TARGET, TYPE.
+ * [EMAIL PROTECTED] SinkEventAttributes#CHARSET CHARSET}, [EMAIL
PROTECTED] SinkEventAttributes#COORDS COORDS},
+ * [EMAIL PROTECTED] SinkEventAttributes#HREF HREF}, [EMAIL PROTECTED]
SinkEventAttributes#HREFLANG HREFLANG},
+ * [EMAIL PROTECTED] SinkEventAttributes#REL REL}, [EMAIL PROTECTED]
SinkEventAttributes#REV REV},
+ * [EMAIL PROTECTED] SinkEventAttributes#SHAPE SHAPE}, [EMAIL PROTECTED]
SinkEventAttributes#TARGET TARGET},
+ * [EMAIL PROTECTED] SinkEventAttributes#TYPE TYPE}.
* </blockquote>
* <p>
* If [EMAIL PROTECTED] SinkEventAttributes#HREF HREF} is specified in
the
@@ -1056,7 +1133,7 @@
* </p>
*
* @param name the name of the link.
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
*/
void link( String name, SinkEventAttributes attributes );
@@ -1074,11 +1151,12 @@
/**
* Starts an italic element.
+ *
* <p>
* Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes}.
* </p>
*
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
*/
void italic( SinkEventAttributes attributes );
@@ -1096,11 +1174,12 @@
/**
* Starts a bold element.
+ *
* <p>
* Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes}.
* </p>
*
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
*/
void bold( SinkEventAttributes attributes );
@@ -1118,11 +1197,12 @@
/**
* Starts a monospaced element.
+ *
* <p>
* Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes}.
* </p>
*
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
*/
void monospaced( SinkEventAttributes attributes );
@@ -1140,11 +1220,16 @@
/**
* Adds a line break.
+ *
* <p>
- * Supported attributes are ID, CLASS, TITLE and STYLE.
+ * Supported attributes are:
* </p>
+ * <blockquote>
+ * [EMAIL PROTECTED] SinkEventAttributes#ID ID}, [EMAIL PROTECTED]
SinkEventAttributes#CLASS CLASS},
+ * [EMAIL PROTECTED] SinkEventAttributes#TITLE TITLE}, [EMAIL PROTECTED]
SinkEventAttributes#STYLE STYLE}.
+ * </blockquote>
*
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
*/
void lineBreak( SinkEventAttributes attributes );
@@ -1163,6 +1248,7 @@
/**
* Adds a text.
+ *
* <p>
* The <code>text</code> parameter should contain only real content, ie
any
* ignorable/collapsable whitespace/EOLs or other pretty-printing should
@@ -1174,12 +1260,13 @@
* </p>
* <p>
* Supported attributes are the [EMAIL PROTECTED] SinkEventAttributes
base attributes}
- * plus VALIGN (values "sub", "sup") and DECORATION (values "underline",
+ * plus [EMAIL PROTECTED] SinkEventAttributes#VALIGN VALIGN} (values
"sub", "sup") and
+ * [EMAIL PROTECTED] SinkEventAttributes#DECORATION DECORATION} (values
"underline",
* "overline", "line-through").
* </p>
*
* @param text The text to write.
- * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}.
+ * @param attributes A set of [EMAIL PROTECTED] SinkEventAttributes}, may
be <code>null</code>.
*/
void text( String text, SinkEventAttributes attributes );
