X-Git-Url: http://www.git.stargrave.org/?a=blobdiff_plain;f=Documentation%2Fdesign_www.txt;h=b1f916ddb3697606aaf623ada2ef3b607666e6f3;hb=10e0e2052b2c2a4bb405cfbb4c2c72464671152d;hp=39b124143fd313baa17b6ea80bd94d7e85fb7854;hpb=0af0bd903b9b5aede71155ce8756e01a229b40bb;p=public-inbox.git diff --git a/Documentation/design_www.txt b/Documentation/design_www.txt index 39b12414..b1f916dd 100644 --- a/Documentation/design_www.txt +++ b/Documentation/design_www.txt @@ -1,31 +1,62 @@ -URL naming ----------- +PublicInbox::WWW (PSGI interface) design notes -### Unstable endpoints -/$LISTNAME/?r=$GIT_COMMIT -> HTML only -/$LISTNAME/new.atom -> Atom feed +URL and anchor naming +--------------------- -#### 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 +### Unstable endpoints +/$INBOX/?r=$GIT_COMMIT -> HTML only +/$INBOX/new.atom -> Atom feed + +#### 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. + +/$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 (short quotes) -/$LISTNAME/$MESSAGE_ID -> 301 to /$LISTNAME/$MESSAGE_ID -/$LISTNAME/$MESSAGE_ID/raw -> raw mbox -/$LISTNAME/$MESSAGE_ID/f/ -> HTML content (full quotes) +/$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. @@ -40,11 +71,29 @@ 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. +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 --------------------------------- @@ -54,17 +103,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 @@ -79,7 +129,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)