ponymail-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject [1/2] incubator-ponymail-site git commit: Synch with code docs
Date Sun, 15 Jan 2017 23:07:57 GMT
Repository: incubator-ponymail-site
Updated Branches:
  refs/heads/asf-site a4ad431ff -> e0ce656f0

Synch with code docs

Project: http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/commit/d7430b81
Tree: http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/tree/d7430b81
Diff: http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/diff/d7430b81

Branch: refs/heads/asf-site
Commit: d7430b8144b7aa97178a288d709adb79526d0000
Parents: dce3e8c
Author: Sebb <sebb@apache.org>
Authored: Sun Jan 15 23:06:49 2017 +0000
Committer: Sebb <sebb@apache.org>
Committed: Sun Jan 15 23:06:49 2017 +0000

 source/markdown/docs/API.md            | 64 ++++++++++++++++++++++++++---
 source/markdown/docs/IMPORTING.md      | 36 +++++++++++-----
 source/markdown/docs/INSTALL.fedora.md |  2 +-
 source/markdown/docs/INSTALL.ubuntu.md |  5 +--
 source/markdown/docs/INSTALLING.md     | 15 +++----
 5 files changed, 93 insertions(+), 29 deletions(-)

diff --git a/source/markdown/docs/API.md b/source/markdown/docs/API.md
index 70461ea..0d868a1 100644
--- a/source/markdown/docs/API.md
+++ b/source/markdown/docs/API.md
@@ -3,10 +3,11 @@
 ### Fetching a specific email:
-`GET /api/email.lua?id=$mid`
+`GET /api/email.lua?id=$mid[&attachment=true&file=$hash]`
 Parameters: (cookie may be required)
   - $mid: The email ID or Message-ID: header
+  - $hash: the file attachment hash
 Response example:
@@ -37,18 +38,23 @@ Response example:
 ### Fetching list data
