You are viewing a plain text version of this content. The canonical link for it is here.
Posted to server-dev@james.apache.org by bt...@apache.org on 2020/06/01 07:31:55 UTC
[james-project] branch master updated (16456a2 -> 90933d5)
This is an automated email from the ASF dual-hosted git repository.
btellier pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git.
from 16456a2 JAMES-3197 Matcher processing should handle NoClassDefFoundError
new 9651480 JAMES-3187 Restructured documentation
new 90933d5 JAMES-3187 Removed obsolete file
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
docs/antora.yml | 10 +--
docs/modules/ROOT/nav.adoc | 2 +-
docs/modules/ROOT/pages/index.adoc | 32 ++++++--
docs/modules/admin/nav.adoc | 1 -
docs/modules/admin/pages/index.adoc | 4 -
docs/modules/{ops => community}/nav.adoc | 0
docs/modules/community/pages/index.adoc | 5 ++
docs/modules/concepts/nav.adoc | 11 +++
docs/modules/concepts/pages/index.adoc | 29 +++++++
docs/modules/concepts/pages/mail/index.adoc | 15 ++++
docs/modules/concepts/pages/mail/messages/imf.adoc | 83 +++++++++++++++++++
.../concepts/pages/mail/messages/index.adoc | 14 ++++
.../modules/concepts/pages/mail/messages/mime.adoc | 92 +++++++++++++++++++++
.../concepts/pages/mail/protocols/imap.adoc | 4 +
.../concepts/pages/mail/protocols/index.adoc | 16 ++++
.../concepts/pages/mail/protocols/jmap.adoc | 4 +
.../modules/concepts/pages/mail/protocols/pop.adoc | 4 +
.../concepts/pages/mail/protocols/smtp.adoc | 67 +++++++++++++++
docs/modules/concepts/pages/processing/index.adoc | 5 ++
docs/modules/{doc => customization}/nav.adoc | 0
docs/modules/customization/pages/index.adoc | 3 +
docs/modules/dev/pages/index.adoc | 4 -
docs/modules/{dev => development}/nav.adoc | 0
docs/modules/development/pages/index.adoc | 5 ++
docs/modules/doc/pages/index.adoc | 11 ---
docs/modules/ops/pages/index.adoc | 4 -
docs/modules/servers/nav.adoc | 5 ++
.../pages/15-minute-demo.adoc} | 10 +--
.../pages/5-minute-demo.adoc} | 8 +-
docs/modules/servers/pages/demo.adoc | 13 +++
docs/modules/servers/pages/distributed.adoc | 5 ++
docs/modules/servers/pages/index.adoc | 84 +++++++++++++++++++
docs/modules/servers/pages/local.adoc | 5 ++
docs/modules/servers/pages/redundant.adoc | 5 ++
docs/modules/servers/pages/run.adoc | 94 ++++++++++++++++++++++
docs/modules/user/nav.adoc | 6 --
docs/modules/user/pages/build.adoc | 4 -
docs/modules/user/pages/index.adoc | 23 ------
docs/modules/user/pages/learn.adoc | 4 -
docs/modules/user/pages/try.adoc | 10 ---
40 files changed, 607 insertions(+), 94 deletions(-)
delete mode 100644 docs/modules/admin/nav.adoc
delete mode 100644 docs/modules/admin/pages/index.adoc
rename docs/modules/{ops => community}/nav.adoc (100%)
create mode 100644 docs/modules/community/pages/index.adoc
create mode 100644 docs/modules/concepts/nav.adoc
create mode 100644 docs/modules/concepts/pages/index.adoc
create mode 100644 docs/modules/concepts/pages/mail/index.adoc
create mode 100644 docs/modules/concepts/pages/mail/messages/imf.adoc
create mode 100644 docs/modules/concepts/pages/mail/messages/index.adoc
create mode 100644 docs/modules/concepts/pages/mail/messages/mime.adoc
create mode 100644 docs/modules/concepts/pages/mail/protocols/imap.adoc
create mode 100644 docs/modules/concepts/pages/mail/protocols/index.adoc
create mode 100644 docs/modules/concepts/pages/mail/protocols/jmap.adoc
create mode 100644 docs/modules/concepts/pages/mail/protocols/pop.adoc
create mode 100644 docs/modules/concepts/pages/mail/protocols/smtp.adoc
create mode 100644 docs/modules/concepts/pages/processing/index.adoc
rename docs/modules/{doc => customization}/nav.adoc (100%)
create mode 100644 docs/modules/customization/pages/index.adoc
delete mode 100644 docs/modules/dev/pages/index.adoc
rename docs/modules/{dev => development}/nav.adoc (100%)
create mode 100644 docs/modules/development/pages/index.adoc
delete mode 100644 docs/modules/doc/pages/index.adoc
delete mode 100644 docs/modules/ops/pages/index.adoc
create mode 100644 docs/modules/servers/nav.adoc
rename docs/modules/{user/pages/try/15_minutes.adoc => servers/pages/15-minute-demo.adoc} (93%)
rename docs/modules/{user/pages/try/5_minutes.adoc => servers/pages/5-minute-demo.adoc} (88%)
create mode 100644 docs/modules/servers/pages/demo.adoc
create mode 100644 docs/modules/servers/pages/distributed.adoc
create mode 100644 docs/modules/servers/pages/index.adoc
create mode 100644 docs/modules/servers/pages/local.adoc
create mode 100644 docs/modules/servers/pages/redundant.adoc
create mode 100644 docs/modules/servers/pages/run.adoc
delete mode 100644 docs/modules/user/nav.adoc
delete mode 100644 docs/modules/user/pages/build.adoc
delete mode 100644 docs/modules/user/pages/index.adoc
delete mode 100644 docs/modules/user/pages/learn.adoc
delete mode 100644 docs/modules/user/pages/try.adoc
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org
[james-project] 01/02: JAMES-3187 Restructured documentation
Posted by bt...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
btellier pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git
commit 9651480c1933ab8d1292666547996e68ff7b4aa1
Author: David Leangen <da...@leangen.net>
AuthorDate: Tue May 19 11:24:08 2020 +0900
JAMES-3187 Restructured documentation
---
docs/antora.yml | 10 +--
docs/modules/ROOT/nav.adoc | 2 +-
docs/modules/ROOT/pages/index.adoc | 32 ++++++--
docs/modules/admin/nav.adoc | 1 -
docs/modules/admin/pages/index.adoc | 4 -
docs/modules/{ops => community}/nav.adoc | 0
docs/modules/community/pages/index.adoc | 5 ++
docs/modules/concepts/nav.adoc | 11 +++
docs/modules/concepts/pages/index.adoc | 29 +++++++
docs/modules/concepts/pages/mail/index.adoc | 15 ++++
docs/modules/concepts/pages/mail/messages/imf.adoc | 83 +++++++++++++++++++
.../concepts/pages/mail/messages/index.adoc | 14 ++++
.../modules/concepts/pages/mail/messages/mime.adoc | 92 +++++++++++++++++++++
docs/modules/concepts/pages/mail/mime/james.adoc | 3 +
.../concepts/pages/mail/protocols/imap.adoc | 4 +
.../concepts/pages/mail/protocols/index.adoc | 16 ++++
.../concepts/pages/mail/protocols/jmap.adoc | 4 +
.../modules/concepts/pages/mail/protocols/pop.adoc | 4 +
.../concepts/pages/mail/protocols/smtp.adoc | 67 +++++++++++++++
docs/modules/concepts/pages/processing/index.adoc | 5 ++
docs/modules/{doc => customization}/nav.adoc | 0
docs/modules/customization/pages/index.adoc | 3 +
docs/modules/dev/pages/index.adoc | 4 -
docs/modules/{dev => development}/nav.adoc | 0
docs/modules/development/pages/index.adoc | 5 ++
docs/modules/doc/pages/index.adoc | 11 ---
docs/modules/ops/pages/index.adoc | 4 -
docs/modules/servers/nav.adoc | 5 ++
.../pages/15-minute-demo.adoc} | 10 +--
.../pages/5-minute-demo.adoc} | 8 +-
docs/modules/servers/pages/demo.adoc | 13 +++
docs/modules/servers/pages/distributed.adoc | 5 ++
docs/modules/servers/pages/index.adoc | 84 +++++++++++++++++++
docs/modules/servers/pages/local.adoc | 5 ++
docs/modules/servers/pages/redundant.adoc | 5 ++
docs/modules/servers/pages/run.adoc | 94 ++++++++++++++++++++++
docs/modules/user/nav.adoc | 6 --
docs/modules/user/pages/build.adoc | 4 -
docs/modules/user/pages/index.adoc | 23 ------
docs/modules/user/pages/learn.adoc | 4 -
docs/modules/user/pages/try.adoc | 10 ---
41 files changed, 610 insertions(+), 94 deletions(-)
diff --git a/docs/antora.yml b/docs/antora.yml
index a7cff65..c451f20 100644
--- a/docs/antora.yml
+++ b/docs/antora.yml
@@ -3,8 +3,8 @@ title: Apache James Reference Book
version: '3.5'
prerelease: Alpha
nav:
-- modules/user/nav.adoc
-- modules/ops/nav.adoc
-- modules/admin/nav.adoc
-- modules/dev/nav.adoc
-- modules/doc/nav.adoc
+- modules/concepts/nav.adoc
+- modules/servers/nav.adoc
+- modules/customization/nav.adoc
+- modules/development/nav.adoc
+- modules/community/nav.adoc
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index 94db0dc..ee807cf 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -1 +1 @@
-* Apache James Reference Book
+* Apache James Reference Documentation
diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
index b0fd779..e65d2c9 100644
--- a/docs/modules/ROOT/pages/index.adoc
+++ b/docs/modules/ROOT/pages/index.adoc
@@ -1,15 +1,31 @@
= Welcome
-Welcome to the Apache James Reference Book! This Book is for version {page-version} of James.
+Welcome to the Apache James Reference Documentation! These documents are for version {page-version} of James.
-Apache James is the **J**ava **A**pache **M**ail **E**nterprise **S**erver. It boasts of a modular architecture based on a rich set of components that run on the JVM. With James, you can create your own custom enterprise email solution.
+Apache James is a flexible email platform that provides out-of-the-box mail servers that you can start
+using in production immediately.
+James runs on the JVM and is highly customizable.
This Reference Book is divided into the following Parts:
-* xref:main:user:index.adoc[User Manual]
-* xref:main:ops:index.adoc[Operator Manual]
-* xref:main:admin:index.adoc[Administrator Guide]
-* xref:main:dev:index.adoc[Developer Resources]
-* xref:main:doc:index.adoc[About this documentation]
+* xref:main:concepts:index.adoc[James Core Concepts]
+** These are the core concepts that describe what James is all about.
+ Start here if you want to learn more about what James can do
+ and how it is designed.
+* xref:main:servers:index.adoc[James Servers]
+** We provide a few out-of-the-box servers that you can
+ choose from depending on your needs. Start here if you just
+ want to get up and running quickly with a working production-grade mail server.
+* xref:main:customization:index.adoc[Customization]
+** Shows how you can customize any James server with the
+ functionalities that you need.
+ Check out this section if you have special business or technical
+ needs and are interested in a custom solution.
+* xref:main:development:index.adoc[James Developer Guide]
+** A guide aimed at experienced developers, describing
+ how you can assemble your own specialized server.
+* xref:main:community:index.adoc[James Community]
+** All about the Apache James community, and how you can be
+ part of this active and dynamic group, too!
-Please note that this Reference Book is a **living document**. It is subject to change. You are currently reading version {page-version}. If you find anything that is unclear, unfinished, or confusing, please do not hestiate to xref:main:doc:index.adoc[lend us a hand].
+Please note that this Reference Documentation is a **living document**. It is subject to change. You are currently reading version {page-version}. If you find anything that is unclear, unfinished, or confusing, please do not hestiate to xref:main:community:index.adoc[lend us a hand].
diff --git a/docs/modules/admin/nav.adoc b/docs/modules/admin/nav.adoc
deleted file mode 100644
index 31f850e..0000000
--- a/docs/modules/admin/nav.adoc
+++ /dev/null
@@ -1 +0,0 @@
-* xref:index.adoc[]
diff --git a/docs/modules/admin/pages/index.adoc b/docs/modules/admin/pages/index.adoc
deleted file mode 100644
index 53ed8f0..0000000
--- a/docs/modules/admin/pages/index.adoc
+++ /dev/null
@@ -1,4 +0,0 @@
-= Apache James Administrator Guide
-:navtitle: Administrator Guide
-
-(TODO)
diff --git a/docs/modules/ops/nav.adoc b/docs/modules/community/nav.adoc
similarity index 100%
rename from docs/modules/ops/nav.adoc
rename to docs/modules/community/nav.adoc
diff --git a/docs/modules/community/pages/index.adoc b/docs/modules/community/pages/index.adoc
new file mode 100644
index 0000000..5cf5498
--- /dev/null
+++ b/docs/modules/community/pages/index.adoc
@@ -0,0 +1,5 @@
+= Apache James Community
+:navtitle: Community
+
+(TODO)
+
diff --git a/docs/modules/concepts/nav.adoc b/docs/modules/concepts/nav.adoc
new file mode 100644
index 0000000..7dc1e62
--- /dev/null
+++ b/docs/modules/concepts/nav.adoc
@@ -0,0 +1,11 @@
+* xref:index.adoc[]
+** xref:mail/index.adoc[]
+*** xref:mail/messages/index.adoc[]
+**** xref:mail/messages/imf.adoc[]
+**** xref:mail/messages/mime.adoc[]
+*** xref:mail/protocols/index.adoc[]
+**** xref:mail/protocols/smtp.adoc[]
+**** xref:mail/protocols/pop.adoc[]
+**** xref:mail/protocols/imap.adoc[]
+**** xref:mail/protocols/jmap.adoc[]
+** xref:processing/index.adoc[]
diff --git a/docs/modules/concepts/pages/index.adoc b/docs/modules/concepts/pages/index.adoc
new file mode 100644
index 0000000..bcb5174
--- /dev/null
+++ b/docs/modules/concepts/pages/index.adoc
@@ -0,0 +1,29 @@
+= Apache James Core Concepts
+:navtitle: Concepts
+
+The core domain of Apache James is intimitely related to email communications.
+Therefore this section is divided into two parts:
+
+ * <<emails,The James Model of the Email Messaging Domain>>
+ * <<processing,The James Model of Email Processing>>
+
+[#emails]
+== Email Messaging Domain
+
+Electronic Mail (often written as "e-mail" or "email") is a means of
+exchanging messages over a data network. In our context, it is obvious
+that we mean "electronic mail" and not "postal mail", so we usually just
+write "mail".
+
+Building a complex system like James requires a clear and consistent
+xref:mail/index.adoc[domain model for email].
+
+
+[#processing]
+== James Email Processing
+
+There are many ways to peel a potato. James has its own particular
+xref:processing/index.adoc[model for processing mail],
+based mostly on the concept of a "Mailet". The idea of Mailet-based
+processing was heavily inspired by the https://en.wikipedia.org/wiki/Java_servlet[Servlet]
+concept.
diff --git a/docs/modules/concepts/pages/mail/index.adoc b/docs/modules/concepts/pages/mail/index.adoc
new file mode 100644
index 0000000..9cf9451
--- /dev/null
+++ b/docs/modules/concepts/pages/mail/index.adoc
@@ -0,0 +1,15 @@
+= All About Emails
+:navtitle: Emails
+
+The https://en.wikipedia.org/wiki/History_of_email[history of email] has resulted
+in a convoluted patchwork of standards and practices, which can be very difficult
+to understand and decipher. Fortunately, James has your back.
+
+We have built up our own view of emails that allows us to process messages in a
+consistent and comprehensible way.
+
+To help you understand how James approaches emails, we have divided this section
+up into the following parts:
+
+ * xref:mail/messages/index.adoc[]
+ * xref:mail/protocols/index.adoc[]
diff --git a/docs/modules/concepts/pages/mail/messages/imf.adoc b/docs/modules/concepts/pages/mail/messages/imf.adoc
new file mode 100644
index 0000000..886c5f0
--- /dev/null
+++ b/docs/modules/concepts/pages/mail/messages/imf.adoc
@@ -0,0 +1,83 @@
+= Internet Message Format
+:navtitle: IMF
+
+== Overview
+
+What people casually call "email" actually refers more specifically to a
+text message written in a specified format called
+https://en.wikipedia.org/wiki/Email["Internet Message Format"] or "IMF".
+After the first IMF specification was published in 1982 there was no looking back.
+Email took the world by storm. Today it is arguably the most prevalent means of
+communicating with a distant party.
+
+IMF is very basic, and is limited to only specifying a syntax for text messages.
+For the transmission of images, audio, or other types of data we need to make
+use of the xref:mail/messages/mime.adoc[MIME] specification.
+Although IMF forms the base standard upon which
+email is based, email today is rarely used without MIME. We therefore consider
+for practical purposes that an email message is essentially the equivalent of
+a MIME message.
+
+
+
+== Specifications
+
+The specifications for Internet Message Format (IMF) form the basis of what we commonly
+call "email".
+
+=== RFC822
+
+https://tools.ietf.org/html/rfc822[RFC822] ("Standard for the Format of ARPA Internet Text Messages")
+was the original standard that defined the format of an email. It was obsoleted by
+<<RFC2822>>. The definition of an email under this standard was an attempt to take the lessons
+learned from the ARPANET and extend the use of text messaging to a broader context.
+
+Electronic mail messages are defined as having contents and an envelope. The contents
+consist of header fields and, optionally, a body. The body is nothing more than
+a (potentially empty) sequence of lines of text.
+
+Although this sounds like a an extremely simple concept, to get two completely separate systems
+to agree and understand each other is a surprisingly complex problem that most people
+today take for granted. Most of RFC822 deals with the nitty-gritty of formatting and parsing
+this type of text message.
+
+This specification deals with the headers, additionally relating them to the sending and
+forwarding of messages. The body content is dealt with in <<RFC2045>>
+
+
+
+=== RFC2822
+
+https://tools.ietf.org/html/rfc2822[RFC2822] ("Internet Message Format")
+obsoletes <<RFC822>>, and was obsoleted by <<RFC5322>>.
+
+The standard builds on RFC822, but limits its scope to only the sytax of the
+message, and obsoletes much of what was defined by RFC822. The envelope was
+split into a separate specification, <<RFC2821>>.
+
+
+
+
+=== RFC5322
+
+https://tools.ietf.org/html/rfc5322[RFC5322] ("Internet Message Format")
+was published in 2008.
+It obsoletes <<RFC2822>> and is currently the specification still actually in use.
+
+It builds on RFC2822, updating it to the then-current context and obsoleting
+outdated parts of RFC2822.
+
+
+
+
+== James Model
+
+While the general description of IMF is not sufficient for building a complex
+system like James, the technical specifications are unfortunately
+very messy and overly-complex due to their history and the context in which
+they were developed.
+
+Since modern-day messaging almost always requires MIME, and since the
+separation between IMF and MIME is not really useful from a usage perspective,
+James considers an "email" to be both IMF- an MIME-compliant. For all intents
+and purposes, James does not consider the concept of IMF in its domain model.
diff --git a/docs/modules/concepts/pages/mail/messages/index.adoc b/docs/modules/concepts/pages/mail/messages/index.adoc
new file mode 100644
index 0000000..8a9b488
--- /dev/null
+++ b/docs/modules/concepts/pages/mail/messages/index.adoc
@@ -0,0 +1,14 @@
+= Email Messages
+:navtitle: Messages
+
+An email message is essentially a simple text message that is communicated
+from one party to another. It is no miracle that two unknown parties are
+able to communicate; rather rather we can thank a set of standards that
+allow any two unrelated systems to process an email even if the system owners
+do not know each other.
+
+The two most important standards upon which today's emails are based
+are:
+
+ * xref:mail/messages/imf.adoc[Internet Mail Format] (IMF)
+ * xref:mail/messages/mime.adoc[Multipurpose Internet Mail Extensions] (MIME)
diff --git a/docs/modules/concepts/pages/mail/messages/mime.adoc b/docs/modules/concepts/pages/mail/messages/mime.adoc
new file mode 100644
index 0000000..fbd45e5
--- /dev/null
+++ b/docs/modules/concepts/pages/mail/messages/mime.adoc
@@ -0,0 +1,92 @@
+= Multipurpose Internet Mail Extensions
+:navtitle: MIME
+
+== Overview
+
+The base format of an email message is xref:mail/messages/imf.adoc[Internet Message Format"],
+but most contemporary messages use a format called
+https://en.wikipedia.org/wiki/MIME["Multipurpose Internet Mail Extensions"].
+MIME specifies how to extend a valid IMF message, dealing with character encodings,
+various file formats, and many other odds and ends that make email what it is today.
+
+A user of email rarely has to be concerned with the MIME specifications. Usually the
+communications system should take care of all the nitty gritty, and even then MIME
+processing is usually at a very low level. For this reason, the blissfully simple
+conception of a simple "email" is usually just fine from the perspective of a user
+and even in most cases for a developer.
+
+
+
+
+== Specifications
+
+Multipurpose Internet Mail Extensions, or just MIME, functions much like an extension
+to IMF in order to:
+
+ * Add different character sets for internationalization
+ * Allow for processing of media types other than plain text
+
+=== RFC2045
+
+https://tools.ietf.org/html/rfc2045[RFC2045] ("Multipurpose Internet Mail Extensions
+Part One: Format of Internet Message Bodies")
+describes the message body format of an email. It is part of a serious of MIME
+specifications including <<RFC2046>>, <<RFC2047>>, <<RFC2048>>, and <<RFC2049>>.
+This particular document in the series specifies the various headers that
+are used to describe the structure of a MIME message.
+
+
+
+=== RFC2046
+
+https://tools.ietf.org/html/rfc2046[RFC2046] ("Multipurpose Internet Mail Extensions
+Part Two: Media Types") describes the various MIME media types, such as
+plain text, images, videos, etc. It is part of the serious of MIME specifications
+that includes <<RFC2045>>, <<RFC2047>>, <<RFC2048>>, and <<RFC2049>>.
+
+
+
+
+=== RFC2047
+
+https://tools.ietf.org/html/rfc2047[RFC2047] ("MIME Part Three:
+Message Header Extensions for Non-ASCII Text") describes, as the
+title indicates, header extensions for non-ASCII text. It is part
+of the series of MIME specifications that includes
+<<RFC2045>>, <<RFC2046>>, <<RFC2048>>, and <<RFC2049>>.
+
+
+
+
+=== RFC2048
+
+https://tools.ietf.org/html/rfc2048[RFC2048] ("Multipurpose Internet Mail Extensions
+Part Four: Registration Procedures") describes the procedure for registering a MIME
+type. It is not directly relevant to James, but is part of the MIME series that includes
+<<RFC2045>>, <<RFC2046>>, <<RFC2047>>, and <<RFC2049>>.
+
+This specification was obsoleted by https://tools.ietf.org/html/rfc4288[RFC4288]
+(which itself was obsoleted by https://tools.ietf.org/html/rfc6838[RFC6838]) and
+https://tools.ietf.org/html/rfc4289[RFC4289].
+
+
+
+=== RFC2049
+
+https://tools.ietf.org/html/rfc2049[RFC2049] ("Multipurpose Internet Mail Extensions
+Part Five: Conformance Criteria and Examples") mainly describes what portions of MIME
+must be supported by a conformant MIME implementation. It is part of the series that includes
+<<RFC2045>>, <<RFC2046>>, <<RFC2047>>, and <<RFC2049>>.
+
+
+
+== James Model
+
+While a general, non-technical description of MIME is useful for most users
+and developers, it is not sufficient for building a complex system like James. Meanwhile,
+the technical specifications are unfortunately very messy and overly-complex due to
+their history and the context in which they were developed. To make dealing with
+emails possible and practical, James has defined its own version of what it means
+to be an email.
+
+(TODO need a reference, please!)
diff --git a/docs/modules/concepts/pages/mail/mime/james.adoc b/docs/modules/concepts/pages/mail/mime/james.adoc
new file mode 100644
index 0000000..7879639
--- /dev/null
+++ b/docs/modules/concepts/pages/mail/mime/james.adoc
@@ -0,0 +1,3 @@
+Added as a dummy file because there is an orphaned comment in GitHub that I am unable to resolve.
+
+Will this workaround work???
diff --git a/docs/modules/concepts/pages/mail/protocols/imap.adoc b/docs/modules/concepts/pages/mail/protocols/imap.adoc
new file mode 100644
index 0000000..2454663
--- /dev/null
+++ b/docs/modules/concepts/pages/mail/protocols/imap.adoc
@@ -0,0 +1,4 @@
+= Message Access (IMAP)
+:navtitle: IMAP
+
+(TODO)
diff --git a/docs/modules/concepts/pages/mail/protocols/index.adoc b/docs/modules/concepts/pages/mail/protocols/index.adoc
new file mode 100644
index 0000000..729438e
--- /dev/null
+++ b/docs/modules/concepts/pages/mail/protocols/index.adoc
@@ -0,0 +1,16 @@
+= Transmission Protocols
+:navtitle: Protocols
+
+The true value of emails is that any one party can communicate with any
+other party located virtually anywhere. All they need are a common understanding
+of a xref:mail/messages/index.adoc[message format], and a means of
+transmitting the message.
+
+Transmitting email messages between parties requires a mutually-known standard.
+It turns out that there are several standard protocols used for the
+transmission of email messages, each with a different purpose:
+
+ ** xref:mail/protocols/smtp.adoc[Message Transport]
+ ** xref:mail/protocols/pop.adoc[Electronic Post]
+ ** xref:mail/protocols/imap.adoc[Remote Message Access]
+ ** xref:mail/protocols/jmap.adoc[Application Data Transfer]
diff --git a/docs/modules/concepts/pages/mail/protocols/jmap.adoc b/docs/modules/concepts/pages/mail/protocols/jmap.adoc
new file mode 100644
index 0000000..2c2fdb4
--- /dev/null
+++ b/docs/modules/concepts/pages/mail/protocols/jmap.adoc
@@ -0,0 +1,4 @@
+= Application Data Transfer (JMAP)
+:navtitle: JMAP
+
+(TODO)
diff --git a/docs/modules/concepts/pages/mail/protocols/pop.adoc b/docs/modules/concepts/pages/mail/protocols/pop.adoc
new file mode 100644
index 0000000..b0116d8
--- /dev/null
+++ b/docs/modules/concepts/pages/mail/protocols/pop.adoc
@@ -0,0 +1,4 @@
+= Electronic Post (POP)
+:navtitle: POP
+
+(TODO)
diff --git a/docs/modules/concepts/pages/mail/protocols/smtp.adoc b/docs/modules/concepts/pages/mail/protocols/smtp.adoc
new file mode 100644
index 0000000..f24a876
--- /dev/null
+++ b/docs/modules/concepts/pages/mail/protocols/smtp.adoc
@@ -0,0 +1,67 @@
+= Simple Mail Transfer Protocol (SMTP)
+:navtitle: SMTP
+
+== Overview
+
+When the original specification for Simple Mail Transfer Protocol, or SMTP,
+was published almost 40 years ago together with
+xref:mail/messages/imf.adoc[IMF], Email as we know it today was born.
+
+
+
+== Specifications
+
+=== RFC821
+
+https://tools.ietf.org/html/rfc821[RFC821] ("Simple Mail Transfer Protocol")
+was the original SMTP specification published in 1982.
+It was obsoleted by <<RFC2821>> in 2001.
+
+== RFC2821
+
+https://tools.ietf.org/html/rfc2821[RFC2821] ("Simple Mail Transfer Protocol") replaced
+<<RFC821>>. It was itself replaced by <<RFC5321>> in 2008.
+
+== RFC 5321
+
+https://tools.ietf.org/html/rfc5321[RFC5321] is the currently used standard for
+"Simple Mail Transfer Protocol", or "SMTP". It is "a specification of the basic
+protocol for Internet electronic mail transport". If you are interested in all
+the gory details, we recommend that you read this document.
+
+This specification has many dependencies with xref:mail/messages/imf.adoc[IMF],
+xref:mail/messages/mime.adoc[MIME], and other technical concepts, which can quickly
+become utterly confusing.
+
+Here, we provide a very short and simplified description of those portions of the
+specification that we felt were interesting enough to repeat here.
+
+As the spec mentions, "SMTP transports a mail object", a mail object being described
+as an object that contains both an envelope and content. An SMTP client connects
+to a server and communicates via a session. Both client and server provide a
+mail transport service, and are therefore act as "Mail Transfer Agents", or
+"MTAs". A mail originates and terminates with a "Mail User Agent" ("MUA").
+On the originating side, a MUA may, for instance, collect mail to be transmitted
+by a user and hand it off to an MTA. On the terminating side, an MTA would
+hand a mail off to an MUA.
+
+"SMTP sessions are stateful, with both parties carefully maintaining a
+common view of the current state." The session is initiated by the client,
+which establishes a two-way channel to an SMTP server. The session must either
+close successful (or with a failure message), else delivery is considered to
+have failed.
+
+
+
+== James Model
+
+(TODO: explain how all this is modeled in James)
+
+
+
+
+== Try It!
+
+Add a section to the demo, and connect manuall via an SMTP session
+
+
diff --git a/docs/modules/concepts/pages/processing/index.adoc b/docs/modules/concepts/pages/processing/index.adoc
new file mode 100644
index 0000000..61a0223
--- /dev/null
+++ b/docs/modules/concepts/pages/processing/index.adoc
@@ -0,0 +1,5 @@
+= Mail Processing Domain Model
+:navtitle: Processing
+
+(TODO)
+
diff --git a/docs/modules/doc/nav.adoc b/docs/modules/customization/nav.adoc
similarity index 100%
rename from docs/modules/doc/nav.adoc
rename to docs/modules/customization/nav.adoc
diff --git a/docs/modules/customization/pages/index.adoc b/docs/modules/customization/pages/index.adoc
new file mode 100644
index 0000000..99c4bf0
--- /dev/null
+++ b/docs/modules/customization/pages/index.adoc
@@ -0,0 +1,3 @@
+= Apache James Customization
+:navtitle: Customization
+
diff --git a/docs/modules/dev/pages/index.adoc b/docs/modules/dev/pages/index.adoc
deleted file mode 100644
index db73ae1..0000000
--- a/docs/modules/dev/pages/index.adoc
+++ /dev/null
@@ -1,4 +0,0 @@
-= Apache James Developer Resources
-:navtitle: Developer Resources
-
-(TODO)
diff --git a/docs/modules/dev/nav.adoc b/docs/modules/development/nav.adoc
similarity index 100%
rename from docs/modules/dev/nav.adoc
rename to docs/modules/development/nav.adoc
diff --git a/docs/modules/development/pages/index.adoc b/docs/modules/development/pages/index.adoc
new file mode 100644
index 0000000..56db0cd
--- /dev/null
+++ b/docs/modules/development/pages/index.adoc
@@ -0,0 +1,5 @@
+= Apache James Developer Guide
+:navtitle: Developer Guide
+
+(TODO)
+
diff --git a/docs/modules/doc/pages/index.adoc b/docs/modules/doc/pages/index.adoc
deleted file mode 100644
index 163a381..0000000
--- a/docs/modules/doc/pages/index.adoc
+++ /dev/null
@@ -1,11 +0,0 @@
-= About this documentation
-:navtitle: About this documentation
-
-This documentation was produced with Antora.
-
-We know that this documentation is lacking. We are slowing working on making it better.
-To that end, we would **love** to get your help!
-
-This section explains how to work with Antora and the Apache James Reference Book.
-
-(TODO)
diff --git a/docs/modules/ops/pages/index.adoc b/docs/modules/ops/pages/index.adoc
deleted file mode 100644
index d11c829..0000000
--- a/docs/modules/ops/pages/index.adoc
+++ /dev/null
@@ -1,4 +0,0 @@
-= Apache James Operator Manual
-:navtitle: Operator Manual
-
-(TODO)
diff --git a/docs/modules/servers/nav.adoc b/docs/modules/servers/nav.adoc
new file mode 100644
index 0000000..78f97b3
--- /dev/null
+++ b/docs/modules/servers/nav.adoc
@@ -0,0 +1,5 @@
+* xref:index.adoc[]
+** xref:demo.adoc[]
+** xref:local.adoc[]
+** xref:redundant.adoc[]
+** xref:distributed.adoc[]
diff --git a/docs/modules/user/pages/try/15_minutes.adoc b/docs/modules/servers/pages/15-minute-demo.adoc
similarity index 93%
rename from docs/modules/user/pages/try/15_minutes.adoc
rename to docs/modules/servers/pages/15-minute-demo.adoc
index 6fbad69..18498ff 100644
--- a/docs/modules/user/pages/try/15_minutes.adoc
+++ b/docs/modules/servers/pages/15-minute-demo.adoc
@@ -1,6 +1,6 @@
-= Try James in 15 minutes
+= Long Demo
-In this tutorial, we will set up a runing James demo using a prepared Docker image.
+In this demo (~15 minutes), we will set up a runing James demo using a prepared Docker image.
We will then test the server by connecting with an email client. Finally, we
will connect to the server via the REST-based Admin API.
@@ -57,7 +57,7 @@ docker exec james java -jar /root/james-cli.jar \
-h \<<HOST>> -p \<<PORT>> \<<COMMAND>>
----
-In this tutorial, we are using host 127.0.0.1 and port 9999, so every command looks like:
+In this demo, we are using host 127.0.0.1 and port 9999, so every command looks like:
----
docker exec james java -jar /root/james-cli.jar \
@@ -66,7 +66,7 @@ docker exec james java -jar /root/james-cli.jar \
Host 127.0.0.1 is of course localhost, and the use of port 9999 is completely arbitrary.
-To make this tutorial a little easier, set this up as a bash script by copying and pasting this script:
+To make this demo a little easier to use, set this up as a bash script by copying and pasting this script:
[source,bash]
----
@@ -123,7 +123,7 @@ You should now see your newly created user:
== Connect to the server with an email client
****
-For this tutorial, we will use Thunderbird, as it is available in multiple languages
+For this demo, we will use Thunderbird, as it is available in multiple languages
on Windows, Mac, and Linux.
Go to https://www.thunderbird.net to download Thunderbird.
diff --git a/docs/modules/user/pages/try/5_minutes.adoc b/docs/modules/servers/pages/5-minute-demo.adoc
similarity index 88%
rename from docs/modules/user/pages/try/5_minutes.adoc
rename to docs/modules/servers/pages/5-minute-demo.adoc
index a885eb3..bf710c9 100644
--- a/docs/modules/user/pages/try/5_minutes.adoc
+++ b/docs/modules/servers/pages/5-minute-demo.adoc
@@ -1,6 +1,6 @@
-= Try James in 5 minutes
+= Short Demo
-In this short tutorial, we will set up a runing James demo very quickly
+In this short demo (~5 minutes), we will set up a runing James demo very quickly
using a prepared Docker image.
Then you will add a domain, and a user account within that domain.
@@ -38,7 +38,7 @@ docker exec james java -jar /root/james-cli.jar \
-h \<<HOST>> -p \<<PORT>> \<<COMMAND>>
----
-In this tutorial, we are using host 127.0.0.1 and port 9999, so every command looks like:
+In this demo, we are using host 127.0.0.1 and port 9999, so every command looks like:
----
docker exec james java -jar /root/james-cli.jar \
@@ -48,7 +48,7 @@ docker exec james java -jar /root/james-cli.jar \
Host 127.0.0.1 is of course localhost, and the use of port 9999 is completely arbitrary.
****
-To make this tutorial a little easier, set this up as a bash script by copying and pasting this script:
+To make this demo a little easier to use, set this up as a bash script by copying and pasting this script:
[source,bash]
----
diff --git a/docs/modules/servers/pages/demo.adoc b/docs/modules/servers/pages/demo.adoc
new file mode 100644
index 0000000..a752a2a
--- /dev/null
+++ b/docs/modules/servers/pages/demo.adoc
@@ -0,0 +1,13 @@
+= Server Demo
+:navtitle: Demo
+
+The James Demo Server sets up a light-weight, disposable mail server
+so you can try it out easily on your own local machine.
+
+ * xref:main:servers:5-minute-demo.adoc[Short demo] (~5 minutes)
+ ** Set up a demo server
+ ** Create a new user with the CLI
+ * xref:main:servers:15-minute-demo.adoc[Long demo] (~15 minutes)
+ ** Same steps as above
+ ** Interact with the server via the Admin API
+ ** Test the server with an email client
diff --git a/docs/modules/servers/pages/distributed.adoc b/docs/modules/servers/pages/distributed.adoc
new file mode 100644
index 0000000..b795e46
--- /dev/null
+++ b/docs/modules/servers/pages/distributed.adoc
@@ -0,0 +1,5 @@
+= James Distributed Mail Server
+:navtitle: Distributed
+
+(TODO)
+
diff --git a/docs/modules/servers/pages/index.adoc b/docs/modules/servers/pages/index.adoc
new file mode 100644
index 0000000..3786e81
--- /dev/null
+++ b/docs/modules/servers/pages/index.adoc
@@ -0,0 +1,84 @@
+= Apache James Mail Servers
+:navtitle: Servers
+
+James offers a number of ready-made Mail Servers. The servers are intended
+for those with typcial use cases, and can be used out-of-the-box. These
+servers have been tested and verified so you can get set up quickly with
+a production-grade Mail Server that you can use with confidence.
+
+The available James Servers are:
+
+ * <<demo,James Demo Mail Server>>
+ * <<local,James Local Mail Server>>
+ * <<redundant,James Redundant Mail Server>>
+ * <<distributed,James Distributed Mail Server>>
+
+
+[#demo]
+== James Demo Server
+The xref:demo.adoc[James Server Demo] is intended for those who just want
+to give James a quick spin on their local machine.
+
+
+[#local]
+== James Local Mail Server
+
+If you are not sure which server you should be using, then
+you probably ought to be using the xref:local.adoc[*Local Server*].
+This server uses the local file system to store emails, which tends
+to considerably simplify the system. To safeguard your emails, you
+only need a simple generic backup solution that works with a data
+volume.
+
+This server is intended to be the simplest to set up and use in production.
+It has the least amount of dependencies and complexities. If you do not yet
+have a huge amount of emails to process, then usually the simplicity is
+well worth the loss of some functionality. The last thing you need is
+to have to resolve difficult issues on a production server when you have not
+yet acquired the requisite knowledge to deal with those issues. Using the
+xref:local.adoc[*Local Server*] will help you reduce the risk of running into
+production issues.
+
+This server is:
+
+ * Suggested for use with smaller deployments
+ * Appropriate for use by most operators
+ * The preferred choice for most installations
+ * Endowed with fewer dependencies, which makes it simpler and less risky to use in production
+ * Only dependent on your local file system for data storage, so very easy to manage
+
+
+
+
+[#redundant]
+== James Redundant Mail Server
+
+When your requirements start to get a little more serious
+(let's say in the tens of millions of emails), then you may want to
+start to consider using the xref:redundant.adoc[*Redundant Server*].
+
+This server provides data redundancy so that it can stay live at
+all times, even in the rare case that your data gets corrupted.
+
+This server is:
+
+ * Intended for use by experienced operators only
+ * Used for mid-sized to large deployments
+ * More performant than the Minimal and Basic Server, but also more complex
+
+
+
+
+[#distributed]
+== James Distributed Mail Server
+
+The xref:distributed.adoc[*Distributed Server*] is a heavy-duty industrial
+enterprise mail server.
+
+This server is:
+
+ * Intended for use by experts only
+ * Use for large-scale distributed deployments
+ * The most feature-rich server, but also by far the most complex
+
+
diff --git a/docs/modules/servers/pages/local.adoc b/docs/modules/servers/pages/local.adoc
new file mode 100644
index 0000000..8783dcf
--- /dev/null
+++ b/docs/modules/servers/pages/local.adoc
@@ -0,0 +1,5 @@
+= James Local Mail Server
+:navtitle: Local
+
+(TODO)
+
diff --git a/docs/modules/servers/pages/redundant.adoc b/docs/modules/servers/pages/redundant.adoc
new file mode 100644
index 0000000..659034a
--- /dev/null
+++ b/docs/modules/servers/pages/redundant.adoc
@@ -0,0 +1,5 @@
+= James Redundant Mail Server
+:navtitle: Redundant
+
+(TODO)
+
diff --git a/docs/modules/servers/pages/run.adoc b/docs/modules/servers/pages/run.adoc
new file mode 100644
index 0000000..70a71ca
--- /dev/null
+++ b/docs/modules/servers/pages/run.adoc
@@ -0,0 +1,94 @@
+= Run James in Production
+:navtitle: Run
+
+James provides a number of *profiles* out of the box.
+These profiles have been tested and verified so you can
+get set up quickly with a production mail server that you
+can use with confidence.
+
+The available profiles are:
+
+ * <<minimal,James Minimal Profile>>
+ * <<basic,James Basic Profile>>
+ * <<advanced,James Advanced Profile>>
+ * <<distributed,James Distributed Profile>>
+
+
+
+[#minimal]
+== James Minimal Profile
+
+If you are not sure which profile you should be using, then
+you probably ought to be using the *James Minimal Profile*.
+
+This profile is intended to be the simplest to set up and use in production.
+It has the least amount of dependencies and complexities. If you do not yet
+have a huge amount of emails to process, then usually the simplicity is
+well worth the loss of some functionality. The last thing you need is
+to have to resolve difficult issues on a production server when you have not
+yet acquired the requisite knowledge to deal with those issues. Using the
+*James Minimal Profile* will help you reduce the risk of running into
+production issues.
+
+This profile is:
+
+ * Suggested for use with smaller deployments
+ * Appropriate for use by most operators
+ * The preferred choice for most installations
+ * Endowed with fewer dependencies, which makes it simpler and less risky to use in production
+ * Only dependent on your local file system for data storage, so very easy to manage
+
+(TODO: Add link to details page)
+
+
+[#basic]
+== James Basic Profile
+
+This profile is intended to be relatively easy to use, but provides additional features with regards
+to data storage and management. Of course, these additional features come at the cost of more
+operational complexity. You will have to now deal with a relational database and all the fun
+that comes with it. However, if you are already an expert at relational database management,
+then this profile should be a natural choice for you.
+
+This profile is:
+
+ * Suggested for smaller deployments that require data persisted in a relational database
+ * Appropriate for most operators provided that you understand relational databases and data indexing
+ * Less complex than most profiles, but also less performant
+
+(TODO: Add link to details page)
+
+
+[#advanced]
+== James Advanced Profile
+
+When your requirements start to get a little more serious
+(let's say in the tens of millions of emails), then you may want to
+start to consider using the *James Advanced Profile*.
+
+This profile is:
+
+ * Intended for use by experienced operators only
+ * Used for mid-sized to large deployments
+ * More performant than the Minimal and Basic Profiles, but also more complex
+
+
+(TODO: Add link to details page)
+
+
+
+[#distributed]
+== James Distributed Profile
+
+The *James Distributed Profile* is a heavy-duty industrial enterprise mail server.
+
+This profile is:
+
+ * Intended for use by experts only
+ * Use for large-scale distributed deployments
+ * The most feature-rich profile, but also by far the most complex
+
+
+(TODO: Add link to details page)
+
+
diff --git a/docs/modules/user/nav.adoc b/docs/modules/user/nav.adoc
deleted file mode 100644
index b2cfd2e..0000000
--- a/docs/modules/user/nav.adoc
+++ /dev/null
@@ -1,6 +0,0 @@
-* xref:index.adoc[]
-** xref:try.adoc[]
-*** xref:try/5_minutes.adoc[]
-*** xref:try/15_minutes.adoc[]
-** xref:learn.adoc[]
-** xref:build.adoc[]
diff --git a/docs/modules/user/pages/build.adoc b/docs/modules/user/pages/build.adoc
deleted file mode 100644
index 28e483a..0000000
--- a/docs/modules/user/pages/build.adoc
+++ /dev/null
@@ -1,4 +0,0 @@
-= Build your own custom mail server
-:navtitle: Build
-
-(TODO)
diff --git a/docs/modules/user/pages/index.adoc b/docs/modules/user/pages/index.adoc
deleted file mode 100644
index 41ff7af..0000000
--- a/docs/modules/user/pages/index.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-= Apache James User Manual
-:navtitle: User Manual
-
-link:https://gitter.im/apache/james-project[image:https://badges.gitter.im/apache/james-project.svg[Join the chat at link:https://gitter.im/apache/james-project]]
-
-image::james-logo.png[James logo]
-
-*James* stands for *Java Apache Mail Enterprise Server*.
-
-James has a modular architecture based on a rich set of components that form a
-complete, stable, secure and customizable mail server running on the JVM.
-
-Supported protocols include: IMAP, SMTP, JMAP, and POP3.
-
-This user manual provides information to get you up and running quickly with James.
-You can also refer to the Administrator Guide, Developer Resources, and
-Operator Manual for additional information about James from different perspectives.
-
-== How to...
-
- * xref::try.adoc[Try James in 5 minutes]
- * xref::build.adoc[Learn more about the architecture]
- * xref::build.adoc[Build your own custom mail server]
diff --git a/docs/modules/user/pages/learn.adoc b/docs/modules/user/pages/learn.adoc
deleted file mode 100644
index 543ea00..0000000
--- a/docs/modules/user/pages/learn.adoc
+++ /dev/null
@@ -1,4 +0,0 @@
-= Learn more about the architecture
-:navtitle: Learn
-
-You can read about James in the https://james.apache.org/documentation.html[Documentation] section on the James website.
diff --git a/docs/modules/user/pages/try.adoc b/docs/modules/user/pages/try.adoc
deleted file mode 100644
index a40260d..0000000
--- a/docs/modules/user/pages/try.adoc
+++ /dev/null
@@ -1,10 +0,0 @@
-= Try James
-:navtitle: Try
-
- * xref:main:user:try/5_minutes.adoc[Try James in 5 minutes]
- ** Set up a demo server
- ** Create a new user with the CLI
- * xref:main:user:try/15_minutes.adoc[Try James in 15 minutes]
- ** Same steps as above
- ** Interact with the server via the Admin API
- ** Test the server with an email client
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org
[james-project] 02/02: JAMES-3187 Removed obsolete file
Posted by bt...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
btellier pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git
commit 90933d5863d8c2ac29ef5c2ea2876b9ef210e3b6
Author: David Leangen <da...@leangen.net>
AuthorDate: Sun May 31 21:05:27 2020 +0900
JAMES-3187 Removed obsolete file
---
docs/modules/concepts/pages/mail/mime/james.adoc | 3 ---
1 file changed, 3 deletions(-)
diff --git a/docs/modules/concepts/pages/mail/mime/james.adoc b/docs/modules/concepts/pages/mail/mime/james.adoc
deleted file mode 100644
index 7879639..0000000
--- a/docs/modules/concepts/pages/mail/mime/james.adoc
+++ /dev/null
@@ -1,3 +0,0 @@
-Added as a dummy file because there is an orphaned comment in GitHub that I am unable to resolve.
-
-Will this workaround work???
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org