about summary refs log tree commit diff stats
path: root/bollux.conf.5
blob: 9c66cedc73d9be57ca31ab2feba4c7be49709779 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
\" -*- nroff -*-
.TH bollux.conf 5 0.4.0
.SH NAME
.B bollux.conf
\- configuration file for
.BR bollux (1)
.SH DESCRIPTION
.BR bollux (1)
uses a number of environment variables that can be sourced from an external file,
usually placed in
.IR $XDG_CONFIG_HOME/bollux/bollux.conf .
\"The location can be changed at runtime by invoking
\".BR "bollux \-c CONFIG" .
.SH VARIABLES
.SS Variables you might actually want to set
Here are actually useful variables that are good things to set in your
.IR bollux.conf ,
in order of usefulness.
.TP
.BR BOLLUX_URL
valid values are URLs; default is ''.
.br
If
.B BOLLUX_URL
is set,
.BR bollux (1)
loads that resource;
otherwise it asks the user for where to go.
Setting this variable works like setting a home page.
.TP
.BR BOLLUX_DOWNDIR
valid values are directories; default is '.'.
.br
The directory to attempt to save downloads in.
.BR bollux (1)
will attempt to download anything whose mimetype isn't
.IR text/* ,
and it tries to place it in
.BR BOLLUX_DOWNDIR .
If it can't open the directory, save the file,
or if there's another file with the same name,
.BR bollux (1)
will report the name of the temporary file it saved.
.TP
.BR BOLLUX_DATADIR
valid values are directories; default is '$XDG_DATA_HOME/bollux'.
.br
The directory
.BR bollux (1)
will put its data files, such as history, cert fingerprints, etc.
.TP
.BR BOLLUX_MAXREDIR
valid values are integers; default is '5'.
.br
The maximum number of redirects before
.BR bollux (1)
decides to quit.
The default is 5 as per some RFC spec.
.TP
.BR BOLLUX_LOGLEVEL
valid values are '', DEBUG or QUIET; default is ''.
.br
How verbose
.BR bollux (1)
should be.
.I DEBUG
prints debug-level messages.
.I QUIET
suppresses even error-level messages.
I'm going to be honest,
the difference between the levels is somewhat arbitrary.
In addition, if the environment variable
.BR DEBUG
is set to
.IR true ,
.BR bollux (1)
will enable the
.BR bash (1)
functionality behind
.IR set\ \-x ,
debugging every call.
.SS Typesetting
.BR bollux (1)
typesets text/gemini content using the
.I typeset_gemini
function.
While it's probably possible to redefine the function in
.BR bollux.conf (5),
the default function is pretty nice (at least in my opinion).
The following variables control how text/gemini content is rendered:
.TP
.BR T_MARGIN
valid values are integers; default is 4.
.br
The left margin for text.
Should be at least 3, since line-markers will be displayed in the left margin.
.TP
.BR T_WIDTH
valid values are integers; default is 0.
.br
The total width of the window, including
.BR T_MARGIN .
If set to 0, attempts to use the width of the terminal,
falling back to 80.
.TP
.BR T_PRE_DISPLAY
comma-separated list of items; default is both,pre,alt.
.br
How to display preformatted text blocks.
.I pre
shows only the preformatted lines, ignoring the delimiting fences.
.I alt
shows only the first fence line, along with whatever alt text might be there.
.I both
shows both.
.SS Colors
The different line-types in text/gemini documents are rendered with
.I m-class
terminal escapes (e.g., '\\e[31m').
The following variables should hold the values between
.I \\e[
and
.IR m ,
meaning valid values are anything between those that are valid terminal
color escapes.
.TP
.BR C_SIGIL
default: 35 (fg: magenta)
.br
The color of the line type as defined by text/gemini.
.TP
.BR C_LINK_NUMBER
default: 1 (bold)
.br
The color of the link number added by typeset_gemini.
.TP
.BR C_LINK_TITLE
default: 4 (underline)
.br
The color of the link's title, or if titleless, the URL.
.TP
.BR C_LINK_URL
default: 36 (fg: cyan)
.br
The color of the link's URL.
If the link doesn't have a title, this isn't used.
.TP
.BI C_HEADER "x"
where x is
.IR 1 ,
.IR 2 ", or"
.IR 3
.br
The color of text/gemini headers.
The default for level 1 is
.IR 1;4 ,
for level 2 is
.IR 1 ,
for level 3 is
.IR 3 .
.TP
.BR C_LIST
default: 0 (no formatting)
.br
The color of list items.
.TP
.BR C_PRE
default: 0 (no formatting)
.br
The color of preformatted lines, as delimited by '```'.
.SS Keybindings
.BR bollux (1)
(ab)uses the exit-code scripting capabilities of
.BR less (1)
to do things.  The default keys are listed in the man page for
.BR bollux (1),
but you can also configure them by tweaking these variables:
.TP
.BR KEY_OPEN
default:
.IR o
.br
the key used to open a link from the current page.
.TP
.BR KEY_GOTO
default:
.IR g
.br
the key used to go to a new link (like a URL bar).
.TP
.BR KEY_GOTO_FROM
default:
.IR G
.br
similar to
.BR KEY_GOTO ,
but with the current URL pre-populated.
.TP
.BR KEY_BACK
default:
.IR [
.br
the key used to go back in the history list.
.TP
.BR KEY_FORWARD
default:
.IR ]
.br
the key used to go forward in the history list.
.TP
.BR KEY_REFRESH
default:
.IR r
.br
the key used to re-fetch the current page.
.TP
.BR KEY_CYCLE_PRE
default:
.IR p
.br
the key used to cycle the preformatted text display (see
.BR T_PRE_DISPLAY ,
above).
.TP
If you want more fine-tuned control over the keybindings,
you can edit
.BR BOLLUX_CUSTOM_LESSKEY ,
which is
.IR $XDG_CONFIG_HOME/bollux/bollux.lesskey
by default (of course, it can also be changed).
See
.BR lesskey (1)
for details on that file's format.
.SS Variables that could be configured, but probably shouldn't be
These variables control deeper aspects of
.BR bollux (1)'s
workings.
It's possible they could be tweaked to make
.BR bollux (1)
work differently, like browsing gopher instead of gemini,
but that capability has not been tested.
.TP
.BR BOLLUX_PORT
valid values are port numbers (1-65535); default is '1965'.
.br
The port
.BR bollux (1)
tries to connect to on the server.
.TP
.BR BOLLUX_PROTO
valid values are protocol names (strings); default is 'gemini'.
.br
The protocol to use.
.TP
.BR BOLLUX_TIMEOUT
valid values are as specified in 'help read'; default is '30'.
.br
The request timeout duration.
Specified in seconds.
.TP
.BR BOLLUX_LESSKEY
valid values are files; default is '$BOLLUX_DATADIR/lesskey'.
.br
Where to store the generated
.BR lesskey (1)
file.
.TP
.BR BOLLUX_PAGESRC
valid values are files; default is '$BOLLUX_DATADIR/pagesrc'.
.br
Where to store the page source of the site being visited.
It's not used right now by
.BR bollux (1),
but you could ...
.BR cat (1)
it?
.SH FILES
.I $XDG_CONFIG_HOME/bollux/bollux.conf
.SH SEE ALSO
.BR bollux (1)