ds: share long_step between NNTP and IMAP

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

diff --git a/Documentation/design_www.txt b/Documentation/design_www.txt
index c7d7fcbc7900183d646be7da73e7dfccf5c1ae8c..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:


@@ -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
 ---------------------------------