This is an automated email from the ASF dual-hosted git repository.
chibenwa pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-jsieve.git
commit 7d94f3f985b3562842c8d9463dcc9545ba612466
Author: Benoit TELLIER <[email protected]>
AuthorDate: Sun Aug 23 23:31:20 2026 +0700
[DOC] Migrate to antora
---
docs/antora.yml | 4 +-
.../ROOT/assets/images/james-jsieve-logo.gif | Bin 0 -> 7014 bytes
docs/modules/ROOT/nav.adoc | 8 ++
docs/modules/ROOT/pages/features.adoc | 74 +++++++++++++++
docs/modules/ROOT/pages/getting-started.adoc | 99 +++++++++++++++++++++
docs/modules/ROOT/pages/index.adoc | 80 ++++++++++++++++-
docs/modules/ROOT/pages/release-notes.adoc | 62 +++++++++++++
docs/modules/ROOT/pages/specifications.adoc | 13 +++
docs/modules/ROOT/pages/utils.adoc | 26 ++++++
9 files changed, 363 insertions(+), 3 deletions(-)
diff --git a/docs/antora.yml b/docs/antora.yml
index f5c9f9f..5c310c2 100644
--- a/docs/antora.yml
+++ b/docs/antora.yml
@@ -1,4 +1,6 @@
name: jsieve
title: Apache James jSieve
-version: '0.8-SNAPSHOT'
+version: '0.9-SNAPSHOT'
prerelease: true
+nav:
+ - modules/ROOT/nav.adoc
diff --git a/docs/modules/ROOT/assets/images/james-jsieve-logo.gif b/docs/modules/ROOT/assets/images/james-jsieve-logo.gif
new file mode 100644
index 0000000..9c7e34f
Binary files /dev/null and b/docs/modules/ROOT/assets/images/james-jsieve-logo.gif differ
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
new file mode 100644
index 0000000..d11ec72
--- /dev/null
+++ b/docs/modules/ROOT/nav.adoc
@@ -0,0 +1,8 @@
+* xref:index.adoc[Overview]
+* xref:features.adoc[Sieve Features]
+* xref:getting-started.adoc[Getting Started]
+* xref:utils.adoc[jSieve Utilities]
+* xref:specifications.adoc[Specifications]
+* xref:release-notes.adoc[Release Notes]
+* https://issues.apache.org/jira/browse/JSIEVE[Issue Tracker]
+* https://james.apache.org/download.cgi#Apache_JSieve[Download Releases]
diff --git a/docs/modules/ROOT/pages/features.adoc b/docs/modules/ROOT/pages/features.adoc
new file mode 100644
index 0000000..6ce4c27
--- /dev/null
+++ b/docs/modules/ROOT/pages/features.adoc
@@ -0,0 +1,74 @@
+= jSieve Features
+
+== Sieve Features Supported By jSieve
+
+jSieve is limited only by the platform on which it runs.
+
+[cols="1,1"]
+|===
+|Limits |
+
+|Maximum Number Of Actions |No intrinsic limit
+|Maximum Number Of Nested Blocks |No intrinsic limit
+|Maximum Number Of Nested Test Lists |No intrinsic limit
+|===
+
+jSieve supports the standard control commands specified in RFC 5228.
+
+[cols="1,1,1"]
+|===
+|Control Command |Specification |Supported
+
+|If |RFC 5228 (REQUIRED) |yes
+|Require |RFC 5228 (REQUIRED) |yes
+|Stop |RFC 5228 (REQUIRED) |yes
+|===
+
+jSieve supports all action commands (both required and optional) specified in RFC 5228.
+
+NOTE: jSieve uses a pluggable `MailAdapter` as an interface to the mail server.
+Not all implementations may fully support all actions.
+
+[cols="1,1,1"]
+|===
+|Action Command |Specification |Supported
+
+|fileinto |RFC 5228 (REQUIRED) |yes
+|redirect |RFC 5228 (REQUIRED) |yes
+|keep |RFC 5228 (REQUIRED) |yes
+|discard |RFC 5228 (REQUIRED) |yes
+|reject |RFC 5429 |yes
+|ereject |RFC 5429 |no
+|===
+
+jSieve supports all tests commands specified in RFC 5228.
+
+[cols="1,1,1"]
+|===
+|Test Command |Specification |Supported
+
+|address |RFC 5228 (REQUIRED) |yes
+|allof |RFC 5228 (REQUIRED) |yes
+|anyof |RFC 5228 (REQUIRED) |yes
+|envelope |RFC 5228 (OPTIONAL) |yes
+|exists |RFC 5228 (REQUIRED) |yes
+|false |RFC 5228 (REQUIRED) |yes
+|header |RFC 5228 (REQUIRED) |yes
+|not |RFC 5228 (REQUIRED) |yes
+|size |RFC 5228 (REQUIRED) |yes
+|true |RFC 5228 (REQUIRED) |yes
+|body |RFC 5173 |yes
+|vacation |RFC 5230 |yes
+|===
+
+== jSieve Extension Commands
+
+jSieve allows extension commands to be developed and plugged in at run time.
+The following extension commands ship with jSieve:
+
+[cols="1,1"]
+|===
+|Name |Function
+
+|Log |Logs messages
+|===
diff --git a/docs/modules/ROOT/pages/getting-started.adoc b/docs/modules/ROOT/pages/getting-started.adoc
new file mode 100644
index 0000000..e840a95
--- /dev/null
+++ b/docs/modules/ROOT/pages/getting-started.adoc
@@ -0,0 +1,99 @@
+= Getting Started
+
+Until these pages are fleshed out, the best way to understand jSieve is to read the
+javadocs and look at the source code. The jUnit tests illustrate many aspects of the
+implementation.
+
+== Using jSieve
+
+=== Standalone
+
+`org.apache.jsieve.SieveFactory` is the primary invocation point for all Sieve operations.
+The API is clean and simple. See the javadocs for more details.
+
+=== In JAMES
+
+The `SieveMailboxMailet` mailet is part of the jsieve/mailet project. It provides a mailet
+that applies SIEVE actions defined by a user SIEVE script to incoming e-mails. Integration
+is done in the JAMES code base using a `SieveMailet` in project server/mailet/mailets.
+This project:
+
+* Proposes a `SieveLocator` based on your `SieveRepository` for locating your user Sieve script
+* Communicates via URLs with the classes introduced in server/mailet/mailets, allowing it to be
+used independently from the API defined in James Mailbox. All you need to use
+`SieveMailboxMailet` is a mailet environment
+
+Note that some integration tests in James server on mail delivery behave as integration tests
+for JSIEVE in JAMES. Have a look at `org.apache.james.transport.mailets.delivery.SieveMailetTest`.
+
+In James server, Sieve scripts are stored by ``SieveRepository``(ies). Note that you can manage
+your SIEVE scripts as a user on James using 3 mechanisms, depending on your installation:
+
+* With `SieveDefaultRepository` one needs to interact with the file system to customize their
+scripts (legacy reasons)
+* If enabled by the administrator, you can use a ManageSieve server, as specified in RFC-5804
+* Or you can rely on the `ManageSieveMailet` to handle ManageSieve over SMTP
+
+== Implementing A Mail Adapter
+
+`org.apache.jsieve.mail.MailAdapter` is the interface API used by jSieve to interact with a
+mail server.
+
+The mail adapter wraps an email and supplies information (required by the script) about the
+email. It is responsible for accumulating ``Action``s during the parsing of a script and for
+executing them once the parsing is complete.
+
+See the javadocs for more details and the `SieveMailAdapter` implementation
+(`org.apache.jsieve.samples.james.SieveMailAdapter`) for the mailets environment.
+
+== Implementing Extension Commands
+
+A parser is already implemented using jjTree. So the Sieve entities you will implement will
+already be called with parsed arguments. You will have to validate such arguments (SIEVE syntax
+check), handle parsing state modification (such as saying an action was taken, see
+`SieveContext.getCommandStateManager()` for a deeper insight), and implement the behavior you
+want regarding these arguments.
+
+You can implement additional extension commands.
+`org.apache.jsieve.commands.extensions.Log` is an example of an extension command. It is
+recommended that extension commands extend `AbstractCommand`
+(`org.apache.jsieve.commands.AbstractCommand`). See the javadocs for more details.
+
+Commands need to be registered with `org.apache.jsieve.ConfigurationManager` before they can be
+used. This may be done programmatically but the recommended method is by altering the
+`org/apache/jsieve/commandsmap.properties`, `org/apache/jsieve/testsmap.properties` and
+`org/apache/jsieve/comparatorsmap.properties` resource files.
+
+Commands generate actions that get transferred by commands to the `MailAdapter`. If you
+introduce new actions, you will have to extend the `MailAdapter` API if you need more
+information or actions from the mail server.
+
+Writing new tests can be done in a similar way: extend `AbstractTest` to implement your test.
+Adding capabilities to the `MailAdapter` might be required. You also need to register it in
+`org/apache/jsieve/testsmap.properties`.
+
+== Building jSieve
+
+jSieve uses https://maven.apache.org[Maven]. `mvn clean install` compiles the jSieve project
+and installs it.
+
+== Comments, Questions and Issues
+
+jSieve is a sub-project of Apache James. Please direct your comments and questions to the
+relevant https://james.apache.org/mail.html[James list].
+
+To report issues, such as bugs, go to the
+https://issues.apache.org/jira/browse/JSIEVE[jSieve Issue Tracker]. As jSieve comes with a
+fairly extensive suite of jUnit tests, it would be most helpful for bug reports to be
+accompanied by an illustrative jUnit test case.
+
+=== Frequently Asked Questions
+
+==== Why Do Tests Using Non-ASCII Characters Fail?
+
+`SIEVE` specifies that https://tools.ietf.org/html/rfc2278[UTF-8] encoding is used for scripts.
+This format is an international standard and has wide support but not all platforms use this
+encoding by default.
+
+By default, jSieve expects that scripts are encoded using `UTF-8`. Either set the encoding
+programmatically or ensure that the script is encoded using `UTF-8`.
diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
index ad7ff8c..5f18407 100644
--- a/docs/modules/ROOT/pages/index.adoc
+++ b/docs/modules/ROOT/pages/index.adoc
@@ -1,4 +1,80 @@
-= Apache James jSieve documentation
+= Apache James jSieve
+image::james-jsieve-logo.gif[jSieve logo]
-TODO: This is a placeholder. Migrate older documentation.
+== What is jSieve?
+
+jSieve is a Java implementation of the Sieve mail filtering language defined by
+https://tools.ietf.org/html/rfc5228[RFC 5228]. jSieve is implemented as a language
+processor that can be plugged into any internet mail application to add Sieve support.
+
+jSieve is a subproject of https://james.apache.org[Apache JAMES]. All who are interested
+in developing jSieve and JAMES will be warmly welcomed on the
+https://james.apache.org/mail.html[mailing lists].
+
+jSieve consists of two products:
+
+* *Apache JSieve* is a Sieve library coded in Java. See xref:getting-started.adoc[Getting Started]
+and xref:features.adoc[Sieve Features].
+* xref:utils.adoc[*Apache JSieve Utilities*] contains utility classes helpful when using Sieve
+but not considered sufficiently core to be included in the main library.
+
+=== What is Sieve?
+
+Sieve is an extensible mail filtering language. Its limited expressiveness (no loops or
+variables, no tests with side effects) allows user created scripts to be run safely on email
+servers. Sieve is targeted at the final delivery phase (where an incoming email is transferred
+to a user's mailbox).
+
+Sieve scripts are composed of commands. Control commands manage the execution of the script.
+Test commands define side-effect free criteria. Action commands are mail operations to be
+performed.
+
+== Extensions Supported
+
+=== Body Extension
+
+https://tools.ietf.org/html/rfc5173[RFC 5173] (Sieve Email Filtering: Body Extension) describes
+an extension command that tests the body of an email for one or more strings.
+
+=== Sieve-In-Xml
+
+https://tools.ietf.org/html/draft-freed-sieve-in-xml-04[Sieve-in-xml] is an Internet Draft.
+It describes a method for converting Sieve scripts to and from XML fragments.
+xref:utils.adoc[JSieve Utilities] contains an experimental preview of a subset of this draft
+to allow early feedback. xref:utils.adoc#sieve-in-xml[More...]
+
+== News
+
+=== October/2022 - jSieve-0.8 released
+
+The Apache JAMES team is happy to announce the availability of
+https://james.apache.org/download.cgi#Apache_JSieve[Apache jSieve 0.8].
+
+=== May/2010 - jSieve-0.5 released
+
+The Apache JAMES team is happy to announce the availability of
+https://james.apache.org/download.cgi#Apache_JSieve[Apache jSieve 0.5].
+See https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=10412&version=12314991&styleName=Html[release notes]
+for more details.
+
+=== May/2010 - jSieve-0.4 released
+
+The Apache JAMES team is happy to announce the availability of
+https://james.apache.org/download.cgi#Apache_JSieve[Apache jSieve 0.4].
+See https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=10412&styleName=Html&version=12313855[release notes]
+for more details.
+
+=== Jun/2008 - jSieve-0.3 released
+
+The Apache JAMES team is happy to announce the availability of
+https://james.apache.org/download.cgi#Apache_JSieve[Apache jSieve 0.3].
+This is the first modular release including a filtering
+https://james.apache.org/mailet[mailet] as well as many fixes and improvements.
+See the xref:release-notes.adoc[release notes] for more details.
+
+=== Aug/2008 - jSieve-0.2 released
+
+The Apache JAMES team is happy to announce the availability of
+https://james.apache.org/download.cgi#Apache_JSieve[Apache jSieve 0.2].
+This first public release is a major milestone for JSieve.
diff --git a/docs/modules/ROOT/pages/release-notes.adoc b/docs/modules/ROOT/pages/release-notes.adoc
new file mode 100644
index 0000000..992da23
--- /dev/null
+++ b/docs/modules/ROOT/pages/release-notes.adoc
@@ -0,0 +1,62 @@
+= Release Notes
+
+jSieve is a Java implementation of the Sieve mail filtering language defined by
+https://tools.ietf.org/html/rfc5228[RFC 5228]. jSieve is implemented as a language processor
+that can be plugged into any internet mail application to add Sieve support.
+
+== Comments, Questions and Issues
+
+jSieve is a sub-project of Apache James. Please direct your comments and questions to the
+relevant https://james.apache.org/mail.html[James list].
+
+To report issues, such as bugs, go to https://issues.apache.org/jira/browse/JSIEVE.
+As jSieve comes with a fairly extensive suite of jUnit tests, it would be most helpful for bug
+reports to be accompanied by an illustrative jUnit test case.
+
+== Licensing and legal issues
+
+For legal and licensing issues, please look in the legal section of the documentation or read
+the `LICENSE.txt` and `NOTICE.txt` files.
+
+== Version 0.3
+
+This release is the first to include mailet and utility modules, in addition to the core parsing
+library. The configuration API has changed significantly to replace magic singletons with POJOs
+suitable for IoC. The default configuration mechanism has been retained so though calls have
+changed, existing configurations should still be compatible.
+
+Utilities include node serializers to xml and sieve script. The mailet module provides Sieve
+in the James 3 codebase.
+
+=== Sub-tasks Completed
+
+* https://issues.apache.org/jira/browse/JSIEVE-27[JSIEVE-27] - Refactor ComparatorManager
+* https://issues.apache.org/jira/browse/JSIEVE-29[JSIEVE-29] - Refactor ConfigurationManager
+* https://issues.apache.org/jira/browse/JSIEVE-32[JSIEVE-32] - Refactor TestManager
+* https://issues.apache.org/jira/browse/JSIEVE-37[JSIEVE-37] - Push main source down a level
+* https://issues.apache.org/jira/browse/JSIEVE-38[JSIEVE-38] - Modular Ant Build
+* https://issues.apache.org/jira/browse/JSIEVE-44[JSIEVE-44] - Create Check Module
+* https://issues.apache.org/jira/browse/JSIEVE-45[JSIEVE-45] - Extract Reusable Ant Macros
+* https://issues.apache.org/jira/browse/JSIEVE-46[JSIEVE-46] - Unified Distribution
+* https://issues.apache.org/jira/browse/JSIEVE-48[JSIEVE-48] - Release Quality Maven Build
+
+=== Bugs Fixed
+
+* https://issues.apache.org/jira/browse/JSIEVE-49[JSIEVE-49] - CPU spins when `:matches` expression contains `"*************"`
+
+=== Improvements Made
+
+* https://issues.apache.org/jira/browse/JSIEVE-47[JSIEVE-47] - Access to script comments
+* https://issues.apache.org/jira/browse/JSIEVE-52[JSIEVE-52] - Check Support For Numeric Quantifiers
+
+=== New Features Added
+
+* https://issues.apache.org/jira/browse/JSIEVE-43[JSIEVE-43] - Add API for generating a Sieve script from a parse tree
+* https://issues.apache.org/jira/browse/JSIEVE-50[JSIEVE-50] - Sieve-In-XML (Experimental Preview)
+
+=== Tasks Completed
+
+* https://issues.apache.org/jira/browse/JSIEVE-16[JSIEVE-16] - Singletons -> IoC
+* https://issues.apache.org/jira/browse/JSIEVE-24[JSIEVE-24] - Include build time libraries (javacc, javamail, activation) in the source distribution
+* https://issues.apache.org/jira/browse/JSIEVE-33[JSIEVE-33] - Remove `.junit.` package name from tests
+* https://issues.apache.org/jira/browse/JSIEVE-34[JSIEVE-34] - Make jsieve a multimodule project
diff --git a/docs/modules/ROOT/pages/specifications.adoc b/docs/modules/ROOT/pages/specifications.adoc
new file mode 100644
index 0000000..9d328c9
--- /dev/null
+++ b/docs/modules/ROOT/pages/specifications.adoc
@@ -0,0 +1,13 @@
+= Specifications
+
+The specifications jSieve implements or relies upon:
+
+* https://tools.ietf.org/html/rfc2234[RFC 2234] - Augmented BNF for Syntax Specifications (ABNF)
+* https://tools.ietf.org/html/rfc2244[RFC 2244] - Application Configuration Access Protocol (ACAP)
+* https://tools.ietf.org/html/rfc2298[RFC 2298] - Message Disposition Notification (MDN)
+* https://tools.ietf.org/html/rfc4790[RFC 4790] - Internet Application Protocol Collation Registry (IAPCR)
+* https://tools.ietf.org/html/rfc5173[RFC 5173] - Sieve Email Filtering: Body Extension
+* https://tools.ietf.org/html/rfc5228[RFC 5228] - Sieve: An Email Filtering Language
+* https://tools.ietf.org/html/rfc5230[RFC 5230] - Sieve Email Filtering: Vacation Extension
+* https://tools.ietf.org/html/rfc5429[RFC 5429] - Sieve Email Filtering: Reject and Extended Reject Extensions
+* https://tools.ietf.org/html/rfc5804[RFC 5804] - A Protocol for Remotely Managing Sieve Scripts (ManageSieve)
diff --git a/docs/modules/ROOT/pages/utils.adoc b/docs/modules/ROOT/pages/utils.adoc
new file mode 100644
index 0000000..6900bc9
--- /dev/null
+++ b/docs/modules/ROOT/pages/utils.adoc
@@ -0,0 +1,26 @@
+= Apache jSieve Utilities
+
+== Introduction
+
+jSieve Utilities collects lightweight frameworks and utilities useful when working with Sieve
+(in general) and xref:index.adoc[jSieve] (in particular).
+
+They are shipped as the `org.apache.james:apache-jsieve-util` artifact.
+
+== Highlights
+
+=== Script Checker
+
+Checks Sieve scripts. Includes monitoring controlled execution of a script against a message.
+
+[[sieve-in-xml]]
+=== Sieve In Xml
+
+https://tools.ietf.org/html/draft-freed-sieve-in-xml-04[Sieve-in-xml] is an Internet Draft.
+It describes a method to convert Sieve scripts to and from an XML format suitable for editing
+by a UI. A typical use case is as the payload for a web based editor backed by web services.
+
+`OutputUtils` contains an experimental preview of a subset of this draft. It allows a jSieve
+node tree to be output as sieve-in-xml. Full support is planned but feedback is encouraged,
+through the https://james.apache.org/mail.html[mailing lists] or the
+https://issues.apache.org/jira/browse/JSIEVE[issue tracker].
lmpx.com only provides a reader for public news (NNTP) servers. It is not
affiliated with the servers or forums shown here and is not responsible for
the content of articles, which is written by their respective authors.