1 files changed, 191 insertions, 191 deletions

@@ -1,191 +1,191 @@
-.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_DIR/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.

-So.

-.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.

-.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 1, 2, or 3"

-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 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)

+.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_DIR/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.
+So.
+.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.
+.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 1, 2, or 3"
+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 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)