public-inbox 1.1.0-pre1

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

diff --git a/Documentation/design_www.txt b/Documentation/design_www.txt
index 1be4d18e28e1602dc0ae8d13032560fec3c25cb2..514f8ff7d9596e3bbd10db5c21e9218c675e1118 100644 (file)
--- a/Documentation/design_www.txt
+++ b/Documentation/design_www.txt
@@ -1,32 +1,47 @@
-URL naming
-----------
+URL and anchor naming
+---------------------

 
 ### Unstable endpoints
 
 ### Unstable endpoints

-/$LISTNAME/?r=$GIT_COMMIT                 -> HTML only
-/$LISTNAME/new.atom                       -> Atom feed
+/$INBOX/?r=$GIT_COMMIT                 -> HTML only
+/$INBOX/new.atom                       -> Atom feed

 
 #### Optional, relies on Search::Xapian
 
 #### Optional, relies on Search::Xapian

-/$LISTNAME/$MESSAGE_ID/t/                 -> HTML content of thread
-/$LISTNAME/$MESSAGE_ID/t.atom             -> Atom feed for thread
-/$LISTNAME/$MESSAGE_ID/t.mbox.gz          -> gzipped mbox of thread
+/$INBOX/$MESSAGE_ID/t/                 -> HTML content of thread
+       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)
+
+/$INBOX/$MESSAGE_ID/t.atom             -> Atom feed for thread
+/$INBOX/$MESSAGE_ID/t.mbox.gz          -> gzipped mbox of thread

 
 ### Stable endpoints
 
 ### Stable endpoints

-/$LISTNAME/$MESSAGE_ID/                   -> HTML content (short quotes)
-/$LISTNAME/$MESSAGE_ID                    -> 301 to /$LISTNAME/$MESSAGE_ID
-/$LISTNAME/$MESSAGE_ID/raw                -> raw mbox
-/$LISTNAME/$MESSAGE_ID/f/                 -> HTML content (full quotes)
-/$LISTNAME/$MESSAGE_ID/R/                 -> HTML reply instructions
+/$INBOX/$MESSAGE_ID/                   -> HTML content
+       anchors:
+       #r          location of the current message in thread skeleton
+                   (requires Xapian search)
+       #b          start of the message body (linked from thread skeleton)
+
+/$INBOX/$MESSAGE_ID                    -> 301 to /$INBOX/$MESSAGE_ID/
+/$INBOX/$MESSAGE_ID/raw                -> raw mbox
+/$INBOX/$MESSAGE_ID/#R                 -> HTML reply instructions
+
+# Covering up a pre-1.0 design mistake:
+/$INBOX/$MESSAGE_ID/f/                 -> 301 to /$INBOX/$MESSAGE_ID/

 
 ### Legacy endpoints (may be ambiguous given Message-IDs with similar suffixes)
 
 ### Legacy endpoints (may be ambiguous given Message-IDs with similar suffixes)

-/$LISTNAME/m/$MESSAGE_ID/                 -> 301 to /$LISTNAME/$MESSAGE_ID/
-/$LISTNAME/m/$MESSAGE_ID.html             -> 301 to /$LISTNAME/$MESSAGE_ID/
-/$LISTNAME/m/$MESSAGE_ID.txt              -> 301 to /$LISTNAME/$MESSAGE_ID/raw
-/$LISTNAME/f/$MESSAGE_ID.html             -> 301 to /$LISTNAME/$MESSAGE_ID/f/
-/$LISTNAME/f/$MESSAGE_ID.txt [1]          -> 301 to /$LISTNAME/$MESSAGE_ID/raw
+/$INBOX/m/$MESSAGE_ID/                 -> 301 to /$INBOX/$MESSAGE_ID/
+/$INBOX/m/$MESSAGE_ID.html             -> 301 to /$INBOX/$MESSAGE_ID/
+/$INBOX/m/$MESSAGE_ID.txt              -> 301 to /$INBOX/$MESSAGE_ID/raw
+/$INBOX/f/$MESSAGE_ID.html             -> 301 to /$INBOX/$MESSAGE_ID/
+/$INBOX/f/$MESSAGE_ID.txt [1]          -> 301 to /$INBOX/$MESSAGE_ID/raw
+
+/$INBOX/atom.xml [2]                   -> identical to /$INBOX/new.atom

 
 

-/$LISTNAME/atom.xml [2]                   -> identical to /$LISTNAME/new.atom
+Additionally, we support git clone/fetch over HTTP (dumb and smart):

 
 

-Additionally, we support "git clone" pointed to http://$HOST/$LISTNAME
+       git clone --mirror http://$HOSTNAME/$INBOX

 
 FIXME: we must refactor/cleanup/add tests for most of our CGI before
 adding more endpoints and features.
 
 FIXME: we must refactor/cleanup/add tests for most of our CGI before
 adding more endpoints and features.


@@ -41,7 +56,8 @@ Encoding notes
 --------------
 
 Raw HTML and XML should only contain us-ascii characters which render
 --------------
 
 Raw HTML and XML should only contain us-ascii characters which render

-to UTF-8.
+to UTF-8.  We must not rely on users having the necessary fonts
+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.


@@ -55,17 +71,18 @@ We also set <title> to make window management easier.
 We favor <pre>-formatted text since public-inbox is intended as a place
 to share and discuss patches and code.  Unfortunately, long paragraphs
 tends to be less readable with fixed-width serif fonts which GUI
 We favor <pre>-formatted text since public-inbox is intended as a place
 to share and discuss patches and code.  Unfortunately, long paragraphs
 tends to be less readable with fixed-width serif fonts which GUI

-browsers default to.  So perhaps we will add different endpoints for
-variable-width fonts.
+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
+  for user-supplied CSS.

 
 

-* Only one font type (fixed or variable) per page.  This is for
-  accessibility, we must not blow certain elements out-of-proportion
-  when a reader increases font size.
+* Only one font type: fixed.  This is for accessibility, we must
+  not blow certain elements out-of-proportion with different
+  fonts on the page when a reader increases font size.

 
 * Bold and underline elements are OK since they should render fine
   regardless of chosen font and gracefully degrade if a display does
 
 * Bold and underline elements are OK since they should render fine
   regardless of chosen font and gracefully degrade if a display does


@@ -80,7 +97,18 @@ variable-width fonts.
 
 * We only use CSS for one reason: wrapping pre-formatted text
   This is necessary because unfortunate GUI browsers tend to be
 
 * 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.  w3m is fine here without CSS :)
-  No other CSS is allowed, especially with scary things like:
+  prone to layout widening from unwrapped mailers.
+  Do not expect CSS to be enabled, especially with scary things like:
+
+       https://thejh.net/misc/website-terminal-copy-paste
+
+  However, we will try to make it easy for users to supply their
+  own colors via user-side CSS.
+
+CSS classes (for user-supplied CSS)
+-----------------------------------
+span.q - quoted text in email messages

 
 

-       http://thejh.net/misc/website-terminal-copy-paste
+TODO: consider using highlight(1) via libhighlight-perl in Debian,
+      optionally
+...