This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch feature/auto-generate-anchors-for-toc
in repository https://gitbox.apache.org/repos/asf/maven-doxia-site.git
commit f249355476a809402fb6ed61243968500d404fcd
Author: Konrad Windszus <k...@apache.org>
AuthorDate: Tue Nov 28 20:15:28 2023 +0100
[DOXIASITETOOLS-320] Document Sink wrappers and the automatic generation
of anchor names for TOC entries
---
content/apt/developers/sink.apt | 43 +++++++++++++++++++++++++++++++++++++++++
content/apt/macros/index.apt | 7 ++-----
2 files changed, 45 insertions(+), 5 deletions(-)
diff --git a/content/apt/developers/sink.apt b/content/apt/developers/sink.apt
index 479f4a8..8eef12b 100644
--- a/content/apt/developers/sink.apt
+++ b/content/apt/developers/sink.apt
@@ -196,6 +196,49 @@ sink.unknown( "cdata", new Object[]{new Integer(
HtmlMarkup.CDATA_TYPE ), javasc
sink.unknown( "script", new Object[]{new Integer( HtmlMarkup.TAG_TYPE_END )},
null );
+----
+* {Using Sink wrappers}
+
+ One or multiple Sink wrappers can be registered with a parser to optionally
enrich or modify the output emitted to the sink.
+ Each sink wrapper is responsible for calling its subsequent sink (either
again a wrapper or the original sink).
+ The {{{SinkWrapper}}} class automatically just delegates all method calls to
its wrapper.
+ A sink wrapper is automatically created by the parser through a dedicated
factory.
+ Each JSR303 component implementing a SinkWrapperFactory is automatically
registered considering its rank.
+ Other sink wrapper factories can be registered manually via
<<<Parser.registerSinkWrapperFactory(...)>>>.
+
++----
+@Named
+public class MySinkWrapperFactory implements SinkWrapperFactory {
+
+ @Override
+ public Sink createWrapper(Sink sink) {
+ return new MySinkWrapper(sink);
+ }
+
+ @Override
+ public int getRank() {
+ // the higher the rank, the earlier it is called in the processing
queue
+ return 0;
+ }
+}
+
++----
+
+ The according SinkWrapper could look like this
+
++----
+public class MySinkWrapper extends SinkWrapper {
+
+ public MySinkWrapper(Sink sink) {
+ super(sink);
+ }
+
+ @Override
+ public void text(String text) {
+ super.text("some prefix emitted in front of every text " + text);
+ }
+
+}
++----
* {References}
diff --git a/content/apt/macros/index.apt b/content/apt/macros/index.apt
index 60f0bb2..f73d421 100644
--- a/content/apt/macros/index.apt
+++ b/content/apt/macros/index.apt
@@ -169,11 +169,8 @@ public class MyClass
+----
This displays a TOC for the second section in the document, including all
- subsections (depth 2) and sub-subsections (depth 3).
-
- <<Note>> that in Doxia, apt section titles are not implicit anchors
- (see {{{../references/doxia-apt.html}Enhancements to the APT format}}), so
you need
- to insert explicit anchors for links to work!
+ subsections (depth 2) and sub-subsections (depth 3). The macro takes care to
+ automatically generate anchors for each TOC entry.
In a xdoc file, it will be:
