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