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