-`GET /api/stats.lua?list=$list&domain=$domain[&d=$timespan][&q=$query][&header_from=$from][&header_subject=$subject]`
+`GET /api/stats.lua?list=$list&domain=$domain[&d=$timespan][&q=$query][&header_from=$from][&header_to=$to][&header_subject=$subject][&header_body=$body][&quick][&s=$s&e=$e]`
     - $list: The list prefix (e.g. `dev`). Wildcards may be used
     - $domain: The list domain (e.g. `httpd.apache.org`). Wildcards may be used
     - $timespan: A [timespan](#Timespans) value
+    - $s: yyyy-mm start of month (day 1)
+    - $e: yyyy-mm end of month (last day)
     - $query: A search query (may contain wildcards or negations):
       - `foo`: Find all documents containing `foo` in headers or body
       - `-foo`: Find all documents NOT containing `foo`.
       - `foo*`: Find all documents containing `foo`, `fooa`, `foob` etc
     - $from: Optional From: address
+    - $to: Optional To: address
     - $subject: Optional Subject: line
+    - $body: Optional body text
 Response example:
@@ -56,10 +62,30 @@ Response example:
     "took": 437179,
     "firstYear": 2015,
-    "emails": {...},
+    "emails": {
+        {
+            "list_raw": "<dev.ponymail.apache.org>",
+            "gravatar": "66cf545ca7a1b8f595282bb9d8a59657",
+            "id": "b1d6446f5cc8f4846454cbabc48ddb08afbb601a77169f8e32e34102@<dev.ponymail.apache.org>",
+            "epoch": 1474883100,
+            "subject": "Re: Missing tag for 0.9 release",
+            "message-id": "<7f249f5e-e422-68a5-d57f-bfce585e638e@apache.org>",
+            "private": false,
+            "irt": "<CAOGo0VYrCOR=820LSDZA=czc==SOwCaRKasaEvVuxtUEXp9SDQ@mail.gmail.com>",
+            "from": "Daniel Gruno <h...@apache.org>",
+            "attachments": 0
+        },...
+    },
     "no_threads": 10,
     "domain": "ponymail.info",
-    "participants": {...},
+    "participants": {
+        {
+            "count": 3,
+            "name": "Daniel Gruno",
+            "gravatar": "66cf545ca7a1b8f595282bb9d8a59657",
+            "email": "hu...@apache.org"
+        }, ...
+    },
     "lastYear": 2015,
     "name": "dev",
     "cloud": {...},
@@ -73,13 +99,31 @@ Response example:
+### <a name="Timespans"></a>Timespans
+Timespans supported by the &d= parameter.
+    - d=yyyy-mm => equivalent to &s=yyyy-mm&e=yyyy-mm
+    - d=lte=n[wMyd] (less than n[wMyd] ago, inclusive)
+    - d=gte=n[wMyd] (more than n[wMyd] ago, inclusive)
+    - d=.*dfr=yyyy-mm-dd.* (start date for search, inclusive)
+    - d=.*dto=yyyy-mm-dd.* (end date for search, inclusive)
+    - [wMyd] = weeks, Months, years, days
+    - lte and gte are mutually exclusive
+    - dfr and dto are normally both present
 ### Fetching preferences and quick list overview
-`GET /api/preferences.lua[?logout=true]`
+`GET /api/preferences.lua[?logout][?associate=$email][?verify&hash=$hash][?removealt=$email][?save][?addfav=$list][?remfav=$list]`
 Parameters: (cookie required)
   - logout: Whether to log out of the system (optional)
+  - associate=$email - associate the account with the $email address
+  - verify&hash=$hash - verify an association request $hash
+  - removealt=$email - remove an alternate $email address
+  - save - save preferences
+  - addfav=$list - add a favourite $list
+  - remfav=$list - remove a favourite $list
 Response example:
@@ -132,3 +176,13 @@ Response example:
+### Fetching a month's data as an mbox file
+`GET /api/mbox.lua?list=issues@ponymail.apache.org&date=2016-06`
+Response example:

diff --git a/source/markdown/docs/IMPORTING.md b/source/markdown/docs/IMPORTING.md
index 7afeb4c..465cd28 100644
--- a/source/markdown/docs/IMPORTING.md
+++ b/source/markdown/docs/IMPORTING.md
@@ -3,15 +3,12 @@ Pony Mail supports many ways of importing your old mail archives via the
 `import-mbox.py` script. For command line argument tips, run `python3
 import-mbox.py --help`.
-Imports are digested equally every time, so you can
+Imports are digested equally every time (*), so you can
 import from the same source multiple times without creating duplicate emails in
 the archive. Both the archiver and the importer use the same digest method, so
 they can overlap. Usually, you'll want to set up the archiver first, and when
 emails start flowing through it, you'll use the importer to import older emails.
-## Importing attachments
-If you wish to import attached files, add the `--attachments` flag to your import command,
otherwise, attachments will be stripped.
 ## Importing from mod_mbox
 ### Importing a single domain
@@ -20,11 +17,11 @@ https://your.tld/mod_mbox/$list-yourdomain/, you can import all lists
from that
 `python3 import-mbox.py --source https://your.tld/mod_mbox/ --mod-mbox --project yourdomain`
-For a quick update, which only imports the last 2 months of mail, append then `--quick` flag.
+For a quick update, which only imports the last 2 months of mail, append the `--quick` flag.
 You can also import just a single list by specifying that list ID:
-`python3 import-mbox.py --source https://your.tld/mod_mbox/ --mod-mbox --project yourdomain-listname`
+`python3 import-mbox.py --source https://your.tld/mod_mbox/ --mod-mbox --project listname-yourdomain`
 ### Importing an entire archive (multiple domains)
 To import an entire site, use the same command as above, but omit the `--project` flag
@@ -34,7 +31,7 @@ To import an entire site, use the same command as above, but omit the `--project
 ### Setting the domain or list id properly in case of variance
 If your old archive varies in terms of list IDs across time, you can force harmonization
by using the `--lid` or `--domain` flags:
-`python3 import-mbox.py --source https://your.tld/mod_mbox/ --mod-mbox --project listid-yourdomain
--lid "<listid.youdomain.tld>"`
+`python3 import-mbox.py --source https://your.tld/mod_mbox/ --mod-mbox --project listid-yourdomain
--lid "<listid.yourdomain.tld>"`
 This should only be done one list at a time.
@@ -53,12 +50,31 @@ While the `project` flag is not needed here, you may wish to specify the
list ID
 ## Importing from locally stored mbox files
 To import from one or more local mbox files, specify a filesystem path as the source:
-`python3 import-mbox.py --source /tmp/mylists/ --attachments`
+`python3 import-mbox.py --source /tmp/mylists/`
+This will recursively import all files with the extension '.mbox'.
+You can change the extension as follows:
+`python3 import-mbox.py --source /tmp/mylists/ --ext .mbx`
+To match all files with any non-empty extension:
-If you have a mix of mbox and non-mbox files in the specific dir, you may wish to let Pony
Mail know which files to scan:
+`python3 import-mbox.py --source /tmp/mylists/ --ext '.*'`
-`python3 import-mbox.py --source /tmp/mylists/ --ext .mbox --attachments`
+To match files regardless of extension:
+`python3 import-mbox.py --source /tmp/mylists/ --ext ''`
+Or you can import a single file:
+`python3 import-mbox.py --source 2016-11.mbox`
+(This is supported in versions after 0.9)
 ## Test archives
 We have a few test archives for those that wish to test large imports.
 They can be found in gzip format at [http://ponymail.info/mboxes/](http://ponymail.info/mboxes/)
+(*) The digest depends on the [archiver] generator setting in ponymail.cfg
+If that varies between imports, then duplicates will occur

diff --git a/source/markdown/docs/INSTALL.fedora.md b/source/markdown/docs/INSTALL.fedora.md
index a94ce6f..f27e1ee 100644
--- a/source/markdown/docs/INSTALL.fedora.md
+++ b/source/markdown/docs/INSTALL.fedora.md
@@ -109,4 +109,4 @@ elasticsearch settings once Pony mail is up and running.
 Refer to the [General installation documentation](INSTALLING.md) for
 detailed information about archiving messages, OAuth, mail settings and
-much more.
\ No newline at end of file
+much more.

diff --git a/source/markdown/docs/INSTALL.ubuntu.md b/source/markdown/docs/INSTALL.ubuntu.md
index dff4752..95c47a2 100644
--- a/source/markdown/docs/INSTALL.ubuntu.md
+++ b/source/markdown/docs/INSTALL.ubuntu.md
@@ -67,14 +67,14 @@ sudo python3 setup.py
 Set up Apache httpd by adding, for example, the following virtual host configuration (e.g.
in `/etc/apache2/sites-enabled/000-default.conf`):
-&lt;VirtualHost *:80&gt;
+<VirtualHost *:80>
     ServerName mylists.foo.tld
     DocumentRoot /var/www/ponymail/site
     AddHandler      lua-script .lua
     LuaScope        thread
     LuaCodeCache    stat
     AcceptPathInfo  On
 Enable mod_lua and start apache, if not already enabled:
@@ -92,4 +92,3 @@ elasticsearch settings once Pony mail is up and running.
 Refer to the [General installation documentation](INSTALLING.md) for
 detailed information about archiving messages, OAuth, mail settings and
 much more.

diff --git a/source/markdown/docs/INSTALLING.md b/source/markdown/docs/INSTALLING.md
index 9f66882..e7244de 100644
--- a/source/markdown/docs/INSTALLING.md
+++ b/source/markdown/docs/INSTALLING.md
@@ -18,6 +18,7 @@ You will need the following software installed on your machine:
 - Python 3.x for the archiver plugin (setup.py will handle dependencies) and importer
 - Apache HTTP Server 2.4.x with mod_lua (see http://modlua.org/gs/installing if you need
to build mod_lua manually)
 - Lua >=5.1 with the following modules: cjson, luasec, luasocket
+  (Note: Lua 5.3 is not currently supported by httpd mod_lua or luasocket)
 ## Download and Install ##
@@ -108,16 +109,9 @@ Run `python3 edit-list.py --help` for CLI args.
 ## Setting up OAuth for Pony Mail ##
-If you want people to be able to log in and reply via the Web UI, you can either
-use the default Persona login (works for all email addresses) or specify an
-OAuth provider.
+If you want people to be able to log in and reply via the Web UI, you
+can specify an OAuth provider.
-### Setting up or disabling Persona ###
-Persona is enabled by default, as it's a fast and convenient way to enable
-logins for *public* lists. Should you wish to disable Persona, set the
-`enabled` variable to `false` in the persona section of `site/js/config.js`.
-Persona will only ever work for public lists. For private lists, you will need
-to specify and implement an OAuth provider.
 ### Setting up an OAuth provider ###
 Pony Mail comes with a few default OAuth examples in `site/js/config.js`, such
@@ -216,4 +210,5 @@ body, timestamp and list-ID to generate the MID. There is also a 'short'
 that only digests the body, and a 'full' that uses the entire message as
 a bytestring to generate an ID. Medium is recommended for most setups
 (especially clustered setups), while full can be used for single-machine
\ No newline at end of file
+N.B. At present, all the generators have issues, see (#176 #177 #178)

View raw message