1  .TH bollux.conf 5 0.4.0
  2  .SH NAME
  3  .B bollux.conf
  4  \- configuration file for
  5  .BR bollux (1)
  6  .SH DESCRIPTION
  7  .BR bollux (1)
  8  uses a number of environment variables that can be sourced from an external file,
  9  usually placed in
 10  .IR $XDG_CONFIG_HOME/bollux/bollux.conf .
 11  The location can be changed at runtime by invoking
 12  .BR "bollux \-c CONFIG" .
 13  .SH VARIABLES
 14  .SS Variables you might actually want to set
 15  Here are actually useful variables that are good things to set in your
 16  .IR bollux.conf ,
 17  in order of usefulness.
 18  .TP
 19  .BR BOLLUX_URL
 20  valid values are URLs; default is ''.
 21  .br
 22  If
 23  .B BOLLUX_URL
 24  is set,
 25  .BR bollux (1)
 26  loads that resource;
 27  otherwise it asks the user for where to go.
 28  Setting this variable works like setting a home page.
 29  .TP
 30  .BR BOLLUX_DOWNDIR
 31  valid values are directories; default is '.'.
 32  .br
 33  The directory to attempt to save downloads in.
 34  .BR bollux (1)
 35  will attempt to download anything whose mimetype isn't
 36  .IR text/* ,
 37  and it tries to place it in
 38  .BR BOLLUX_DOWNDIR .
 39  If it can't open the directory, save the file,
 40  or if there's another file with the same name,
 41  .BR bollux (1)
 42  will report the name of the temporary file it saved.
 43  .TP
 44  .BR BOLLUX_DATADIR
 45  valid values are directories; default is '$XDG_DATA_DIR/bollux'.
 46  .br
 47  The directory
 48  .BR bollux (1)
 49  will put its data files, such as history, cert fingerprints, etc.
 50  .TP
 51  .BR BOLLUX_MAXREDIR
 52  valid values are integers; default is '5'.
 53  .br
 54  The maximum number of redirects before
 55  .BR bollux (1)
 56  decides to quit.
 57  The default is 5 as per some RFC spec.
 58  .TP
 59  .BR BOLLUX_LOGLEVEL
 60  valid values are '', DEBUG or QUIET; default is ''.
 61  .br
 62  How verbose
 63  .BR bollux (1)
 64  should be.
 65  .I DEBUG
 66  prints debug-level messages.
 67  .I QUIET
 68  suppresses even error-level messages.
 69  I'm going to be honest,
 70  the difference between the levels is somewhat arbitrary.
 71  So.
 72  .SS Typesetting
 73  .BR bollux (1)
 74  typesets text/gemini content using the
 75  .I typeset_gemini
 76  function.
 77  While it's probably possible to redefine the function in
 78  .BR bollux.conf (5),
 79  the default function is pretty nice (at least in my opinion).
 80  The following variables control how text/gemini content is rendered:
 81  .TP
 82  .BR T_MARGIN
 83  valid values are integers; default is 4.
 84  .br
 85  The left margin for text.
 86  Should be at least 3, since line-markers will be displayed in the left margin.
 87  .TP
 88  .BR T_WIDTH
 89  valid values are integers; default is 0.
 90  .br
 91  The total width of the window, including
 92  .BR T_MARGIN .
 93  If set to 0, attempts to use the width of the terminal,
 94  falling back to 80.
 95  .SS Colors
 96  The different line-types in text/gemini documents are rendered with
 97  .I m-class
 98  terminal escapes (e.g., '\\e[31m').
 99  The following variables should hold the values between
100  .I \\e[
101  and
102  .IR m ,
103  meaning valid values are anything between those that are valid terminal
104  color escapes.
105  .TP
106  .BR C_SIGIL
107  default: 35 (fg: magenta)
108  .br
109  The color of the line type as defined by text/gemini.
110  .TP
111  .BR C_LINK_NUMBER
112  default: 1 (bold)
113  .br
114  The color of the link number added by typeset_gemini.
115  .TP
116  .BR C_LINK_TITLE
117  default: 4 (underline)
118  .br
119  The color of the link's title, or if titleless, the URL.
120  .TP
121  .BR C_LINK_URL
122  default: 36 (fg: cyan)
123  .br
124  The color of the link's URL.
125  If the link doesn't have a title, this isn't used.
126  .TP
127  .BI C_HEADER "x where x is 1, 2, or 3"
128  The color of text/gemini headers.
129  The default for level 1 is
130  .IR 1;4 ,
131  for level 2 is
132  .IR 1 ,
133  for level 3 is
134  .IR 3 .
135  .TP
136  .BR C_LIST
137  default: 0 (no formatting)
138  .br
139  The color of list items.
140  .TP
141  .BR C_PRE
142  default: 0 (no formatting)
143  .br
144  The color of preformatted lines, as delimited by '```'.
145  .SS Variables that could be configured, but probably shouldn't be
146  These variables control deeper aspects of
147  .BR bollux (1)'s
148  workings.
149  It's possible they could be tweaked to make
150  .BR bollux (1)
151  work differently, like browsing gopher instead of gemini,
152  but that capability has not been tested.
153  .TP
154  .BR BOLLUX_PORT
155  valid values are port numbers (1-65535); default is '1965'.
156  .br
157  The port
158  .BR bollux (1)
159  tries to connect to on the server.
160  .TP
161  .BR BOLLUX_PROTO
162  valid values are protocol names (strings); default is 'gemini'.
163  .br
164  The protocol to use.
165  .TP
166  .BR BOLLUX_TIMEOUT
167  valid values are as specified in 'help read'; default is '30'.
168  .br
169  The request timeout duration.
170  Specified in seconds.
171  .TP
172  .BR BOLLUX_LESSKEY
173  valid values are files; default is '$BOLLUX_DATADIR/lesskey'.
174  .br
175  Where to store the generated
176  .BR lesskey (1)
177  file.
178  .TP
179  .BR BOLLUX_PAGESRC
180  valid values are files; default is '$BOLLUX_DATADIR/pagesrc'.
181  .br
182  Where to store the page source of the site being visited.
183  It's not used right now by
184  .BR bollux (1),
185  but you could ...
186  .BR cat (1)
187  it?
188  .SH FILES
189  .I $XDG_CONFIG_HOME/bollux/bollux.conf
190  .SH SEE ALSO
191  .BR bollux (1)