public-inbox.git  about / heads / tags
an "archives first" approach to mailing lists
blob f15a55629745869ab34f4d0735c337d5b5035b31 4621 bytes (raw)
$ git show ci-WIP:Documentation/design_www.txt	# shows this blob on the CLI

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
PublicInbox::WWW (PSGI interface) design notes

URL and anchor naming
---------------------

### Unstable endpoints
/$INBOX/?r=$GIT_COMMIT                 -> HTML only
/$INBOX/new.atom                       -> Atom feed

#### Optional, relies on Search::Xapian
/$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<SHA-1>   per-message links, where <SHA-1> is of the Message-ID
	            of each message (stable)
	#s<NUM>     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

### Stable endpoints
/$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

[2] Do not make this into a 301 since feed readers may not follow them as well
    as normal browsers do.

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.

Guidelines for using limited HTML
---------------------------------

We mainly use HTML for linking pages together with <a>.
We also set <title> 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.

* No graphics, images, or icons at all.  We tolerate, but do not
  encourage the use of GUIs.

* 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:
  a) read and audit all our code for on every single page load
  b) trust us and and run code without reading it

* 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.
  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)
-----------------------------------

See examples in contrib/css/ and lib/PublicInbox/WwwText.pm
(or https://public-inbox.org/meta/_/text/color/ soon)

git clone https://public-inbox.org/public-inbox.git
git clone http://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/public-inbox.git