about summary refs log tree commit diff stats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--bollux.1186
-rw-r--r--bollux.conf.5382
2 files changed, 284 insertions, 284 deletions
diff --git a/bollux.1 b/bollux.1 index dc397be..ce32e8d 100644 --- a/bollux.1 +++ b/bollux.1
@@ -1,93 +1,93 @@
1.TH bollux 1 0.4.0 1.TH bollux 1 0.4.0
2.SH NAME 2.SH NAME
3bollux \- gemini protocol browser written in 3bollux \- gemini protocol browser written in
4.BR bash (1) 4.BR bash (1)
5.SH SYNOPSIS 5.SH SYNOPSIS
6.B bollux 6.B bollux
7.RI [ \-h ] 7.RI [ \-h ]
8.TP 8.TP
9.B bollux 9.B bollux
10.RI [ \-q ] 10.RI [ \-q ]
11.RI [ \-v ] 11.RI [ \-v ]
12.\".RI [ \-c 12.\".RI [ \-c
13.\".BR CONFIG ] 13.\".BR CONFIG ]
14.RB [ URL ] 14.RB [ URL ]
15.SH DESCRIPTION 15.SH DESCRIPTION
16.BR bollux (1) 16.BR bollux (1)
17is a browser for the new Gemini protocol, which aims to be 17is a browser for the new Gemini protocol, which aims to be
18"heavier than gopher, but lighter than the web." 18"heavier than gopher, but lighter than the web."
19It can follow links, collect user input, download files, and display text/* mimetype pages in geminispace. 19It can follow links, collect user input, download files, and display text/* mimetype pages in geminispace.
20.SH OPTIONS 20.SH OPTIONS
21.TP 21.TP
22.B \-h 22.B \-h
23Display an inline help screen and exit 23Display an inline help screen and exit
24.TP 24.TP
25.B \-q 25.B \-q
26Be quiet: don't show any messages, even fatal ones 26Be quiet: don't show any messages, even fatal ones
27.TP 27.TP
28.B \-v 28.B \-v
29Be verbose: show all messages, even debug ones 29Be verbose: show all messages, even debug ones
30.\".TP 30.\".TP
31.\".B \-c CONFIG 31.\".B \-c CONFIG
32.\"Use CONFIG file to configure 32.\"Use CONFIG file to configure
33.\".BR bollux (1) 33.\".BR bollux (1)
34.\"instead of the default: $XDG_CONFIG_HOME/bollux/bollux.conf. 34.\"instead of the default: $XDG_CONFIG_HOME/bollux/bollux.conf.
35.TP 35.TP
36.B URL 36.B URL
37The gemini URL to navigate to 37The gemini URL to navigate to
38.SH USAGE 38.SH USAGE
39If 39If
40.BR bollux (1) 40.BR bollux (1)
41is invoked with a URL, it will download or display that URL. 41is invoked with a URL, it will download or display that URL.
42Otherwise, the user will be prompted for a URL to download or display. 42Otherwise, the user will be prompted for a URL to download or display.
43If the URL points to a text/* document, it is paged with 43If the URL points to a text/* document, it is paged with
44.BR less (1) 44.BR less (1)
45with custom keybinds: 45with custom keybinds:
46.TP 46.TP
47.B o 47.B o
48open a link on the current page 48open a link on the current page
49.TP 49.TP
50.B g 50.B g
51goto a new URL 51goto a new URL
52.TP 52.TP
53.B G 53.B G
54goto a new URL - with current URL pre-filled 54goto a new URL - with current URL pre-filled
55.TP 55.TP
56.B r 56.B r
57refresh the current page 57refresh the current page
58.TP 58.TP
59.B [ 59.B [
60goto the previous page in history 60goto the previous page in history
61.TP 61.TP
62.B ] 62.B ]
63goto the next page in history 63goto the next page in history
64.TP 64.TP
65.B q 65.B q
66quit bollux 66quit bollux
67.TP 67.TP
68.B \= 68.B \=
69show a short help message 69show a short help message
70.PP 70.PP
71If a new URL is selected, 71If a new URL is selected,
72.BR bollux (1) 72.BR bollux (1)
73will repeat the download-and-display loop with the new URL. 73will repeat the download-and-display loop with the new URL.
74.PP 74.PP
75If the mimetype is other than text/*, 75If the mimetype is other than text/*,
76.BR bollux (1) 76.BR bollux (1)
77will attempt to download the file to 77will attempt to download the file to
78.B $BOLLUX_DOWNDIR 78.B $BOLLUX_DOWNDIR
79(which defaults to '.'). 79(which defaults to '.').
80.PP 80.PP
81.BR bollux (1) 81.BR bollux (1)
82also supports the gopher protocol, 82also supports the gopher protocol,
83which is browsed the same way as the gemini protocol 83which is browsed the same way as the gemini protocol
84(except the URL starts with 'gopher://'). 84(except the URL starts with 'gopher://').
85Gopher support is as of now rudimentary. 85Gopher support is as of now rudimentary.
86.SH ISSUES 86.SH ISSUES
87Certificate handling needs to be much improved: TOFU needs to be implemented 87Certificate handling needs to be much improved: TOFU needs to be implemented
88and bollux should be able to generate client certificates. 88and bollux should be able to generate client certificates.
89.SH SEE ALSO 89.SH SEE ALSO
90.BR bollux.conf (5) 90.BR bollux.conf (5)
91.SH BUGS 91.SH BUGS
92The development repo is located at https://sr.ht/~acdw/bollux. 92The development repo is located at https://sr.ht/~acdw/bollux.
93Please direct all bug reports, patches, or general complaints there. 93Please direct all bug reports, patches, or general complaints there.
diff --git a/bollux.conf.5 b/bollux.conf.5 index 9f431db..e4b2c54 100644 --- a/bollux.conf.5 +++ b/bollux.conf.5
@@ -1,191 +1,191 @@
1.TH bollux.conf 5 0.4.0 1.TH bollux.conf 5 0.4.0
2.SH NAME 2.SH NAME
3.B bollux.conf 3.B bollux.conf
4\- configuration file for 4\- configuration file for
5.BR bollux (1) 5.BR bollux (1)
6.SH DESCRIPTION 6.SH DESCRIPTION
7.BR bollux (1) 7.BR bollux (1)
8uses a number of environment variables that can be sourced from an external file, 8uses a number of environment variables that can be sourced from an external file,
9usually placed in 9usually placed in
10.IR $XDG_CONFIG_HOME/bollux/bollux.conf . 10.IR $XDG_CONFIG_HOME/bollux/bollux.conf .
11The location can be changed at runtime by invoking 11The location can be changed at runtime by invoking
12.BR "bollux \-c CONFIG" . 12.BR "bollux \-c CONFIG" .
13.SH VARIABLES 13.SH VARIABLES
14.SS Variables you might actually want to set 14.SS Variables you might actually want to set
15Here are actually useful variables that are good things to set in your 15Here are actually useful variables that are good things to set in your
16.IR bollux.conf , 16.IR bollux.conf ,
17in order of usefulness. 17in order of usefulness.
18.TP 18.TP
19.BR BOLLUX_URL 19.BR BOLLUX_URL
20valid values are URLs; default is ''. 20valid values are URLs; default is ''.
21.br 21.br
22If 22If
23.B BOLLUX_URL 23.B BOLLUX_URL
24is set, 24is set,
25.BR bollux (1) 25.BR bollux (1)
26loads that resource; 26loads that resource;
27otherwise it asks the user for where to go. 27otherwise it asks the user for where to go.
28Setting this variable works like setting a home page. 28Setting this variable works like setting a home page.
29.TP 29.TP
30.BR BOLLUX_DOWNDIR 30.BR BOLLUX_DOWNDIR
31valid values are directories; default is '.'. 31valid values are directories; default is '.'.
32.br 32.br
33The directory to attempt to save downloads in. 33The directory to attempt to save downloads in.
34.BR bollux (1) 34.BR bollux (1)
35will attempt to download anything whose mimetype isn't 35will attempt to download anything whose mimetype isn't
36.IR text/* , 36.IR text/* ,
37and it tries to place it in 37and it tries to place it in
38.BR BOLLUX_DOWNDIR . 38.BR BOLLUX_DOWNDIR .
39If it can't open the directory, save the file, 39If it can't open the directory, save the file,
40or if there's another file with the same name, 40or if there's another file with the same name,
41.BR bollux (1) 41.BR bollux (1)
42will report the name of the temporary file it saved. 42will report the name of the temporary file it saved.
43.TP 43.TP
44.BR BOLLUX_DATADIR 44.BR BOLLUX_DATADIR
45valid values are directories; default is '$XDG_DATA_DIR/bollux'. 45valid values are directories; default is '$XDG_DATA_DIR/bollux'.
46.br 46.br
47The directory 47The directory
48.BR bollux (1) 48.BR bollux (1)
49will put its data files, such as history, cert fingerprints, etc. 49will put its data files, such as history, cert fingerprints, etc.
50.TP 50.TP
51.BR BOLLUX_MAXREDIR 51.BR BOLLUX_MAXREDIR
52valid values are integers; default is '5'. 52valid values are integers; default is '5'.
53.br 53.br
54The maximum number of redirects before 54The maximum number of redirects before
55.BR bollux (1) 55.BR bollux (1)
56decides to quit. 56decides to quit.
57The default is 5 as per some RFC spec. 57The default is 5 as per some RFC spec.
58.TP 58.TP
59.BR BOLLUX_LOGLEVEL 59.BR BOLLUX_LOGLEVEL
60valid values are '', DEBUG or QUIET; default is ''. 60valid values are '', DEBUG or QUIET; default is ''.
61.br 61.br
62How verbose 62How verbose
63.BR bollux (1) 63.BR bollux (1)
64should be. 64should be.
65.I DEBUG 65.I DEBUG
66prints debug-level messages. 66prints debug-level messages.
67.I QUIET 67.I QUIET
68suppresses even error-level messages. 68suppresses even error-level messages.
69I'm going to be honest, 69I'm going to be honest,
70the difference between the levels is somewhat arbitrary. 70the difference between the levels is somewhat arbitrary.
71So. 71So.
72.SS Typesetting 72.SS Typesetting
73.BR bollux (1) 73.BR bollux (1)
74typesets text/gemini content using the 74typesets text/gemini content using the
75.I typeset_gemini 75.I typeset_gemini
76function. 76function.
77While it's probably possible to redefine the function in 77While it's probably possible to redefine the function in
78.BR bollux.conf (5), 78.BR bollux.conf (5),
79the default function is pretty nice (at least in my opinion). 79the default function is pretty nice (at least in my opinion).
80The following variables control how text/gemini content is rendered: 80The following variables control how text/gemini content is rendered:
81.TP 81.TP
82.BR T_MARGIN 82.BR T_MARGIN
83valid values are integers; default is 4. 83valid values are integers; default is 4.
84.br 84.br
85The left margin for text. 85The left margin for text.
86Should be at least 3, since line-markers will be displayed in the left margin. 86Should be at least 3, since line-markers will be displayed in the left margin.
87.TP 87.TP
88.BR T_WIDTH 88.BR T_WIDTH
89valid values are integers; default is 0. 89valid values are integers; default is 0.
90.br 90.br
91The total width of the window, including 91The total width of the window, including
92.BR T_MARGIN . 92.BR T_MARGIN .
93If set to 0, attempts to use the width of the terminal, 93If set to 0, attempts to use the width of the terminal,
94falling back to 80. 94falling back to 80.
95.SS Colors 95.SS Colors
96The different line-types in text/gemini documents are rendered with 96The different line-types in text/gemini documents are rendered with
97.I m-class 97.I m-class
98terminal escapes (e.g., '\\e[31m'). 98terminal escapes (e.g., '\\e[31m').
99The following variables should hold the values between 99The following variables should hold the values between
100.I \\e[ 100.I \\e[
101and 101and
102.IR m , 102.IR m ,
103meaning valid values are anything between those that are valid terminal 103meaning valid values are anything between those that are valid terminal
104color escapes. 104color escapes.
105.TP 105.TP
106.BR C_SIGIL 106.BR C_SIGIL
107default: 35 (fg: magenta) 107default: 35 (fg: magenta)
108.br 108.br
109The color of the line type as defined by text/gemini. 109The color of the line type as defined by text/gemini.
110.TP 110.TP
111.BR C_LINK_NUMBER 111.BR C_LINK_NUMBER
112default: 1 (bold) 112default: 1 (bold)
113.br 113.br
114The color of the link number added by typeset_gemini. 114The color of the link number added by typeset_gemini.
115.TP 115.TP
116.BR C_LINK_TITLE 116.BR C_LINK_TITLE
117default: 4 (underline) 117default: 4 (underline)
118.br 118.br
119The color of the link's title, or if titleless, the URL. 119The color of the link's title, or if titleless, the URL.
120.TP 120.TP
121.BR C_LINK_URL 121.BR C_LINK_URL
122default: 36 (fg: cyan) 122default: 36 (fg: cyan)
123.br 123.br
124The color of the link's URL. 124The color of the link's URL.
125If the link doesn't have a title, this isn't used. 125If the link doesn't have a title, this isn't used.
126.TP 126.TP
127.BI C_HEADER "x where x is 1, 2, or 3" 127.BI C_HEADER "x where x is 1, 2, or 3"
128The color of text/gemini headers. 128The color of text/gemini headers.
129The default for level 1 is 129The default for level 1 is
130.IR 1;4 , 130.IR 1;4 ,
131for level 2 is 131for level 2 is
132.IR 1 , 132.IR 1 ,
133for level 3 is 133for level 3 is
134.IR 3 . 134.IR 3 .
135.TP 135.TP
136.BR C_LIST 136.BR C_LIST
137default: 0 (no formatting) 137default: 0 (no formatting)
138.br 138.br
139The color of list items. 139The color of list items.
140.TP 140.TP
141.BR C_PRE 141.BR C_PRE
142default: 0 (no formatting) 142default: 0 (no formatting)
143.br 143.br
144The color of preformatted lines, as delimited by '```'. 144The color of preformatted lines, as delimited by '```'.
145.SS Variables that could be configured, but probably shouldn't be 145.SS Variables that could be configured, but probably shouldn't be
146These variables control deeper aspects of 146These variables control deeper aspects of
147.BR bollux (1)'s 147.BR bollux (1)'s
148workings. 148workings.
149It's possible they could be tweaked to make 149It's possible they could be tweaked to make
150.BR bollux (1) 150.BR bollux (1)
151work differently, like browsing gopher instead of gemini, 151work differently, like browsing gopher instead of gemini,
152but that capability has not been tested. 152but that capability has not been tested.
153.TP 153.TP
154.BR BOLLUX_PORT 154.BR BOLLUX_PORT
155valid values are port numbers (1-65535); default is '1965'. 155valid values are port numbers (1-65535); default is '1965'.
156.br 156.br
157The port 157The port
158.BR bollux (1) 158.BR bollux (1)
159tries to connect to on the server. 159tries to connect to on the server.
160.TP 160.TP
161.BR BOLLUX_PROTO 161.BR BOLLUX_PROTO
162valid values are protocol names (strings); default is 'gemini'. 162valid values are protocol names (strings); default is 'gemini'.
163.br 163.br
164The protocol to use. 164The protocol to use.
165.TP 165.TP
166.BR BOLLUX_TIMEOUT 166.BR BOLLUX_TIMEOUT
167valid values are as specified in 'help read'; default is '30'. 167valid values are as specified in 'help read'; default is '30'.
168.br 168.br
169The request timeout duration. 169The request timeout duration.
170Specified in seconds. 170Specified in seconds.
171.TP 171.TP
172.BR BOLLUX_LESSKEY 172.BR BOLLUX_LESSKEY
173valid values are files; default is '$BOLLUX_DATADIR/lesskey'. 173valid values are files; default is '$BOLLUX_DATADIR/lesskey'.
174.br 174.br
175Where to store the generated 175Where to store the generated
176.BR lesskey (1) 176.BR lesskey (1)
177file. 177file.
178.TP 178.TP
179.BR BOLLUX_PAGESRC 179.BR BOLLUX_PAGESRC
180valid values are files; default is '$BOLLUX_DATADIR/pagesrc'. 180valid values are files; default is '$BOLLUX_DATADIR/pagesrc'.
181.br 181.br
182Where to store the page source of the site being visited. 182Where to store the page source of the site being visited.
183It's not used right now by 183It's not used right now by
184.BR bollux (1), 184.BR bollux (1),
185but you could ... 185but you could ...
186.BR cat (1) 186.BR cat (1)
187it? 187it?
188.SH FILES 188.SH FILES
189.I $XDG_CONFIG_HOME/bollux/bollux.conf 189.I $XDG_CONFIG_HOME/bollux/bollux.conf
190.SH SEE ALSO 190.SH SEE ALSO
191.BR bollux (1) 191.BR bollux (1)
© 2022 C. Duckworth. generated by cgit. comments, issues, and patches welcome at < git at acdw dot net >.