Documentation/design_www.txt

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