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