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