X-Git-Url: http://www.git.stargrave.org/?a=blobdiff_plain;f=Documentation%2Fdesign_www.txt;h=b1f916ddb3697606aaf623ada2ef3b607666e6f3;hb=HEAD;hp=18b716c7981a7fab2dfe014a9bb2fe8e32fc3f35;hpb=474a987a2ba9183ceb9e143aeccdc49c7cb5f382;p=public-inbox.git diff --git a/Documentation/design_www.txt b/Documentation/design_www.txt index 18b716c7..b1f916dd 100644 --- a/Documentation/design_www.txt +++ b/Documentation/design_www.txt @@ -1,45 +1,62 @@ +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 +#### 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 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 + +/$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. -/$LISTNAME/$MESSAGE_ID/t.atom -> Atom feed for thread -/$LISTNAME/$MESSAGE_ID/t.mbox.gz -> gzipped mbox of thread +/$INBOX/$GIT_OID/s/$FILENAME -> "git show", raw output + As above, but shows the raw (usually text/plain) output. ### Stable endpoints -/$LISTNAME/$MESSAGE_ID/ -> HTML content +/$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) -/$LISTNAME/$MESSAGE_ID -> 301 to /$LISTNAME/$MESSAGE_ID/ -/$LISTNAME/$MESSAGE_ID/raw -> raw mbox -/$LISTNAME/$MESSAGE_ID/R/ -> HTML reply instructions +/$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/$MESSAGE_ID/f/ -> HTML content -/$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 -/$LISTNAME/atom.xml [2] -> identical to /$LISTNAME/new.atom +/$INBOX/atom.xml [2] -> identical to /$INBOX/new.atom Additionally, we support git clone/fetch over HTTP (dumb and smart): - git clone --mirror http://$HOSTNAME/$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. @@ -60,6 +77,23 @@ installed to render uncommon characters. 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 --------------------------------- @@ -74,10 +108,9 @@ 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 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 @@ -97,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. - 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 - own colors and perhaps offer color options over cookies. + own colors via user-side 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)