Documentation/design_www.txt

   1 URL and anchor naming
   2 ---------------------
   3
   4 ### Unstable endpoints
   5 /$LISTNAME/?r=$GIT_COMMIT                 -> HTML only
   6 /$LISTNAME/new.atom                       -> Atom feed
   7
   8 #### Optional, relies on Search::Xapian
   9 /$LISTNAME/$MESSAGE_ID/t/                 -> HTML content of thread
  10         anchors:
  11         #u          location of $MESSAGE_ID in URL
  12         #m<SHA-1>   per-message links, where <SHA-1> is of the Message-ID
  13                     of each message (stable)
  14         #s<NUM>     relative numeric position of message in thread (unstable)
  15
  16 /$LISTNAME/$MESSAGE_ID/t.atom             -> Atom feed for thread
  17 /$LISTNAME/$MESSAGE_ID/t.mbox.gz          -> gzipped mbox of thread
  18
  19 ### Stable endpoints
  20 /$LISTNAME/$MESSAGE_ID/                   -> HTML content
  21         anchors:
  22         #r          location of the current message in thread skeleton
  23                     (requires Xapian search)
  24         #b          start of the message body (linked from thread skeleton)
  25
  26 /$LISTNAME/$MESSAGE_ID                    -> 301 to /$LISTNAME/$MESSAGE_ID/
  27 /$LISTNAME/$MESSAGE_ID/raw                -> raw mbox
  28 /$LISTNAME/$MESSAGE_ID/R/                 -> HTML reply instructions
  29
  30 ### Legacy endpoints (may be ambiguous given Message-IDs with similar suffixes)
  31 /$LISTNAME/$MESSAGE_ID/f/                 -> HTML content
  32 /$LISTNAME/m/$MESSAGE_ID/                 -> 301 to /$LISTNAME/$MESSAGE_ID/
  33 /$LISTNAME/m/$MESSAGE_ID.html             -> 301 to /$LISTNAME/$MESSAGE_ID/
  34 /$LISTNAME/m/$MESSAGE_ID.txt              -> 301 to /$LISTNAME/$MESSAGE_ID/raw
  35 /$LISTNAME/f/$MESSAGE_ID.html             -> 301 to /$LISTNAME/$MESSAGE_ID/f/
  36 /$LISTNAME/f/$MESSAGE_ID.txt [1]          -> 301 to /$LISTNAME/$MESSAGE_ID/raw
  37
  38 /$LISTNAME/atom.xml [2]                   -> identical to /$LISTNAME/new.atom
  39
  40 Additionally, we support git clone/fetch over HTTP (dumb and smart):
  41
  42         git clone --mirror http://$HOSTNAME/$LISTNAME
  43
  44 FIXME: we must refactor/cleanup/add tests for most of our CGI before
  45 adding more endpoints and features.
  46
  47 [1] These URLs were never linked, but only exist as a convenience to folks
  48     who edit existing URLs
  49
  50 [2] Do not make this into a 301 since feed readers may not follow them as well
  51     as normal browsers do.
  52
  53 Encoding notes
  54 --------------
  55
  56 Raw HTML and XML should only contain us-ascii characters which render
  57 to UTF-8.  We must not rely on users having the necessary fonts
  58 installed to render uncommon characters.
  59
  60 Plain text (raw message) endpoints display in the original encoding(s)
  61 of the original email.
  62
  63 Guidelines for using limited HTML
  64 ---------------------------------
  65
  66 We mainly use HTML for linking pages together with <a>.
  67 We also set <title> to make window management easier.
  68
  69 We favor <pre>-formatted text since public-inbox is intended as a place
  70 to share and discuss patches and code.  Unfortunately, long paragraphs
  71 tends to be less readable with fixed-width serif fonts which GUI
  72 browsers default to.
  73
  74 * No graphics, images, or icons at all.  We tolerate, but do not
  75   encourage the use of GUIs.
  76
  77 * No setting colors or font sizes, power to users to decide those.
  78   We will include and document <span class=?> to support colors
  79   for user-supplied CSS, and may support client-supplied CSS
  80   via cookie.
  81
  82 * Only one font type: fixed.  This is for accessibility, we must
  83   not blow certain elements out-of-proportion with different
  84   fonts on the page when a reader increases font size.
  85
  86 * Bold and underline elements are OK since they should render fine
  87   regardless of chosen font and gracefully degrade if a display does
  88   not support them.  Italics and strike-through elements must be
  89   avoided as they do not render well with some displays or user-chosen
  90   fonts.
  91
  92 * No JavaScript. JS is historically too buggy and insecure, and we will
  93   never expect our readers to do either of the following:
  94   a) read and audit all our code for on every single page load
  95   b) trust us and and run code without reading it
  96
  97 * We only use CSS for one reason: wrapping pre-formatted text
  98   This is necessary because unfortunate GUI browsers tend to be
  99   prone to layout widening from unwrapped mailers.
 100   w3m is fine here without CSS :)
 101   No other CSS is allowed, especially with scary things like:
 102
 103         http://thejh.net/misc/website-terminal-copy-paste
 104
 105   However, we will try to make it easy for users to supply their
 106   own colors and perhaps offer color options over cookies.
 107
 108 CSS classes (for user-supplied CSS)
 109 -----------------------------------
 110 span.q  - quoted text in email messages
 111 ...