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