add xt/mem-nntpd-tls maintainer test

[public-inbox.git] / Documentation / design_www.txt

diff --git a/Documentation/design_www.txt b/Documentation/design_www.txt
index 67a90931f84e2405ba9e0ca3dab433685fe703ae..b1f916ddb3697606aaf623ada2ef3b607666e6f3 100644 (file)
--- a/Documentation/design_www.txt
+++ b/Documentation/design_www.txt
@@ -1,3 +1,5 @@
+PublicInbox::WWW (PSGI interface) design notes
+

 URL and anchor naming
 ---------------------
 
 URL and anchor naming
 ---------------------
 


@@ -5,17 +7,30 @@ URL and anchor naming
 /$INBOX/?r=$GIT_COMMIT                 -> HTML only
 /$INBOX/new.atom                       -> Atom feed
 
 /$INBOX/?r=$GIT_COMMIT                 -> HTML only
 /$INBOX/new.atom                       -> Atom feed
 

-#### Optional, relies on Search::Xapian
-/$INBOX/$MESSAGE_ID/t/                 -> HTML content of thread
+#### Optional, relies on Search::Xapian (or Xapian SWIG binding)
+/$INBOX/$MESSAGE_ID/t/                 -> HTML content of thread (nested)
+/$INBOX/$MESSAGE_ID/T/                 -> HTML content of thread (flat)

        anchors:
        #u          location of $MESSAGE_ID in URL
        #m<SHA-1>   per-message links, where <SHA-1> is of the Message-ID
                    of each message (stable)
        #s<NUM>     relative numeric position of message in thread (unstable)
        anchors:
        #u          location of $MESSAGE_ID in URL
        #m<SHA-1>   per-message links, where <SHA-1> is of the Message-ID
                    of each message (stable)
        #s<NUM>     relative numeric position of message in thread (unstable)

+       #i<...>     diffstat location for patch emails
+       #Z?<...>    per-file diff header location for patch emails

 
 /$INBOX/$MESSAGE_ID/t.atom             -> Atom feed for thread
 /$INBOX/$MESSAGE_ID/t.mbox.gz          -> gzipped mbox of thread
 
 
 /$INBOX/$MESSAGE_ID/t.atom             -> Atom feed for thread
 /$INBOX/$MESSAGE_ID/t.mbox.gz          -> gzipped mbox of thread
 

+/$INBOX/$GIT_OID/s/                    -> "git show" (via "git apply")
+       This endpoint requires "coderepo" entries configured for
+       a given inbox.  It can recreate ("solve") blobs from
+       patch emails using Xapian and git-apply(1).  It can also
+       display non-blob content, but that remains a
+       work-in-progress.
+
+/$INBOX/$GIT_OID/s/$FILENAME           -> "git show", raw output
+       As above, but shows the raw (usually text/plain) output.
+

 ### Stable endpoints
 /$INBOX/$MESSAGE_ID/                   -> HTML content
        anchors:
 ### Stable endpoints
 /$INBOX/$MESSAGE_ID/                   -> HTML content
        anchors:


@@ -25,7 +40,7 @@ URL and anchor naming
 
 /$INBOX/$MESSAGE_ID                    -> 301 to /$INBOX/$MESSAGE_ID/
 /$INBOX/$MESSAGE_ID/raw                -> raw mbox
 
 /$INBOX/$MESSAGE_ID                    -> 301 to /$INBOX/$MESSAGE_ID/
 /$INBOX/$MESSAGE_ID/raw                -> raw mbox

-/$INBOX/$MESSAGE_ID/R/                 -> HTML reply instructions
+/$INBOX/$MESSAGE_ID/#R                 -> HTML reply instructions

 
 # Covering up a pre-1.0 design mistake:
 /$INBOX/$MESSAGE_ID/f/                 -> 301 to /$INBOX/$MESSAGE_ID/
 
 # Covering up a pre-1.0 design mistake:
 /$INBOX/$MESSAGE_ID/f/                 -> 301 to /$INBOX/$MESSAGE_ID/


@@ -62,6 +77,23 @@ installed to render uncommon characters.
 Plain text (raw message) endpoints display in the original encoding(s)
 of the original email.
 
 Plain text (raw message) endpoints display in the original encoding(s)
 of the original email.
 

+Offline friendly
+----------------
+
+The "/t/", "/T/", "t.mbox.gz" endpoints are designed to be
+useful for reading long threads for users with intermittent
+connections or saved for offline viewing.
+
+Date displays are always absolute, not the "X hours ago"
+pattern commonly seen because readers may be reading a
+previously-saved or cached copy.
+
+HTML URLs end with '/' or "$FILENAME.html".  The reason many
+URLs end with the '/' character is so it can trivially be saved
+to a directory via wget or similar tools as "index.html", making
+it easy to mirror all files ending in ".html" using any static
+web server.
+

 Guidelines for using limited HTML
 ---------------------------------
 
 Guidelines for using limited HTML
 ---------------------------------
 


@@ -76,10 +108,9 @@ browsers default to.
 * No graphics, images, or icons at all.  We tolerate, but do not
   encourage the use of GUIs.
 
 * No graphics, images, or icons at all.  We tolerate, but do not
   encourage the use of GUIs.
 

-* No setting colors or font sizes, power to users to decide those.
+* No setting font sizes, power to users to decide those.

   We will include and document <span class=?> to support colors
   We will include and document <span class=?> to support colors

-  for user-supplied CSS, and may support client-supplied CSS
-  via cookie.
+  for user-supplied CSS.

 
 * Only one font type: fixed.  This is for accessibility, we must
   not blow certain elements out-of-proportion with different
 
 * Only one font type: fixed.  This is for accessibility, we must
   not blow certain elements out-of-proportion with different


@@ -99,15 +130,15 @@ browsers default to.
 * We only use CSS for one reason: wrapping pre-formatted text
   This is necessary because unfortunate GUI browsers tend to be
   prone to layout widening from unwrapped mailers.
 * We only use CSS for one reason: wrapping pre-formatted text
   This is necessary because unfortunate GUI browsers tend to be
   prone to layout widening from unwrapped mailers.

-  w3m is fine here without CSS :)
-  No other CSS is allowed, especially with scary things like:
+  Do not expect CSS to be enabled, especially with scary things like:

 
 

-       http://thejh.net/misc/website-terminal-copy-paste
+       https://thejh.net/misc/website-terminal-copy-paste

 
   However, we will try to make it easy for users to supply their
 
   However, we will try to make it easy for users to supply their

-  own colors and perhaps offer color options over cookies.
+  own colors via user-side CSS.

 
 CSS classes (for user-supplied CSS)
 -----------------------------------
 
 CSS classes (for user-supplied CSS)
 -----------------------------------

-span.q - quoted text in email messages
-...
+
+See examples in contrib/css/ and lib/PublicInbox/WwwText.pm
+(or https://public-inbox.org/meta/_/text/color/ soon)