X-Git-Url: http://www.git.stargrave.org/?a=blobdiff_plain;f=Documentation%2Fdesign_www.txt;h=b1f916ddb3697606aaf623ada2ef3b607666e6f3;hb=0ae89efce11e1e3b10a067c61c5b4cde30fa2b3b;hp=0d25a45a5dae5039c99bf84e483fc07e5616b214;hpb=f93b46bea8cd2811d911f256447f9332b7fc6bfa;p=public-inbox.git diff --git a/Documentation/design_www.txt b/Documentation/design_www.txt index 0d25a45a..b1f916dd 100644 --- a/Documentation/design_www.txt +++ b/Documentation/design_www.txt @@ -1,45 +1,126 @@ -URL naming ----------- +PublicInbox::WWW (PSGI interface) design notes + +URL and anchor naming +--------------------- ### Unstable endpoints -/$LISTNAME/?r=$GIT_COMMIT -> HTML only -/$LISTNAME/index.atom.xml -> Atom feed -/$LISTNAME/all.atom.xml -> Atom feed, includes replies +/$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/m/$MESSAGE_ID.html -> HTML content (short quotes) -/$LISTNAME/m/$MESSAGE_ID.txt -> raw original -/$LISTNAME/m/$MESSAGE_ID -> 301 to .html version -/$LISTNAME/f/$MESSAGE_ID.html -> HTML content (full quotes) -/$LISTNAME/f/$MESSAGE_ID -> 301 to .html version -/$LISTNAME/f/$MESSAGE_ID.txt -> 301 to m/$MESSAGE_ID.txt +/$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) +/$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 + +Additionally, we support git clone/fetch over HTTP (dumb and smart): + + git clone --mirror http://$HOSTNAME/$INBOX + +FIXME: we must refactor/cleanup/add tests for most of our CGI before +adding more endpoints and features. + +[1] These URLs were never linked, but only exist as a convenience to folks + who edit existing URLs -Maybe TODO (these might be expensive) -------------------------------------- -/$LISTNAME/t/$MESSAGE_ID.html -> HTML content of thread -/$LISTNAME/t/$MESSAGE_ID.mbox -> mbox content of thread +[2] Do not make this into a 301 since feed readers may not follow them as well + as normal browsers do. -We use file name suffixes on all of these (except /) so URLs may easily -cached/memoized using a static file server. +Encoding notes +-------------- + +Raw HTML and XML should only contain us-ascii characters which render +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 --------------------------------- + We mainly use HTML for linking pages together with . 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. - -* Do not build <a> links from user-generated-content, this prevents - public-inbox deployments from being turned into a spam linkfarm. +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. 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 + not support them. Italics and strike-through elements must be + avoided as they do not render well with some displays or user-chosen + fonts. * No JavaScript. JS is historically too buggy and insecure, and we will never expect our readers to do either of the following: @@ -48,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. lynx 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)