lib/PublicInbox/WwwText.pm

   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>
   3
   4 # used for displaying help texts and other non-mail content
   5 package PublicInbox::WwwText;
   6 use strict;
   7 use warnings;
   8 use PublicInbox::Linkify;
   9 use PublicInbox::WwwStream;
  10 use PublicInbox::Hval qw(ascii_html);
  11 our $QP_URL = 'https://xapian.org/docs/queryparser.html';
  12 our $WIKI_URL = 'https://en.wikipedia.org/wiki';
  13
  14 # /$INBOX/_/text/$KEY/ # KEY may contain slashes
  15 # For now, "help" is the only supported $KEY
  16 sub get_text {
  17         my ($ctx, $key) = @_;
  18         my $code = 200;
  19
  20         $key = 'help' if !defined $key; # this 302s to _/text/help/
  21
  22         # get the raw text the same way we get mboxrds
  23         my $raw = ($key =~ s!/raw\z!!);
  24         my $have_tslash = ($key =~ s!/\z!!) if !$raw;
  25
  26         my $txt = '';
  27         if (!_default_text($ctx, $key, \$txt)) {
  28                 $code = 404;
  29                 $txt = "404 Not Found ($key)\n";
  30         }
  31         if ($raw) {
  32                 return [ $code, [ 'Content-Type', 'text/plain',
  33                                   'Content-Length', bytes::length($txt) ],
  34                         [ $txt ] ]
  35         }
  36
  37         # enforce trailing slash for "wget -r" compatibility
  38         if (!$have_tslash && $code == 200) {
  39                 my $url = $ctx->{-inbox}->base_url($ctx->{env});
  40                 $url .= "_/text/$key/";
  41
  42                 return [ 302, [ 'Content-Type', 'text/plain',
  43                                 'Location', $url ],
  44                         [ "Redirecting to $url\n" ] ];
  45         }
  46
  47         # Follow git commit message conventions,
  48         # first line is the Subject/title
  49         my ($title) = ($txt =~ /\A([^\n]*)/s);
  50         _do_linkify($txt);
  51         $ctx->{-title_html} = ascii_html($title);
  52
  53         my $nslash = ($key =~ tr!/!/!);
  54         $ctx->{-upfx} = '../../../' . ('../' x $nslash);
  55
  56         PublicInbox::WwwStream->response($ctx, $code, sub {
  57                 my ($nr, undef) = @_;
  58                 $nr == 1 ? '<pre>'.$txt.'</pre>' : undef
  59         });
  60 }
  61
  62 sub _do_linkify {
  63         my $l = PublicInbox::Linkify->new;
  64         $_[0] = $l->linkify_2(ascii_html($l->linkify_1($_[0])));
  65 }
  66
  67 sub _srch_prefix ($$) {
  68         my ($srch, $txt) = @_;
  69         my $pad = 0;
  70         my $htxt = '';
  71         my $help = $srch->help;
  72         my $i;
  73         for ($i = 0; $i < @$help; $i += 2) {
  74                 my $pfx = $help->[$i];
  75                 my $n = length($pfx);
  76                 $pad = $n if $n > $pad;
  77                 $htxt .= $pfx . "\0";
  78                 $htxt .= $help->[$i + 1];
  79                 $htxt .= "\f\n";
  80         }
  81         $pad += 2;
  82         my $padding = ' ' x ($pad + 8);
  83         $htxt =~ s/^/$padding/gms;
  84         $htxt =~ s/^$padding(\S+)\0/"        $1".
  85                                 (' ' x ($pad - length($1)))/egms;
  86         $htxt =~ s/\f\n/\n/gs;
  87         $$txt .= $htxt;
  88         1;
  89 }
  90
  91 sub _colors_help ($$) {
  92         my ($ctx, $txt) = @_;
  93         my $ibx = $ctx->{-inbox};
  94         my $base_url = $ibx->base_url($ctx->{env});
  95         $$txt .= "color customization for $base_url\n";
  96         $$txt .= <<EOF;
  97
  98 public-inbox provides a stable set of CSS classes for users to
  99 customize colors for highlighting diffs and code.
 100
 101 Users of browsers such as dillo, Firefox, or some browser
 102 extensions may start by downloading the following sample CSS file
 103 to control the colors they see:
 104
 105         ${base_url}userContent.css
 106
 107 CSS classes
 108 -----------
 109
 110            span.q - quoted text in email messages
 111
 112 For diff highlighting, we try to match class names with those
 113 used by cgit: https://git.zx2c4.com/cgit/
 114
 115          span.add - diff post-image lines
 116
 117          span.del - diff pre-image lines
 118
 119         span.head - diff header (metainformation)
 120
 121         span.hunk - diff hunk-header
 122
 123 EOF
 124 }
 125
 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?
 130
 131         my $ibx = $ctx->{-inbox};
 132         my $base_url = $ibx->base_url($ctx->{env});
 133         $$txt .= "public-inbox help for $base_url\n";
 134         $$txt .= <<EOF;
 135
 136 overview
 137 --------
 138
 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).
 144
 145     Thus, it is possible to retrieve any message by its
 146     Message-ID by going to:
 147
 148         $base_url<Message-ID>/
 149
 150         (without the '<' or '>')
 151
 152     Message-IDs are described at:
 153
 154         $WIKI_URL/Message-ID
 155
 156 EOF
 157
 158         # n.b. we use the Xapian DB for any regeneratable,
 159         # order-of-arrival-independent data.
 160         my $srch = $ibx->search;
 161         if ($srch) {
 162                 $$txt .= <<EOF;
 163 search
 164 ------
 165
 166     This public-inbox has search functionality provided by Xapian.
 167
 168     It supports typical AND, OR, NOT, '+', '-' queries present
 169     in other search engines.
 170
 171     We also support search prefixes to limit the scope of the
 172     search to certain fields.
 173
 174     Prefixes supported in this installation include:
 175
 176 EOF
 177                 _srch_prefix($srch, $txt);
 178
 179                 $$txt .= <<EOF;
 180
 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
 185     the query syntax:
 186
 187         $QP_URL
 188
 189 message threading
 190 -----------------
 191
 192     Message threading is enabled for this public-inbox,
 193     additional endpoints for message threads are available:
 194
 195     * $base_url<Message-ID>/T/#u
 196
 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>.
 200
 201     * $base_url<Message-ID>/t/#u
 202
 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.
 206
 207     Both of these HTML endpoints are suitable for offline reading
 208     using the thread overview at the bottom of each page.
 209
 210     Users of feed readers may follow a particular thread using:
 211
 212     * $base_url<Message-ID>/t.atom
 213
 214       Which loads the thread in Atom Syndication Standard
 215       described at Wikipedia and RFC4287:
 216
 217         $WIKI_URL/Atom_(standard)
 218         https://tools.ietf.org/html/rfc4287
 219
 220       Atom Threading Extensions (RFC4685) is supported:
 221
 222         https://tools.ietf.org/html/rfc4685
 223
 224     Finally, the gzipped mbox for a thread is available for
 225     downloading and importing into your favorite mail client:
 226
 227     * $base_url<Message-ID>/t.mbox.gz
 228
 229     We use the mboxrd variant of the mbox format described
 230     at:
 231
 232         $WIKI_URL/Mbox
 233
 234 contact
 235 -------
 236
 237     This help text is maintained by public-inbox developers
 238     reachable via plain-text email at: meta\@public-inbox.org
 239
 240 EOF
 241         # TODO: support admin contact info in ~/.public-inbox/config
 242         }
 243         1;
 244 }
 245
 246 1;