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