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