]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/design_www.txt
doc: clean-doc: remove generated standards.txt
[public-inbox.git] / 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
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 ### Stable endpoints
25 /$INBOX/$MESSAGE_ID/                   -> HTML content
26         anchors:
27         #r          location of the current message in thread skeleton
28                     (requires Xapian search)
29         #b          start of the message body (linked from thread skeleton)
30
31 /$INBOX/$MESSAGE_ID                    -> 301 to /$INBOX/$MESSAGE_ID/
32 /$INBOX/$MESSAGE_ID/raw                -> raw mbox
33 /$INBOX/$MESSAGE_ID/#R                 -> HTML reply instructions
34
35 # Covering up a pre-1.0 design mistake:
36 /$INBOX/$MESSAGE_ID/f/                 -> 301 to /$INBOX/$MESSAGE_ID/
37
38 ### Legacy endpoints (may be ambiguous given Message-IDs with similar suffixes)
39 /$INBOX/m/$MESSAGE_ID/                 -> 301 to /$INBOX/$MESSAGE_ID/
40 /$INBOX/m/$MESSAGE_ID.html             -> 301 to /$INBOX/$MESSAGE_ID/
41 /$INBOX/m/$MESSAGE_ID.txt              -> 301 to /$INBOX/$MESSAGE_ID/raw
42 /$INBOX/f/$MESSAGE_ID.html             -> 301 to /$INBOX/$MESSAGE_ID/
43 /$INBOX/f/$MESSAGE_ID.txt [1]          -> 301 to /$INBOX/$MESSAGE_ID/raw
44
45 /$INBOX/atom.xml [2]                   -> identical to /$INBOX/new.atom
46
47 Additionally, we support git clone/fetch over HTTP (dumb and smart):
48
49         git clone --mirror http://$HOSTNAME/$INBOX
50
51 FIXME: we must refactor/cleanup/add tests for most of our CGI before
52 adding more endpoints and features.
53
54 [1] These URLs were never linked, but only exist as a convenience to folks
55     who edit existing URLs
56
57 [2] Do not make this into a 301 since feed readers may not follow them as well
58     as normal browsers do.
59
60 Encoding notes
61 --------------
62
63 Raw HTML and XML should only contain us-ascii characters which render
64 to UTF-8.  We must not rely on users having the necessary fonts
65 installed to render uncommon characters.
66
67 Plain text (raw message) endpoints display in the original encoding(s)
68 of the original email.
69
70 Guidelines for using limited HTML
71 ---------------------------------
72
73 We mainly use HTML for linking pages together with <a>.
74 We also set <title> to make window management easier.
75
76 We favor <pre>-formatted text since public-inbox is intended as a place
77 to share and discuss patches and code.  Unfortunately, long paragraphs
78 tends to be less readable with fixed-width serif fonts which GUI
79 browsers default to.
80
81 * No graphics, images, or icons at all.  We tolerate, but do not
82   encourage the use of GUIs.
83
84 * No setting font sizes, power to users to decide those.
85   We will include and document <span class=?> to support colors
86   for user-supplied CSS.
87
88 * Only one font type: fixed.  This is for accessibility, we must
89   not blow certain elements out-of-proportion with different
90   fonts on the page when a reader increases font size.
91
92 * Bold and underline elements are OK since they should render fine
93   regardless of chosen font and gracefully degrade if a display does
94   not support them.  Italics and strike-through elements must be
95   avoided as they do not render well with some displays or user-chosen
96   fonts.
97
98 * No JavaScript. JS is historically too buggy and insecure, and we will
99   never expect our readers to do either of the following:
100   a) read and audit all our code for on every single page load
101   b) trust us and and run code without reading it
102
103 * We only use CSS for one reason: wrapping pre-formatted text
104   This is necessary because unfortunate GUI browsers tend to be
105   prone to layout widening from unwrapped mailers.
106   Do not expect CSS to be enabled, especially with scary things like:
107
108         https://thejh.net/misc/website-terminal-copy-paste
109
110   However, we will try to make it easy for users to supply their
111   own colors via user-side CSS.
112
113 CSS classes (for user-supplied CSS)
114 -----------------------------------
115
116 See examples in contrib/css/ and lib/PublicInbox/WwwText.pm
117 (or https://public-inbox.org/meta/_/text/color/ soon)