foreseen

A text-based gemini browser with prefetching
git clone git://git.laack.co/foreseen.git
Log | Files | Refs | README | LICENSE

foreseen.1 (3510B)


      1 .TH foreseen 1 foreseen\- v0.0.1
      2 .SH NAME
      3 foreseen
      4 .SH SYNOPSIS
      5 .B foreseen [--help] [--version] [--cache-pages VAR] [--prefetch-links VAR] [--search-engine VAR] destination
      6 .SH DESCRIPTION
      7 foreseen is a Gemini protocol browser built for performance and simplicity.
      8 
      9 .SH CACHING
     10 All caching is done in memory with a configurable FIFO data structure to limit
     11 cached page count.
     12 There are two separate instances of the cache object at any given time:
     13 one for prefetching and one for history.
     14 .PP
     15 Pages fetched with an identity are never cached, and prefetching never sends
     16 requests to hosts you'd use an identity for.
     17 .SS Prefetch caching
     18 One of the main reasons this browser feels so much faster than other Gemini
     19 protocol browsers is its optional prefetch caching.
     20 This is enabled by default.
     21 When you visit a site without an identity, a thread will be created that
     22 fetches the first 10 links on the page, caching them if they return a 2X
     23 status code.
     24 This enables near-instantaneous visitation of those links.
     25 Prefetch caching is only enabled when you aren't using an identity for a
     26 domain.
     27 .PP
     28 Per the gemtext specification, "clients must not automatically make any
     29 network connections as part of displaying links", so this mode of operation
     30 may be construed as non-compliant with the gemtext specification.
     31 I don't believe a file format specification should be prescriptive about such
     32 things.
     33 Additionally, if this was a feature in an HTTP-based web browser, I would
     34 disable it.
     35 I perceive Gemini as being more trustworthy right now and thus am not
     36 concerned about having this defaulted on.
     37 .SS History caching
     38 When you visit a page, the page will be cached after it's loaded.
     39 If the page was in the prefetch cache before, it will be upgraded to the
     40 history cache, because visited pages are more important than prefetched ones.
     41 When using identities, history caching only applies for forward and backward
     42 navigation, not when visiting a previous site via a link or URL.
     43 .SH IDENTITIES
     44 Identities are specified in:
     45 .PP
     46 .RS
     47 .EX
     48 $HOME/.foreseen/{hostname}/client.crt
     49 $HOME/.foreseen/{hostname}/client.key
     50 .EE
     51 .RE
     52 .PP
     53 Or, for a non-standard port (port != 1965):
     54 .PP
     55 .RS
     56 .EX
     57 $HOME/.foreseen/{hostname}:{port}/client.crt
     58 $HOME/.foreseen/{hostname}:{port}/client.key
     59 .EE
     60 .RE
     61 .PP
     62 Example layout:
     63 .PP
     64 .RS
     65 .EX
     66 $ tree .foreseen
     67 \&.foreseen
     68 \(ba\-\- bbs.geminispace.org
     69     |\-\- client.crt
     70     \`\-\- client.key
     71 .EE
     72 .RE
     73 .PP
     74 Example command to generate keys:
     75 .PP
     76 .RS
     77 .EX
     78 openssl req \-x509 \-newkey rsa:2048 \-nodes \-days 3650 \-keyout client.key \e
     79     \-out client.crt \-subj "/CN=localhost"
     80 .EE
     81 .RE
     82 
     83 
     84 .SH OPTIONS
     85 .TP
     86 .B -h, --help \n
     87 shows help message and exits 
     88 
     89 .TP
     90 .B  -v, --version
     91 prints version information and exits
     92 
     93 .TP
     94 .B  -c, --cache-pages
     95 max number of pages for each cache (history, prefetch) [nargs=0..1] [default: 500]
     96 
     97 .TP
     98 .B -p, --prefetch-links 
     99 max number of links to prefetch per page (0 disables prefetching) [nargs=0..1] [default: 10]
    100 
    101 .TP
    102 .B -e, --search-engine
    103 default search engine [nargs=0..1] [default: "gemini://tlgs.one/search"]
    104 
    105 .SH EXAMPLES
    106 
    107 Specify the default search engine:
    108 .PP
    109 .RS
    110 .EX
    111 foreseen \-e gemini://kennedy.gemi.dev/search
    112 .EE
    113 .RE
    114 .PP
    115 Disable prefetching:
    116 .PP
    117 .RS
    118 .EX
    119 foreseen \-p 0
    120 .EE
    121 .RE
    122 .PP
    123 Limit cache sizes:
    124 .PP
    125 .RS
    126 .EX
    127 foreseen \-c 10
    128 .EE
    129 .RE
    130 .PP
    131 Open a local file on startup:
    132 .PP
    133 .RS
    134 .EX
    135 foreseen sites/index.gmi
    136 .EE
    137 .RE
    138 Prefetch first 20 links:
    139 .PP
    140 .RS
    141 .EX
    142 foreseen \-c 20
    143 .EE
    144 .RE
    145 .SH BUGS
    146 Send all bug reports with an optional patch to
    147 .MT andrew@laack.co
    148 .ME .