288 lines
6.3 KiB
Groff
288 lines
6.3 KiB
Groff
\" -*- nroff -*-
|
|
.TH bollux.conf 5 0.4.1
|
|
.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_GEMINI_PORT
|
|
valid values are port numbers (1-65535); default is '1965'.
|
|
.br
|
|
The port
|
|
.BR bollux (1)
|
|
tries to connect to on gemini servers.
|
|
.TP
|
|
.BR BOLLUX_GOPHER_PORT
|
|
valid values are port numbers (1-65535); default is '70'.
|
|
.br
|
|
The port
|
|
.BR bollux (1)
|
|
tries to connect to on gopher servers.
|
|
.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)
|