1 # Copyright (C) 2016-2018 all contributors <meta@public-inbox.org>
2 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
4 # used for displaying help texts and other non-mail content
5 package PublicInbox::WwwText;
8 use bytes (); # only for bytes::length
9 use PublicInbox::Linkify;
10 use PublicInbox::WwwStream;
11 use PublicInbox::Hval qw(ascii_html);
12 our $QP_URL = 'https://xapian.org/docs/queryparser.html';
13 our $WIKI_URL = 'https://en.wikipedia.org/wiki';
15 require PublicInbox::HlMod;
16 PublicInbox::HlMod->new
19 # /$INBOX/_/text/$KEY/ # KEY may contain slashes
20 # For now, "help" is the only supported $KEY
25 $key = 'help' if !defined $key; # this 302s to _/text/help/
27 # get the raw text the same way we get mboxrds
28 my $raw = ($key =~ s!/raw\z!!);
29 my $have_tslash = ($key =~ s!/\z!!) if !$raw;
32 if (!_default_text($ctx, $key, \$txt)) {
34 $txt = "404 Not Found ($key)\n";
37 return [ $code, [ 'Content-Type', 'text/plain',
38 'Content-Length', bytes::length($txt) ],
42 # enforce trailing slash for "wget -r" compatibility
43 if (!$have_tslash && $code == 200) {
44 my $url = $ctx->{-inbox}->base_url($ctx->{env});
45 $url .= "_/text/$key/";
47 return [ 302, [ 'Content-Type', 'text/plain',
49 [ "Redirecting to $url\n" ] ];
52 # Follow git commit message conventions,
53 # first line is the Subject/title
54 my ($title) = ($txt =~ /\A([^\n]*)/s);
56 $ctx->{-title_html} = ascii_html($title);
58 my $nslash = ($key =~ tr!/!/!);
59 $ctx->{-upfx} = '../../../' . ('../' x $nslash);
61 PublicInbox::WwwStream->response($ctx, $code, sub {
63 $nr == 1 ? '<pre>'.$txt.'</pre>' : undef
68 my $l = PublicInbox::Linkify->new;
71 $hl->do_hl_text(\($_[0]));
73 $_[0] = ascii_html($_[0]);
75 $_[0] = $l->linkify_2($_[0]);
78 sub _srch_prefix ($$) {
79 my ($srch, $txt) = @_;
82 my $help = $srch->help;
84 for ($i = 0; $i < @$help; $i += 2) {
85 my $pfx = $help->[$i];
87 $pad = $n if $n > $pad;
89 $htxt .= $help->[$i + 1];
93 my $padding = ' ' x ($pad + 8);
94 $htxt =~ s/^/$padding/gms;
95 $htxt =~ s/^$padding(\S+)\0/" $1".
96 (' ' x ($pad - length($1)))/egms;
97 $htxt =~ s/\f\n/\n/gs;
102 sub _colors_help ($$) {
103 my ($ctx, $txt) = @_;
104 my $ibx = $ctx->{-inbox};
105 my $env = $ctx->{env};
106 my $base_url = $ibx->base_url($env);
107 $$txt .= "color customization for $base_url\n";
110 public-inbox provides a stable set of CSS classes for users to
111 customize colors for highlighting diffs and code.
113 Users of browsers such as dillo, Firefox, or some browser
114 extensions may start by downloading the following sample CSS file
115 to control the colors they see:
117 ${base_url}userContent.css
123 $$txt .= PublicInbox::UserContent::sample($ibx, $env) . "```\n";
126 sub _default_text ($$$) {
127 my ($ctx, $key, $txt) = @_;
128 return _colors_help($ctx, $txt) if $key eq 'color';
129 return if $key ne 'help'; # TODO more keys?
131 my $ibx = $ctx->{-inbox};
132 my $base_url = $ibx->base_url($ctx->{env});
133 $$txt .= "public-inbox help for $base_url\n";
139 public-inbox uses Message-ID identifiers in URLs.
140 One may look up messages by substituting Message-IDs
141 (without the leading '<' or trailing '>') into the URL.
142 Forward slash ('/') characters in the Message-IDs
143 need to be escaped as "%2F" (without quotes).
145 Thus, it is possible to retrieve any message by its
146 Message-ID by going to:
148 $base_url<Message-ID>/
150 (without the '<' or '>')
152 Message-IDs are described at:
158 # n.b. we use the Xapian DB for any regeneratable,
159 # order-of-arrival-independent data.
160 my $srch = $ibx->search;
166 This public-inbox has search functionality provided by Xapian.
168 It supports typical AND, OR, NOT, '+', '-' queries present
169 in other search engines.
171 We also support search prefixes to limit the scope of the
172 search to certain fields.
174 Prefixes supported in this installation include:
177 _srch_prefix($srch, $txt);
181 Most prefixes are probabilistic, meaning they support stemming
182 and wildcards ('*'). Ranges (such as 'd:') and boolean prefixes
183 do not support stemming or wildcards.
184 The upstream Xapian query parser documentation fully explains
192 Message threading is enabled for this public-inbox,
193 additional endpoints for message threads are available:
195 * $base_url<Message-ID>/T/#u
197 Loads the thread belonging to the given <Message-ID>
198 in flat chronological order. The "#u" anchor
199 focuses the browser on the given <Message-ID>.
201 * $base_url<Message-ID>/t/#u
203 Loads the thread belonging to the given <Message-ID>
204 in threaded order with nesting. For deep threads,
205 this requires a wide display or horizontal scrolling.
207 Both of these HTML endpoints are suitable for offline reading
208 using the thread overview at the bottom of each page.
210 Users of feed readers may follow a particular thread using:
212 * $base_url<Message-ID>/t.atom
214 Which loads the thread in Atom Syndication Standard
215 described at Wikipedia and RFC4287:
217 $WIKI_URL/Atom_(standard)
218 https://tools.ietf.org/html/rfc4287
220 Atom Threading Extensions (RFC4685) is supported:
222 https://tools.ietf.org/html/rfc4685
224 Finally, the gzipped mbox for a thread is available for
225 downloading and importing into your favorite mail client:
227 * $base_url<Message-ID>/t.mbox.gz
229 We use the mboxrd variant of the mbox format described
237 This help text is maintained by public-inbox developers
238 reachable via plain-text email at: meta\@public-inbox.org
241 # TODO: support admin contact info in ~/.public-inbox/config