1 package org.apache.maven.doxia.sink;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import org.apache.maven.doxia.logging.LogEnabled;
23
24 /**
25 * A <i>Sink</i> consumes Doxia events to produce a resultant output format
26 * (eg Docbook, PDF, XHTML...).
27 * <p>
28 * Doxia allows you to transform any supported input document format (ie for which a Parser exists)
29 * into any supported output document format (ie for which a Sink exists).
30 * </p>
31 * <p>
32 * A parser is responsible for reading an input document and emitting a sequence of Doxia events
33 * which can then be consumed by a Doxia Sink. Thus, you can parse any front- end format
34 * (eg APT, FML, Xdoc, ...) and have them all contribute to a final XHTML version of a web site.
35 * All documents being parsed result in a stream of Doxia events (eg paragraph, bold, italic,
36 * text,...), which are then fed into a XHTML Sink to produce a set of XHTML pages.
37 * </p>
38 * <p>
39 * A Sink is ultimately responsible for the final format and structure of the output document.
40 * For example, you can take a collection of APT documents, let a Parser emit a series of Doxia
41 * events and have that be fed into a Sink to produce a single PDF, a book, a site, or a
42 * Word document. The Sink is fully responsible for the final output.
43 * </p>
44 * <p>
45 * You can easily integrate any custom (XML, Wiki,...) format by creating a Doxia Parser which
46 * reads your input document and produces a proper sequence of Doxia events.
47 * Those can then be fed into an arbitrary Sink to produce any desired final output.
48 * </p>
49 * <p>
50 * <b>Note</b>: All implemented sink <b>should</b> use UTF-8 as encoding.
51 * </p>
52 *
53 * @since 1.0-alpha-6
54 * @author <a href="mailto:jason@maven.org">Jason van Zyl</a>
55 * @author <a href="mailto:vincent.siveton@gmail.com">Vincent Siveton</a>
56 * @author ltheussl
57 */
58 public interface Sink
59 extends LogEnabled
60 {
61 /** The Plexus Sink Role. */
62 String ROLE = Sink.class.getName();
63
64 /**
65 * A numbering to handle a number list.
66 * @see #numberedList(int,SinkEventAttributes)
67 */
68 int NUMBERING_DECIMAL = 0;
69
70 /**
71 * A numbering to handle a lower alpha list.
72 * @see #numberedList(int,SinkEventAttributes)
73 */
74 int NUMBERING_LOWER_ALPHA = 1;
75
76 /**
77 * A numbering to handle a upper alpha list.
78 * @see #numberedList(int,SinkEventAttributes)
79 */
80 int NUMBERING_UPPER_ALPHA = 2;
81
82 /**
83 * A numbering to handle a lower roman list.
84 * @see #numberedList(int,SinkEventAttributes)
85 */
86 int NUMBERING_LOWER_ROMAN = 3;
87
88 /**
89 * A numbering to handle a upper roman list.
90 * @see #numberedList(int,SinkEventAttributes)
91 */
92 int NUMBERING_UPPER_ROMAN = 4;
93
94 /**
95 * A level 1 section (section).
96 * @see #section(int,SinkEventAttributes)
97 */
98 int SECTION_LEVEL_1 = 1;
99
100 /**
101 * A level 2 section (subsection).
102 * @see #section(int,SinkEventAttributes)
103 */
104 int SECTION_LEVEL_2 = 2;
105
106 /**
107 * A level 3 section (sub-subsection).
108 * @see #section(int,SinkEventAttributes)
109 */
110 int SECTION_LEVEL_3 = 3;
111
112 /**
113 * A level 4 section (sub-sub-subsection).
114 * @see #section(int,SinkEventAttributes)
115 */
116 int SECTION_LEVEL_4 = 4;
117
118 /**
119 * A level 5 section (sub-sub-sub-subsection).
120 * @see #section(int,SinkEventAttributes)
121 */
122 int SECTION_LEVEL_5 = 5;
123
124 /**
125 * A level 5 section (sub-sub-sub-subsection).
126 * @see #section(int,SinkEventAttributes)
127 */
128 int SECTION_LEVEL_6 = 6;
129
130 /**
131 * Center alignment for table cells.
132 * @see #tableRows(int[], boolean)
133 */
134 int JUSTIFY_CENTER = 0;
135
136 /**
137 * Left alignment for table cells.
138 * @see #tableRows(int[], boolean)
139 */
140 int JUSTIFY_LEFT = 1;
141
142 /**
143 * Right alignment for table cells.
144 * @see #tableRows(int[], boolean)
145 */
146 int JUSTIFY_RIGHT = 2;
147
148 /**
149 * Starts the head element.
150 *
151 * @see #head(SinkEventAttributes)
152 */
153 void head();
154
155 /**
156 * Starts the head element.
157 *
158 * <p>
159 * This contains information about the current document, (eg its title) that is not
160 * considered document content. The head element is optional but if it exists, it has to be
161 * unique within a sequence of Sink events that produces one output document, and it has
162 * to come before the {@link #body(SinkEventAttributes)} element.
163 * </p>
164 * <p>
165 * The canonical sequence of events for the head element is:
166 * </p>
167 * <pre>
168 * sink.head();
169 *
170 * sink.title();
171 * sink.text( "Title" );
172 * sink.title_();
173 *
174 * sink.author();
175 * sink.text( "Author" );
176 * sink.author_();
177 *
178 * sink.date();
179 * sink.text( "Date" );
180 * sink.date_();
181 *
182 * sink.head_();
183 * </pre>
184 * <p>
185 * but none of the enclosed events is required. However, if they exist they have to occur
186 * in the order shown, and the title() and date() events have to be unique (author() events
187 * may occur any number of times).
188 * </p>
189 * <p>
190 * Supported attributes are:
191 * </p>
192 * <blockquote>
193 * {@link SinkEventAttributes#PROFILE PROFILE}, {@link SinkEventAttributes#LANG LANG}.
194 * </blockquote>
195 *
196 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
197 * @since 1.1
198 */
199 void head( SinkEventAttributes attributes );
200
201 /**
202 * Ends the head element.
203 */
204 void head_();
205
206 /**
207 * Starts the title element.
208 *
209 * @see #title(SinkEventAttributes)
210 */
211 void title();
212
213 /**
214 * Starts the title element. This is used to identify the document.
215 *
216 * <p>
217 * Supported attributes are the {@link SinkEventAttributes base attributes}.
218 * </p>
219 *
220 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
221 * @since 1.1
222 * @see #head(SinkEventAttributes)
223 */
224 void title( SinkEventAttributes attributes );
225
226 /**
227 * Ends the title element.
228 */
229 void title_();
230
231 /**
232 * Starts an author element.
233 *
234 * @see #author(SinkEventAttributes)
235 */
236 void author();
237
238 /**
239 * Starts an author element. This is used to identify the author of the document.
240 *
241 * <p>
242 * Supported attributes are: {@link SinkEventAttributes#EMAIL EMAIL}.
243 * </p>
244 *
245 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
246 * @since 1.1
247 * @see #head(SinkEventAttributes)
248 */
249 void author( SinkEventAttributes attributes );
250
251 /**
252 * Ends an author element.
253 */
254 void author_();
255
256 /**
257 * Starts the date element.
258 *
259 * @see #date(SinkEventAttributes)
260 */
261 void date();
262
263 /**
264 * Starts the date element. This is used to identify the date of the document: there is no strict definition
265 * if it is <b>creation date</b> or <b>last modification date</b>, which are the 2 classical semantics.
266 * There is no formal formatting requirements either.
267 * <br>
268 * The date is recommended (but it is not a requirement) to be aligned to the
269 * <a href="http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=26780">ISO-8601</a>
270 * standard, i.e.:
271 * <pre>YYYY-MM-DD</pre>
272 * where
273 * <ul>
274 * <li><code>YYYY</code> is the year in the Gregorian calendar,</li>
275 * <li><code>MM</code> is the month of the year between 01 (January) and 12 (December),</li>
276 * <li>and <code>DD</code> is the day of the month between 01 and 31.</li>
277 * </ul>
278 *
279 * <p>
280 * Supported attributes are: none.
281 * </p>
282 *
283 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
284 * @since 1.1
285 * @see #head(SinkEventAttributes)
286 */
287 void date( SinkEventAttributes attributes );
288
289 /**
290 * Ends the date element.
291 */
292 void date_();
293
294 /**
295 * Starts the body of a document.
296 *
297 * @see #body(SinkEventAttributes)
298 */
299 void body();
300
301 /**
302 * Starts the body of a document. This contains the document's content.
303 *
304 * <p>
305 * Supported attributes are the {@link SinkEventAttributes base attributes}.
306 * </p>
307 *
308 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
309 * @since 1.1
310 * @see #head(SinkEventAttributes)
311 */
312 void body( SinkEventAttributes attributes );
313
314 /**
315 * Ends the body element.
316 */
317 void body_();
318
319 /**
320 * Starts an article within a document.
321 *
322 * @see #article(SinkEventAttributes)
323 */
324 void article();
325
326 /**
327 * Starts an article within a document.
328 *
329 * <p>
330 * Supported attributes are the {@link SinkEventAttributes base attributes}.
331 * </p>
332 *
333 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
334 * @since 2.0
335 */
336 void article( SinkEventAttributes attributes );
337
338 /**
339 * Ends the article element.
340 */
341 void article_();
342
343 /**
344 * Starts a navigation section within a document.
345 *
346 * @see #navigation(SinkEventAttributes)
347 */
348 void navigation();
349
350 /**
351 * Starts a navigation section within a document.
352 *
353 * <p>
354 * Supported attributes are the {@link SinkEventAttributes base attributes}.
355 * </p>
356 *
357 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
358 * @since 2.0
359 * @see #navigation(SinkEventAttributes)
360 */
361 void navigation( SinkEventAttributes attributes );
362
363 /**
364 * Ends the navigation element.
365 */
366 void navigation_();
367
368 /**
369 * Starts a sidebar section within a document.
370 *
371 * @see #sidebar(SinkEventAttributes)
372 */
373 void sidebar();
374
375 /**
376 * Starts a sidebar section within a document.
377 *
378 * <p>
379 * Supported attributes are the {@link SinkEventAttributes base attributes}.
380 * </p>
381 *
382 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
383 * @since 2.0
384 */
385 void sidebar( SinkEventAttributes attributes );
386
387 /**
388 * Ends the sidebar element.
389 */
390 void sidebar_();
391
392 /**
393 * Starts a title heading element.
394 */
395 void sectionTitle();
396
397 /**
398 * Ends a title heading element.
399 */
400 void sectionTitle_();
401
402 /**
403 * Starts a first heading element which contains the topic of the section.
404 *
405 * @see #section(int,SinkEventAttributes)
406 */
407 void section1();
408
409 /**
410 * Ends a first heading element.
411 */
412 void section1_();
413
414 /**
415 * Starts a first title heading element. This element is optional, but if it exists,
416 * it has to be contained, and be the first element, within a {@link #section1()} element.
417 *
418 * @see #sectionTitle(int,SinkEventAttributes)
419 */
420 void sectionTitle1();
421
422 /**
423 * Ends a first title heading element.
424 */
425 void sectionTitle1_();
426
427 /**
428 * Starts a second heading element which contains the topic of the section.
429 * This has to be contained within a {@link #section1()} element.
430 *
431 * @see #section(int,SinkEventAttributes)
432 */
433 void section2();
434
435 /**
436 * Ends a second heading element.
437 */
438 void section2_();
439
440 /**
441 * Starts a second title heading element. This element is optional, but if it exists,
442 * it has to be contained, and be the first element, within a {@link #section2()} element.
443 *
444 * @see #sectionTitle(int,SinkEventAttributes)
445 */
446 void sectionTitle2();
447
448 /**
449 * Ends a second title heading element.
450 */
451 void sectionTitle2_();
452
453 /**
454 * Starts a third heading element which contains the topic of the section.
455 * This has to be contained within a {@link #section2()} element.
456 *
457 * @see #section(int,SinkEventAttributes)
458 */
459 void section3();
460
461 /**
462 * Ends a third heading element.
463 */
464 void section3_();
465
466 /**
467 * Starts a third title heading element. This element is optional, but if it exists,
468 * it has to be contained, and be the first element, within a {@link #section3()} element.
469 *
470 * @see #sectionTitle(int,SinkEventAttributes)
471 */
472 void sectionTitle3();
473
474 /**
475 * Ends a third title heading element.
476 */
477 void sectionTitle3_();
478
479 /**
480 * Starts a 4th heading element which contains the topic of the section.
481 * This has to be contained within a {@link #section3()} element.
482 *
483 * @see #section(int,SinkEventAttributes)
484 */
485 void section4();
486
487 /**
488 * Ends a 4th heading element.
489 */
490 void section4_();
491
492 /**
493 * Starts a 4th title heading element. This element is optional, but if it exists,
494 * it has to be contained, and be the first element, within a {@link #section4()} element.
495 *
496 * @see #sectionTitle(int,SinkEventAttributes)
497 */
498 void sectionTitle4();
499
500 /**
501 * Ends a 4th title heading element.
502 */
503 void sectionTitle4_();
504
505 /**
506 * Starts a 5th heading element which contains the topic of the section.
507 * This has to be contained within a {@link #section4()} element.
508 *
509 * @see #section(int,SinkEventAttributes)
510 */
511 void section5();
512
513 /**
514 * Ends a 5th heading element.
515 */
516 void section5_();
517
518 /**
519 * Starts a 5th title heading element. This element is optional, but if it exists,
520 * it has to be contained, and be the first element, within a {@link #section5()} element.
521 *
522 * @see #sectionTitle(int,SinkEventAttributes)
523 */
524 void sectionTitle5();
525
526 /**
527 * Ends a 5th title heading element.
528 */
529 void sectionTitle5_();
530
531 /**
532 * Starts a 6th heading element which contains the topic of the section.
533 * This has to be contained within a {@link #section5()} element.
534 *
535 * @see #section(int,SinkEventAttributes)
536 * @since 1.7
537 */
538 void section6();
539
540 /**
541 * Ends a 6th heading element.
542 *
543 * @since 1.7
544 */
545 void section6_();
546
547 /**
548 * Starts a 6th title heading element. This element is optional, but if it exists,
549 * it has to be contained, and be the first element, within a {@link #section6()} element.
550 *
551 * @see #sectionTitle(int,SinkEventAttributes)
552 * @since 1.7
553 */
554 void sectionTitle6();
555
556 /**
557 * Ends a 6th title heading element.
558 *
559 * @since 1.7
560 */
561 void sectionTitle6_();
562
563 /**
564 * Start a new section at the given level.
565 *
566 * <p>
567 * Sections with higher level have to be entirely contained within sections of lower level.
568 * </p>
569 * <p>
570 * Supported attributes are the {@link SinkEventAttributes base attributes}.
571 * </p>
572 *
573 * @param level the section level.
574 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
575 * @since 1.1
576 */
577 void section( int level, SinkEventAttributes attributes );
578
579 /**
580 * Ends a section at the given level.
581 *
582 * @param level the section level.
583 * @since 1.1
584 */
585 void section_( int level );
586
587 /**
588 * Start a new section title at the given level.
589 *
590 * <p>
591 * This element is optional, but if it exists, it has to be contained, and be the first
592 * element, within a corresponding {@link #section(int,SinkEventAttributes) section}
593 * element of the same level.
594 * </p>
595 * <p>
596 * <b>NOTE:</b> It is strongly recommended not to make section titles implicit anchors.
597 * Neither Parsers nor Sinks should insert any content that is not explicitly present
598 * in the original source document, as this would lead to undefined behaviour for
599 * multi-format processing chains. However, while Parsers <b>must never</b> emit anchors
600 * for section titles, some specialized Sinks may implement such a feature if the resulting
601 * output documents are not going to be further processed (and this is properly documented).
602 * </p>
603 * <p>
604 * Supported attributes are the {@link SinkEventAttributes base attributes} plus
605 * {@link SinkEventAttributes#ALIGN ALIGN}.
606 * </p>
607 *
608 * @param level the section title level.
609 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
610 * @since 1.1
611 */
612 void sectionTitle( int level, SinkEventAttributes attributes );
613
614 /**
615 * Ends a section title at the given level.
616 *
617 * @param level the section title level.
618 * @since 1.1
619 */
620 void sectionTitle_( int level );
621
622 /**
623 * Start a new header within the section or body.
624 */
625 void header();
626
627 /**
628 * Start a new header within the section or body.
629 *
630 * <p>
631 * Supported attributes are the {@link SinkEventAttributes base attributes}.
632 * </p>
633 *
634 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
635 * @since 2.0
636 */
637 void header( SinkEventAttributes attributes );
638
639 /**
640 * Ends a header element.
641 */
642 void header_();
643
644 /**
645 * Start the main content section between the header and the
646 * footer within the sections and/or body.
647 */
648 void content();
649
650 /**
651 * Start the main content section between the header and the
652 * footer within the sections and/or body.
653 *
654 * <p>
655 * Supported attributes are the {@link SinkEventAttributes base attributes}.
656 * </p>
657 *
658 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
659 * @since 2.0
660 */
661 void content( SinkEventAttributes attributes );
662
663 /**
664 * Ends a main content section.
665 */
666 void content_();
667
668 /**
669 * Start a new footer within the section or body.
670 */
671 void footer();
672
673 /**
674 * Start a new footer within the section or body.
675 *
676 * <p>
677 * Supported attributes are the {@link SinkEventAttributes base attributes}.
678 * </p>
679 *
680 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
681 * @since 2.0
682 */
683 void footer( SinkEventAttributes attributes );
684
685 /**
686 * Ends a footer element.
687 */
688 void footer_();
689
690 /**
691 * Starts an unordered list element.
692 *
693 * @see #list(SinkEventAttributes)
694 */
695 void list();
696
697 /**
698 * Starts an unordered list.
699 *
700 * <p>
701 * Supported attributes are the {@link SinkEventAttributes base attributes}.
702 * </p>
703 *
704 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
705 * @since 1.1
706 */
707 void list( SinkEventAttributes attributes );
708
709 /**
710 * Ends an unordered list element.
711 */
712 void list_();
713
714 /**
715 * Starts a list item element within an unordered list.
716 *
717 * @see #listItem(SinkEventAttributes)
718 */
719 void listItem();
720
721 /**
722 * Starts a list item element within an unordered list.
723 *
724 * <p>
725 * Supported attributes are the {@link SinkEventAttributes base attributes}.
726 * </p>
727 *
728 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
729 * @since 1.1
730 */
731 void listItem( SinkEventAttributes attributes );
732
733 /**
734 * Ends a list item element within an unordered list.
735 */
736 void listItem_();
737
738 /**
739 * Starts an ordered list element.
740 *
741 * @param numbering the numbering style.
742 * @see #numberedList(int,SinkEventAttributes)
743 */
744 void numberedList( int numbering );
745
746 /**
747 * Starts an ordered list element.
748 *
749 * <p>
750 * Supported attributes are the {@link SinkEventAttributes base attributes}.
751 * </p>
752 *
753 * @param numbering the numbering style.
754 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
755 * @since 1.1
756 * @see #NUMBERING_DECIMAL
757 * @see #NUMBERING_LOWER_ALPHA
758 * @see #NUMBERING_LOWER_ROMAN
759 * @see #NUMBERING_UPPER_ALPHA
760 * @see #NUMBERING_UPPER_ROMAN
761 */
762 void numberedList( int numbering, SinkEventAttributes attributes );
763
764 /**
765 * Ends an ordered list element.
766 */
767 void numberedList_();
768
769 /**
770 * Starts a list item element within an ordered list.
771 *
772 * @see #numberedListItem(SinkEventAttributes)
773 */
774 void numberedListItem();
775
776 /**
777 * Starts a list item element within an ordered list.
778 *
779 * <p>
780 * Supported attributes are the {@link SinkEventAttributes base attributes}.
781 * </p>
782 *
783 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
784 * @since 1.1
785 */
786 void numberedListItem( SinkEventAttributes attributes );
787
788 /**
789 * Ends a list item element within an ordered list.
790 */
791 void numberedListItem_();
792
793 /**
794 * Starts a definition list element.
795 *
796 * @see #definitionList(SinkEventAttributes)
797 */
798 void definitionList();
799
800 /**
801 * Starts a definition list.
802 *
803 * <p>
804 * Supported attributes are the {@link SinkEventAttributes base attributes}.
805 * </p>
806 *
807 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
808 * @since 1.1
809 */
810 void definitionList( SinkEventAttributes attributes );
811
812 /**
813 * Ends a definition list element.
814 */
815 void definitionList_();
816
817 /**
818 * Starts a list item element within a definition list.
819 *
820 * @see #definitionListItem(SinkEventAttributes)
821 */
822 void definitionListItem();
823
824 /**
825 * Starts a list item element within a definition list.
826 *
827 * <p>
828 * Every definitionListItem has to contain exactly one {@link #definedTerm(SinkEventAttributes)}
829 * and one {@link #definition(SinkEventAttributes)}, in this order.
830 * </p>
831 * <p>
832 * Supported attributes are the {@link SinkEventAttributes base attributes}.
833 * </p>
834 *
835 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
836 * @since 1.1
837 */
838 void definitionListItem( SinkEventAttributes attributes );
839
840 /**
841 * Ends a list item element within a definition list.
842 */
843 void definitionListItem_();
844
845 /**
846 * Starts a definition element within a definition list.
847 *
848 * @see #definition(SinkEventAttributes)
849 */
850 void definition();
851
852 /**
853 * Starts a definition element within a definition list.
854 *
855 * <p>
856 * Supported attributes are the {@link SinkEventAttributes base attributes}.
857 * </p>
858 *
859 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
860 * @since 1.1
861 */
862 void definition( SinkEventAttributes attributes );
863
864 /**
865 * Ends a definition element within a definition list.
866 */
867 void definition_();
868
869 /**
870 * Starts a definition term element within a definition list.
871 *
872 * @see #definedTerm(SinkEventAttributes)
873 */
874 void definedTerm();
875
876 /**
877 * Starts a definition term element within a definition list.
878 *
879 * <p>
880 * Supported attributes are the {@link SinkEventAttributes base attributes}.
881 * </p>
882 *
883 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
884 * @since 1.1
885 */
886 void definedTerm( SinkEventAttributes attributes );
887
888 /**
889 * Ends a definition term element within a definition list.
890 */
891 void definedTerm_();
892
893 /**
894 * Starts a basic image embedding element.
895 *
896 * @see #figure(SinkEventAttributes)
897 */
898 void figure();
899
900 /**
901 * Starts a basic image embedding element.
902 *
903 * <p>
904 * The canonical sequence of events for the figure element is:
905 * </p>
906 * <pre>
907 * sink.figure();
908 *
909 * sink.figureGraphics( "figure.png" );
910 *
911 * sink.figureCaption();
912 * sink.text( "Figure caption",);
913 * sink.figureCaption_();
914 *
915 * sink.figure_();
916 * </pre>
917 * <p>
918 * where the figureCaption element is optional.
919 * </p>
920 * <p>
921 * However, <strong>NOTE</strong> that the order of figureCaption and
922 * figureGraphics events is arbitrary,
923 * ie a parser may emit the figureCaption before or after the figureGraphics.
924 * Implementing sinks should be prepared to handle both possibilities.
925 * </p>
926 * <p>
927 * <strong>NOTE</strong> also that the figureGraphics() event does not have to be embedded
928 * inside figure(), in particular for in-line images the figureGraphics() should be used
929 * stand-alone (in HTML language, figureGraphics() produces a <code><img></code>
930 * tag, while figure() opens a paragraph- or <code><div></code>- like environment).
931 * </p>
932 * <p>
933 * Supported attributes are the {@link SinkEventAttributes base attributes}.
934 * </p>
935 *
936 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
937 * @since 1.1
938 */
939 void figure( SinkEventAttributes attributes );
940
941 /**
942 * Ends a basic image embedding element.
943 */
944 void figure_();
945
946 /**
947 * Starts a caption of an image element.
948 *
949 * @see #figureCaption(SinkEventAttributes)
950 */
951 void figureCaption();
952
953 /**
954 * Starts a figure caption.
955 *
956 * <p>
957 * Supported attributes are the {@link SinkEventAttributes base attributes}.
958 * </p>
959 *
960 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
961 * @since 1.1
962 * @see #figure(SinkEventAttributes)
963 */
964 void figureCaption( SinkEventAttributes attributes );
965
966 /**
967 * Ends a caption of an image.
968 */
969 void figureCaption_();
970
971 /**
972 * Adding a source of a graphic.
973 *
974 * @param name the source
975 */
976 void figureGraphics( String name );
977
978 /**
979 * Adds a graphic element.
980 *
981 * <p>
982 * The <code>src</code> parameter should be a valid link, ie it can be an absolute
983 * URL or a link relative to the current source document.
984 * </p>
985 * <p>
986 * Supported attributes are the {@link SinkEventAttributes base attributes} plus:
987 * </p>
988 * <blockquote>
989 * {@link SinkEventAttributes#SRC SRC}, {@link SinkEventAttributes#ALT ALT},
990 * {@link SinkEventAttributes#WIDTH WIDTH}, {@link SinkEventAttributes#HEIGHT HEIGHT},
991 * {@link SinkEventAttributes#ALIGN ALIGN}, {@link SinkEventAttributes#BORDER BORDER},
992 * {@link SinkEventAttributes#HSPACE HSPACE}, {@link SinkEventAttributes#VSPACE VSPACE},
993 * {@link SinkEventAttributes#ISMAP ISMAP}, {@link SinkEventAttributes#USEMAP USEMAP}.
994 * </blockquote>
995 * <p>
996 * If the {@link SinkEventAttributes#SRC SRC} attribute is specified in SinkEventAttributes,
997 * it will be overridden by the <code>src</code> parameter.
998 * </p>
999 *
1000 * @param src the image source, a valid URL.
1001 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1002 * @since 1.1
1003 * @see #figure(SinkEventAttributes)
1004 */
1005 void figureGraphics( String src, SinkEventAttributes attributes );
1006
1007 /**
1008 * Starts a table element for marking up tabular information in a document.
1009 *
1010 * @see #table(SinkEventAttributes)
1011 */
1012 void table();
1013
1014 /**
1015 * Starts a table.
1016 *
1017 * <p>
1018 * The canonical sequence of events for the table element is:
1019 * </p>
1020 * <pre>
1021 * sink.table();
1022 *
1023 * sink.tableRows( justify, true );
1024 *
1025 * sink.tableRow();
1026 * sink.tableCell();
1027 * sink.text( "cell 1,1" );
1028 * sink.tableCell_();
1029 * sink.tableCell();
1030 * sink.text( "cell 1,2" );
1031 * sink.tableCell_();
1032 * sink.tableRow_();
1033 *
1034 * sink.tableRows_();
1035 *
1036 * sink.tableCaption();
1037 * sink.text( "Table caption" );
1038 * sink.tableCaption_();
1039 *
1040 * sink.table_();
1041 *
1042 * </pre>
1043 * <p>
1044 * where the tableCaption element is optional.
1045 * </p>
1046 * <p>
1047 * However, <strong>NOTE</strong> that the order of tableCaption and
1048 * {@link #tableRows(int[],boolean)} events is arbitrary,
1049 * ie a parser may emit the tableCaption before or after the tableRows.
1050 * Implementing sinks should be prepared to handle both possibilities.
1051 * </p>
1052 * <p>
1053 * Supported attributes are the {@link SinkEventAttributes base attributes} plus:
1054 * </p>
1055 * <blockquote>
1056 * {@link SinkEventAttributes#ALIGN ALIGN}, {@link SinkEventAttributes#BGCOLOR BGCOLOR},
1057 * {@link SinkEventAttributes#BORDER BORDER}, {@link SinkEventAttributes#CELLPADDING CELLPADDING},
1058 * {@link SinkEventAttributes#CELLSPACING CELLSPACING}, {@link SinkEventAttributes#FRAME FRAME},
1059 * {@link SinkEventAttributes#RULES RULES}, {@link SinkEventAttributes#SUMMARY SUMMARY},
1060 * {@link SinkEventAttributes#WIDTH WIDTH}.
1061 * </blockquote>
1062 *
1063 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1064 * @since 1.1
1065 */
1066 void table( SinkEventAttributes attributes );
1067
1068 /**
1069 * Ends a table element.
1070 */
1071 void table_();
1072
1073 /**
1074 * Starts an element that contains rows of table data.
1075 *
1076 * @param justification the default justification of columns.
1077 * This can be overridden by individual table rows or table cells.
1078 * If null a left alignment is assumed by default. If this array
1079 * has less elements than there are columns in the table then the value of
1080 * the last array element will be taken as default for the remaining table cells.
1081 * @param grid true to provide a grid, false otherwise.
1082 * @see #table(SinkEventAttributes)
1083 * @see #JUSTIFY_CENTER
1084 * @see #JUSTIFY_LEFT
1085 * @see #JUSTIFY_RIGHT
1086 */
1087 void tableRows( int[] justification, boolean grid );
1088
1089 /**
1090 * Ends an element that contains rows of table data.
1091 */
1092 void tableRows_();
1093
1094 /**
1095 * Starts a row element which acts as a container for a row of table cells.
1096 *
1097 * @see #tableRow(SinkEventAttributes)
1098 */
1099 void tableRow();
1100
1101 /**
1102 * Starts a table row.
1103 *
1104 * <p>
1105 * Supported attributes are the {@link SinkEventAttributes base attributes} plus:
1106 * </p>
1107 * <blockquote>
1108 * {@link SinkEventAttributes#ALIGN ALIGN}, {@link SinkEventAttributes#BGCOLOR BGCOLOR},
1109 * {@link SinkEventAttributes#VALIGN VALIGN}.
1110 * </blockquote>
1111 *
1112 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1113 * @since 1.1
1114 */
1115 void tableRow( SinkEventAttributes attributes );
1116
1117 /**
1118 * Ends a row element.
1119 */
1120 void tableRow_();
1121
1122 /**
1123 * Starts a cell element which defines a cell that contains data.
1124 *
1125 * @see #tableCell(SinkEventAttributes)
1126 */
1127 void tableCell();
1128
1129 /**
1130 * Starts a cell element which defines a cell that contains data.
1131 *
1132 * @param width the size of the cell.
1133 * @deprecated Use #tableCell(SinkEventAttributes) instead.
1134 */
1135 void tableCell( String width );
1136
1137 /**
1138 * Starts a table cell.
1139 *
1140 * <p>
1141 * Supported attributes are the {@link SinkEventAttributes base attributes} plus:
1142 * </p>
1143 * <blockquote>
1144 * {@link SinkEventAttributes#ABBRV ABBRV}, {@link SinkEventAttributes#ALIGN ALIGN},
1145 * {@link SinkEventAttributes#AXIS AXIS}, {@link SinkEventAttributes#BGCOLOR BGCOLOR},
1146 * {@link SinkEventAttributes#COLSPAN COLSPAN}, {@link SinkEventAttributes#HEADERS HEADERS},
1147 * {@link SinkEventAttributes#HEIGHT HEIGHT}, {@link SinkEventAttributes#NOWRAP NOWRAP},
1148 * {@link SinkEventAttributes#ROWSPAN ROWSPAN}, {@link SinkEventAttributes#SCOPE SCOPE},
1149 * {@link SinkEventAttributes#VALIGN VALIGN}, {@link SinkEventAttributes#WIDTH WIDTH}.
1150 * </blockquote>
1151 *
1152 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1153 * @since 1.1
1154 */
1155 void tableCell( SinkEventAttributes attributes );
1156
1157 /**
1158 * Ends a cell element.
1159 */
1160 void tableCell_();
1161
1162 /**
1163 * Starts a cell element which defines a cell that contains header information.
1164 *
1165 * @see #tableHeaderCell(SinkEventAttributes)
1166 */
1167 void tableHeaderCell();
1168
1169 /**
1170 * Starts a cell element which defines a cell that contains header information.
1171 *
1172 * @param width the size of the header cell.
1173 * @deprecated Use #tableHeaderCell(SinkEventAttributes) instead.
1174 */
1175 void tableHeaderCell( String width );
1176
1177 /**
1178 * Starts a table header cell.
1179 *
1180 * <p>
1181 * Supported attributes are the same as for {@link #tableCell(SinkEventAttributes) tableCell}.
1182 * </p>
1183 *
1184 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1185 * @since 1.1
1186 */
1187 void tableHeaderCell( SinkEventAttributes attributes );
1188
1189 /**
1190 * Ends a cell header element.
1191 */
1192 void tableHeaderCell_();
1193
1194 /**
1195 * Starts a caption element of a table.
1196 *
1197 * @see #tableCaption(SinkEventAttributes)
1198 */
1199 void tableCaption();
1200
1201 /**
1202 * Starts a table caption.
1203 *
1204 * <p>
1205 * Note that the order of tableCaption and
1206 * {@link #tableRows(int[],boolean)} events is arbitrary,
1207 * ie a parser may emit the tableCaption before or after the tableRows.
1208 * Implementing sinks should be prepared to handle both possibilities.
1209 * </p>
1210 * <p>
1211 * Supported attributes are the {@link SinkEventAttributes base attributes}
1212 * plus {@link SinkEventAttributes#ALIGN ALIGN}.
1213 * </p>
1214 *
1215 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1216 * @since 1.1
1217 * @see #table(SinkEventAttributes)
1218 */
1219 void tableCaption( SinkEventAttributes attributes );
1220
1221 /**
1222 * Ends a caption element of a table.
1223 */
1224 void tableCaption_();
1225
1226 /**
1227 * Starts an element which represents a paragraph.
1228 *
1229 * @see #paragraph(SinkEventAttributes)
1230 */
1231 void paragraph();
1232
1233 /**
1234 * Starts a paragraph.
1235 *
1236 * <p>
1237 * Supported attributes are the {@link SinkEventAttributes base attributes}
1238 * plus {@link SinkEventAttributes#ALIGN ALIGN}.
1239 * </p>
1240 *
1241 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1242 * @since 1.1
1243 */
1244 void paragraph( SinkEventAttributes attributes );
1245
1246 /**
1247 * Ends a paragraph element.
1248 */
1249 void paragraph_();
1250
1251 /**
1252 * Starts a data element which groups together other elements representing microformats.
1253 *
1254 * @see #data(String, SinkEventAttributes)
1255 * @param value a {@link java.lang.String} object.
1256 */
1257 void data( String value );
1258
1259 /**
1260 * Starts a data element which groups together other elements representing microformats.
1261 *
1262 * <p>
1263 * Supported attributes are the {@link SinkEventAttributes base attributes}
1264 * plus {@link SinkEventAttributes#VALUE VALUE}.
1265 * </p>
1266 *
1267 * @param value the machine readable value of the data, may be <code>null</code>.
1268 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1269 * @since 2.0
1270 */
1271 void data( String value, SinkEventAttributes attributes );
1272
1273 /**
1274 * Ends an data element.
1275 */
1276 void data_();
1277
1278 /**
1279 * Starts a time element which groups together other elements representing a time.
1280 *
1281 * @see #time(String, SinkEventAttributes)
1282 */
1283 void time( String datetime );
1284
1285 /**
1286 * Starts a time element which groups together other elements representing a time.
1287 *
1288 * <p>
1289 * Supported attributes are the {@link SinkEventAttributes base attributes}
1290 * plus {@link SinkEventAttributes#DATETIME DATETIME}.
1291 * </p>
1292 *
1293 * @param datetime the machine readable value of the time, may be <code>null</code>.
1294 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1295 * @since 2.0
1296 */
1297 void time( String datetime, SinkEventAttributes attributes );
1298
1299 /**
1300 * Ends a time element.
1301 */
1302 void time_();
1303
1304 /**
1305 * Starts an address element.
1306 *
1307 * @see #address(SinkEventAttributes)
1308 */
1309 void address();
1310
1311 /**
1312 * Starts an address element.
1313 *
1314 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1315 * @since 2.0
1316 */
1317 void address( SinkEventAttributes attributes );
1318
1319 /**
1320 * Ends an address element.
1321 */
1322 void address_();
1323
1324 /**
1325 * Starts a blockquote element.
1326 *
1327 * @see #blockquote(SinkEventAttributes)
1328 */
1329 void blockquote();
1330
1331 /**
1332 * Starts a blockquote element.
1333 *
1334 * <p>
1335 * Supported attributes are the {@link SinkEventAttributes base attributes}.
1336 * </p>
1337 *
1338 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1339 * @since 2.0
1340 */
1341 void blockquote( SinkEventAttributes attributes );
1342
1343 /**
1344 * Ends an blockquote element.
1345 */
1346 void blockquote_();
1347
1348 /**
1349 * Starts a division element grouping together other elements.
1350 *
1351 * @see #division(SinkEventAttributes)
1352 */
1353 void division();
1354
1355 /**
1356 * Starts a division element grouping together other elements.
1357 *
1358 * <p>
1359 * Supported attributes are the {@link SinkEventAttributes base attributes}
1360 * plus {@link SinkEventAttributes#ALIGN ALIGN}.
1361 * </p>
1362 *
1363 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1364 * @since 2.0
1365 */
1366 void division( SinkEventAttributes attributes );
1367
1368 /**
1369 * Ends a division element.
1370 */
1371 void division_();
1372
1373 /**
1374 * Starts an element which indicates that whitespace in the enclosed text has semantic relevance.
1375 *
1376 * @param boxed true to add a box, false otherwise
1377 * @deprecated Use #verbatim(SinkEventAttributes) instead.
1378 */
1379 void verbatim( boolean boxed );
1380
1381 /**
1382 * Starts a verbatim block, ie a block where whitespace has semantic relevance.
1383 *
1384 * <p>
1385 * Text in a verbatim block must only be wrapped at the linebreaks in the source,
1386 * and spaces should not be collapsed. It should be displayed in a fixed-width font to
1387 * retain the formatting but the overall size may be chosen by the implementation.
1388 * </p>
1389 *
1390 * <p>
1391 * Most Sink events may be emitted within a verbatim block, the only elements explicitly
1392 * forbidden are font-changing events and figures. Also, verbatim blocks may not be nested.
1393 * </p>
1394 *
1395 * <p>
1396 * Supported attributes are the {@link SinkEventAttributes base attributes} plus:
1397 * </p>
1398 * <blockquote>
1399 * {@link SinkEventAttributes#DECORATION DECORATION} (value: "boxed"),
1400 * {@link SinkEventAttributes#ALIGN ALIGN}, {@link SinkEventAttributes#WIDTH WIDTH}.
1401 * </blockquote>
1402 *
1403 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1404 * @since 1.1
1405 */
1406 void verbatim( SinkEventAttributes attributes );
1407
1408 /**
1409 * Ends a verbatim element.
1410 */
1411 void verbatim_();
1412
1413 /**
1414 * Adding a separator of sections from a text to each other.
1415 *
1416 * @see #horizontalRule(SinkEventAttributes)
1417 */
1418 void horizontalRule();
1419
1420 /**
1421 * Adds a horizontal separator rule.
1422 *
1423 * <p>
1424 * Supported attributes are the {@link SinkEventAttributes base attributes} plus:
1425 * </p>
1426 * <blockquote>
1427 * {@link SinkEventAttributes#ALIGN ALIGN}, {@link SinkEventAttributes#NOSHADE NOSHADE},
1428 * {@link SinkEventAttributes#SIZE SIZE}, {@link SinkEventAttributes#WIDTH WIDTH}.
1429 * </blockquote>
1430 *
1431 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1432 * @since 1.1
1433 */
1434 void horizontalRule( SinkEventAttributes attributes );
1435
1436 /**
1437 * Adding a new page separator.
1438 */
1439 void pageBreak();
1440
1441 /**
1442 * Starts an element which defines an anchor.
1443 *
1444 * @param name the name of the anchor.
1445 * @see #anchor(String,SinkEventAttributes)
1446 */
1447 void anchor( String name );
1448
1449 /**
1450 * Starts an element which defines an anchor.
1451 *
1452 * <p>
1453 * The <code>name</code> parameter has to be a valid SGML NAME token.
1454 * According to the <a href="http://www.w3.org/TR/html4/types.html#type-name">
1455 * HTML 4.01 specification section 6.2 SGML basic types</a>:
1456 * </p>
1457 * <p>
1458 * <i>ID and NAME tokens must begin with a letter ([A-Za-z]) and may be
1459 * followed by any number of letters, digits ([0-9]), hyphens ("-"),
1460 * underscores ("_"), colons (":"), and periods (".").</i>
1461 * </p>
1462 * <p>
1463 * Supported attributes are the {@link SinkEventAttributes base attributes}.
1464 * If {@link SinkEventAttributes#NAME NAME} is specified in the SinkEventAttributes,
1465 * it will be overwritten by the <code>name</code> parameter.
1466 * </p>
1467 *
1468 * @param name the name of the anchor. This has to be a valid SGML NAME token.
1469 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1470 * @since 1.1
1471 */
1472 void anchor( String name, SinkEventAttributes attributes );
1473
1474 /**
1475 * Ends an anchor element.
1476 */
1477 void anchor_();
1478
1479 /**
1480 * Starts an element which defines a link.
1481 *
1482 * @param name the name of the link.
1483 * @see #link(String,SinkEventAttributes)
1484 */
1485 void link( String name );
1486
1487 /**
1488 * Starts a link.
1489 *
1490 * <p>
1491 * The <code>name</code> parameter has to be a valid html <code>href</code>
1492 * parameter, ie for internal links (links to an anchor within the same source
1493 * document), <code>name</code> should start with the character "#".
1494 * </p>
1495 * <p>
1496 * Supported attributes are the {@link SinkEventAttributes base attributes} plus:
1497 * </p>
1498 * <blockquote>
1499 * {@link SinkEventAttributes#CHARSET CHARSET}, {@link SinkEventAttributes#COORDS COORDS},
1500 * {@link SinkEventAttributes#HREF HREF}, {@link SinkEventAttributes#HREFLANG HREFLANG},
1501 * {@link SinkEventAttributes#REL REL}, {@link SinkEventAttributes#REV REV},
1502 * {@link SinkEventAttributes#SHAPE SHAPE}, {@link SinkEventAttributes#TARGET TARGET},
1503 * {@link SinkEventAttributes#TYPE TYPE}.
1504 * </blockquote>
1505 * <p>
1506 * If {@link SinkEventAttributes#HREF HREF} is specified in the
1507 * SinkEventAttributes, it will be overwritten by the <code>name</code> parameter.
1508 * </p>
1509 *
1510 * @param name the name of the link.
1511 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1512 * @since 1.1
1513 */
1514 void link( String name, SinkEventAttributes attributes );
1515
1516 /**
1517 * Ends a link element.
1518 */
1519 void link_();
1520
1521 /**
1522 * Starts an inline element.
1523 *
1524 * @see #inline(SinkEventAttributes)
1525 */
1526 void inline();
1527
1528 /**
1529 * Starts an inline element.
1530 *
1531 * <p>
1532 * The inline method is similar to {@link #text(String,SinkEventAttributes)}, but
1533 * allows you to wrap arbitrary elements in addition to text.
1534 * </p>
1535 *
1536 * <p>
1537 * Supported attributes are the {@link SinkEventAttributes base attributes} plus
1538 * </p>
1539 * <blockquote>
1540 * {@link SinkEventAttributes#SEMANTICS SEMANTICS} (values "emphasis", "strong",
1541 * "small", "line-through", "citation", "quote", "definition", "abbreviation",
1542 * "italic", "bold", "monospaced", "variable", "sample", "keyboard", "superscript",
1543 * "subscript", "annotation", "highlight", "ruby", "rubyBase", "rubyText",
1544 * "rubyTextContainer", "rubyParentheses", "bidirectionalIsolation",
1545 * "bidirectionalOverride", "phrase", "insert", "delete").
1546 * </blockquote>
1547 *
1548 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1549 * @since 2.0
1550 */
1551 void inline( SinkEventAttributes attributes );
1552
1553 /**
1554 * Ends an inline element.
1555 */
1556 void inline_();
1557
1558 /**
1559 * Starts an italic element.
1560 *
1561 * Alternatively one may use {@link #text(String,SinkEventAttributes)} with
1562 * {@link SinkEventAttributes#STYLE STYLE} instead.
1563 */
1564 void italic();
1565
1566 /**
1567 * Ends an italic element.
1568 *
1569 * Alternatively one may use {@link #text(String,SinkEventAttributes)} with
1570 * {@link SinkEventAttributes#STYLE STYLE} instead.
1571 */
1572 void italic_();
1573
1574 /**
1575 * Starts a bold element.
1576 *
1577 * Alternatively one may use {@link #text(String,SinkEventAttributes)} with
1578 * {@link SinkEventAttributes#STYLE STYLE} instead.
1579 */
1580 void bold();
1581
1582 /**
1583 * Ends a bold element.
1584 *
1585 * Alternatively one may use {@link #text(String,SinkEventAttributes)} with
1586 * {@link SinkEventAttributes#STYLE STYLE} instead.
1587 */
1588 void bold_();
1589
1590 /**
1591 * Starts a monospaced element.
1592 *
1593 * Alternatively one may use {@link #text(String,SinkEventAttributes)} with
1594 * {@link SinkEventAttributes#STYLE STYLE} instead.
1595 */
1596 void monospaced();
1597
1598 /**
1599 * Ends a monospaced element.
1600 *
1601 * Alternatively one may use {@link #text(String,SinkEventAttributes)} with
1602 * {@link SinkEventAttributes#STYLE STYLE} instead.
1603 */
1604 void monospaced_();
1605
1606 /**
1607 * Adds a line break.
1608 *
1609 * @see #lineBreak(SinkEventAttributes)
1610 */
1611 void lineBreak();
1612
1613 /**
1614 * Adds a line break.
1615 *
1616 * <p>
1617 * Supported attributes are:
1618 * </p>
1619 * <blockquote>
1620 * {@link SinkEventAttributes#ID ID}, {@link SinkEventAttributes#CLASS CLASS},
1621 * {@link SinkEventAttributes#TITLE TITLE}, {@link SinkEventAttributes#STYLE STYLE}.
1622 * </blockquote>
1623 *
1624 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1625 * @since 1.1
1626 */
1627 void lineBreak( SinkEventAttributes attributes );
1628
1629 /**
1630 * Adds a line break opportunity.
1631 *
1632 * @see #lineBreak(SinkEventAttributes)
1633 */
1634 void lineBreakOpportunity();
1635
1636 /**
1637 * Adds a line break opportunity.
1638 *
1639 * <p>
1640 * Supported attributes are:
1641 * </p>
1642 * <blockquote>
1643 * {@link SinkEventAttributes#ID ID}, {@link SinkEventAttributes#CLASS CLASS},
1644 * {@link SinkEventAttributes#TITLE TITLE}, {@link SinkEventAttributes#STYLE STYLE}.
1645 * </blockquote>
1646 *
1647 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1648 * @since 2.0
1649 */
1650 void lineBreakOpportunity( SinkEventAttributes attributes );
1651
1652 /**
1653 * Adding a non breaking space, <i>ie</i> a space without any special formatting operations.
1654 */
1655 void nonBreakingSpace();
1656
1657 /**
1658 * Adding a text.
1659 *
1660 * @param text The text to write.
1661 * @see #text(String,SinkEventAttributes)
1662 */
1663 void text( String text );
1664
1665 /**
1666 * Adds a text.
1667 *
1668 * <p>
1669 * The <code>text</code> parameter should contain only real content, ie any
1670 * ignorable/collapsable whitespace/EOLs or other pretty-printing should
1671 * be removed/normalized by a parser.
1672 * </p>
1673 * <p>
1674 * If <code>text</code> contains any variants of line terminators, they should
1675 * be normalized to the System EOL by an implementing Sink.
1676 * </p>
1677 * <p>
1678 * Supported attributes are the {@link SinkEventAttributes base attributes} plus
1679 * </p>
1680 * <blockquote>
1681 * {@link SinkEventAttributes#SEMANTICS SEMANTICS} (values "emphasis", "strong",
1682 * "small", "line-through", "citation", "quote", "definition", "abbreviation",
1683 * "italic", "bold", "monospaced", "variable", "sample", "keyboard", "superscript",
1684 * "subscript", "annotation", "highlight", "ruby", "rubyBase", "rubyText",
1685 * "rubyTextContainer", "rubyParentheses", "bidirectionalIsolation",
1686 * "bidirectionalOverride", "phrase", "insert", "delete").
1687 * </blockquote>
1688 * <p>
1689 * The following attributes are deprecated:
1690 * </p>
1691 * <blockquote>
1692 * {@link SinkEventAttributes#VALIGN VALIGN} (values "sub", "sup"),
1693 * {@link SinkEventAttributes#DECORATION DECORATION} (values "underline", "overline", "line-through"),
1694 * {@link SinkEventAttributes#STYLE STYLE} (values "italic", "bold", "monospaced").
1695 * </blockquote>
1696 *
1697 * @param text The text to write.
1698 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1699 * @since 1.1
1700 */
1701 void text( String text, SinkEventAttributes attributes );
1702
1703 /**
1704 * Adding a raw text, <i>ie</i> a text without any special formatting operations.
1705 *
1706 * @param text The text to write.
1707 */
1708 void rawText( String text );
1709
1710 /**
1711 * Add a comment.
1712 *
1713 * @param comment The comment to write.
1714 * @since 1.1
1715 */
1716 void comment( String comment );
1717
1718 /**
1719 * Add an unknown event. This may be used by parsers to notify a general Sink about
1720 * an event that doesn't fit into any event defined by the Sink API.
1721 * Depending on the parameters, a Sink may decide whether or not to process the event,
1722 * emit it as raw text, as a comment, log it, etc.
1723 *
1724 * @param name The name of the event.
1725 * @param requiredParams An optional array of required parameters to the event.
1726 * May be <code>null</code>.
1727 * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1728 * @since 1.1
1729 */
1730 void unknown( String name, Object[] requiredParams, SinkEventAttributes attributes );
1731
1732 /**
1733 * Flush the writer or the stream, if needed.
1734 * Flushing a previously-flushed Sink has no effect.
1735 */
1736 void flush();
1737
1738 /**
1739 * Close the writer or the stream, if needed.
1740 * Closing a previously-closed Sink has no effect.
1741 */
1742 void close();
1743 }