]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/design_www.txt
git_async_cat: fix outdated comment
[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 (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 Offline friendly
81 ----------------
82
83 The "/t/", "/T/", "t.mbox.gz" endpoints are designed to be
84 useful for reading long threads for users with intermittent
85 connections or saved for offline viewing.
86
87 Date displays are always absolute, not the "X hours ago"
88 pattern commonly seen because readers may be reading a
89 previously-saved or cached copy.
90
91 HTML URLs end with '/' or "$FILENAME.html".  The reason many
92 URLs end with the '/' character is so it can trivially be saved
93 to a directory via wget or similar tools as "index.html", making
94 it easy to mirror all files ending in ".html" using any static
95 web server.
96
97 Guidelines for using limited HTML
98 ---------------------------------
99
100 We mainly use HTML for linking pages together with <a>.
101 We also set <title> to make window management easier.
102
103 We favor <pre>-formatted text since public-inbox is intended as a place
104 to share and discuss patches and code.  Unfortunately, long paragraphs
105 tends to be less readable with fixed-width serif fonts which GUI
106 browsers default to.
107
108 * No graphics, images, or icons at all.  We tolerate, but do not
109   encourage the use of GUIs.
110
111 * No setting font sizes, power to users to decide those.
112   We will include and document <span class=?> to support colors
113   for user-supplied CSS.
114
115 * Only one font type: fixed.  This is for accessibility, we must
116   not blow certain elements out-of-proportion with different
117   fonts on the page when a reader increases font size.
118
119 * Bold and underline elements are OK since they should render fine
120   regardless of chosen font and gracefully degrade if a display does
121   not support them.  Italics and strike-through elements must be
122   avoided as they do not render well with some displays or user-chosen
123   fonts.
124
125 * No JavaScript. JS is historically too buggy and insecure, and we will
126   never expect our readers to do either of the following:
127   a) read and audit all our code for on every single page load
128   b) trust us and and run code without reading it
129
130 * We only use CSS for one reason: wrapping pre-formatted text
131   This is necessary because unfortunate GUI browsers tend to be
132   prone to layout widening from unwrapped mailers.
133   Do not expect CSS to be enabled, especially with scary things like:
134
135         https://thejh.net/misc/website-terminal-copy-paste
136
137   However, we will try to make it easy for users to supply their
138   own colors via user-side CSS.
139
140 CSS classes (for user-supplied CSS)
141 -----------------------------------
142
143 See examples in contrib/css/ and lib/PublicInbox/WwwText.pm
144 (or https://public-inbox.org/meta/_/text/color/ soon)