bollux.conf.5

   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)