X-Git-Url: http://www.git.stargrave.org/?a=blobdiff_plain;f=Documentation%2Fdesign_www.txt;h=f15a55629745869ab34f4d0735c337d5b5035b31;hb=0acad050fe38033baedfed83f5976aeabebf3287;hp=1be4d18e28e1602dc0ae8d13032560fec3c25cb2;hpb=62a77b55c9fadec1b4b1ba061e99f4a18d8a14bc;p=public-inbox.git diff --git a/Documentation/design_www.txt b/Documentation/design_www.txt index 1be4d18e..f15a5562 100644 --- a/Documentation/design_www.txt +++ b/Documentation/design_www.txt @@ -1,32 +1,52 @@ -URL naming ----------- +PublicInbox::WWW (PSGI interface) design notes + +URL and anchor naming +--------------------- ### 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 -/$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 (nested) +/$INBOX/$MESSAGE_ID/T/ -> HTML content of thread (flat) + anchors: + #u location of $MESSAGE_ID in URL + #m per-message links, where is of the Message-ID + of each message (stable) + #s 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 ### 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) -/$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. @@ -41,7 +61,8 @@ Encoding notes -------------- 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. @@ -55,17 +76,18 @@ We also set 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 -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 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 @@ -80,7 +102,16 @@ variable-width fonts. * 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) +----------------------------------- - http://thejh.net/misc/website-terminal-copy-paste +See examples in contrib/css/ and lib/PublicInbox/WwwText.pm +(or https://public-inbox.org/meta/_/text/color/ soon)