doc: lei: restore alphabetical order to some listings

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

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


@@ -107,8 +139,6 @@ browsers default to.
 
 CSS classes (for user-supplied CSS)
 -----------------------------------
 
 CSS classes (for user-supplied CSS)
 -----------------------------------

-span.q - quoted text in email messages

 
 

-TODO: consider using highlight(1) via libhighlight-perl in Debian,
-      optionally
-...
+See examples in contrib/css/ and lib/PublicInbox/WwwText.pm
+(or https://public-inbox.org/meta/_/text/color/ soon)