~acdw/bollux

d3f0b7fa4a026b85aa65afe9be7fdbeb20d19786 — Case Duckworth a month ago 0c78b32 + c62c434
Merge branch 'main' of tildegit.org:acdw/bollux
6 files changed, 407 insertions(+), 330 deletions(-)

A .drone.yml
M Makefile
M README.md
M bollux -rwxr-xr-x => -rw-r--r--
M bollux.1
M bollux.conf.5
A .drone.yml => .drone.yml +8 -0
@@ 0,0 1,8 @@
---
kind: pipeline
name: shellcheck
steps:
    - name: shellcheck
      image: koalaman/shellcheck-alpine:stable
      commands:
          - shellcheck bollux

M Makefile => Makefile +1 -1
@@ 2,7 2,7 @@
# Author: Case Duckworth <acdw@acdw.net>
# License: MIT

PREFIX ?= /usr
PREFIX ?= /usr/local

INSTALL = install -m 755


M README.md => README.md +7 -6
@@ 4,6 4,8 @@

# bollux - a bash Gemini client

[![Shellcheck Status](https://drone.tildegit.org/api/badges/acdw/bollux/status.svg)](https://drone.tildegit.org/acdw/bollux)

inspired by

* [birch](https://github.com/dylanaraps/birch)


@@ 37,7 39,7 @@ inspired by
* bash >= 4.0
* iconv
* openssl
* less
* less (with lesskey)
* dd

# INSTALL


@@ 57,7 59,7 @@ $ cd bollux
## Alternative

```
$ curl -fLo bollux https://git.sr.ht/~acdw/bollux/blob/0.3.0/bollux
$ curl -fLo bollux https://tildegit.org/bollux/raw/branch/main/bollux
$ chmod +x bollux
$ ./bollux
```


@@ 70,7 72,6 @@ MIT

# CONTRIBUTING

Feel free to write to my
[public inbox](https://lists.sr.ht/~acdw/public-inbox)
with changes you'd like to make, or submit an issue to the
[ticket tracker.](https://todo.sr.ht/~acdw/bollux)
Create an [issue](https://tildegit.org/acdw/bollux/issues/new) or
[pull request](https://tildegit.org/acdw/bollux/compare/main...main) and I'll
get back to you posthaste!

M bollux => bollux +93 -39
@@ 25,6 25,7 @@ END
}

run() { # run COMMAND...
	trap bollux_quit SIGINT
	log debug "$*"
	"$@"
}


@@ 49,6 50,20 @@ trim_string() { # trim_string STRING
	printf '%s\n' "$_"
}

# cycle a variable, e.g. from 'one,two,three' => 'two,three,one'
cycle_list() { # cycle_list LIST DELIM
	local list="${!1}" delim="$2"
	local first="${list%%${delim}*}"
	local rest="${list#*${delim}}"
	printf -v "$1" '%s%s%s' "${rest}" "${delim}" "${first}"
}

# determine the first element of a list, e.g. 'one,two,three' => 'one'
first() { # first LIST DELIM
	local list="${!1}" delim="$2"
	printf '%s\n' "${list%%${delim}*}"
}

log() { # log LEVEL MESSAGE
	[[ "$BOLLUX_LOGLEVEL" == QUIET ]] && return
	local fmt


@@ 105,10 120,11 @@ bollux_args() {

# process config file and set variables
bollux_config() {
	: "${BOLLUX_CONFIG:=${XDG_CONFIG_DIR:-$HOME/.config}/bollux/bollux.conf}"
	: "${BOLLUX_CONFIG:=${XDG_CONFIG_HOME:-$HOME/.config}/bollux/bollux.conf}"

	if [ -f "$BOLLUX_CONFIG" ]; then
		# shellcheck disable=1090
		log debug "Loading config file '$BOLLUX_CONFIG'"
		. "$BOLLUX_CONFIG"
	else
		log debug "Can't load config file '$BOLLUX_CONFIG'."


@@ 125,11 141,12 @@ bollux_config() {
	: "${BOLLUX_DATADIR:=${XDG_DATA_DIR:-$HOME/.local/share}/bollux}"
	: "${BOLLUX_DOWNDIR:=.}"                       # where to save downloads
	: "${BOLLUX_LESSKEY:=$BOLLUX_DATADIR/lesskey}" # where to store binds
	: "${BOLLUX_PAGESRC:=$BOLLUX_DATADIR/pagesrc}" # where to save the source
	BOLLUX_HISTFILE="$BOLLUX_DATADIR/history"      # where to save the history
	: "${BOLLUX_PAGESRC:=$BOLLUX_DATADIR/pagesrc}" # where to save source
	BOLLUX_HISTFILE="$BOLLUX_DATADIR/history"      # where to save history
	## typesetting
	: "${T_MARGIN:=4}"      # left and right margin
	: "${T_WIDTH:=0}"       # width of the viewport -- 0 = get term width
	: "${T_MARGIN:=4}"                 # left and right margin
	: "${T_WIDTH:=0}"                  # width of the viewport -- 0 = get term width
	: "${T_PRE_DISPLAY:=pre,alt,both}" # how to view PRE blocks
	# colors -- these will be wrapped in \e[ __ m
	C_RESET='\e[0m'         # reset
	: "${C_SIGIL:=35}"      # sigil (=>, #, ##, ###, *, ```)


@@ 151,6 168,8 @@ bollux_quit() {
	printf '\e[1m%s\e[0m:\t\e[3m%s\e[0m\n' "$PRGN" "$BOLLUX_BYEMSG"
	exit
}
# trap C-c
trap bollux_quit SIGINT

# set the terminal title
set_title() { # set_title STRING


@@ 196,7 215,9 @@ blastoff() { # blastoff [-u] URL
		if declare -Fp "${url[1]}_response" >/dev/null 2>&1; then
			run "${url[1]}_response" "$url"
		else
			log d "No response handler for '${url[1]}', passing thru"
			log d \
				"No response handler for '${url[1]}';" \
				" passing thru"
			passthru
		fi
	}


@@ 206,7 227,7 @@ blastoff() { # blastoff [-u] URL
## https://tools.ietf.org/html/rfc3986
uwellform() {
	local u="$1"
	

	if [[ "$u" != *://* ]]; then
		u="$BOLLUX_PROTO://$u"
	fi


@@ 220,11 241,12 @@ usplit() { # usplit NAME:ARRAY URL:STRING
	local re='^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?'
	[[ $2 =~ $re ]] || return $?

	local scheme="${BASH_REMATCH[2]}"
	local authority="${BASH_REMATCH[4]}"
	local path="${BASH_REMATCH[5]}"
	local query="${BASH_REMATCH[7]}"
	local fragment="${BASH_REMATCH[9]}"
	# shellcheck disable=2034
	local scheme="${BASH_REMATCH[2]}" \
		authority="${BASH_REMATCH[4]}" \
		path="${BASH_REMATCH[5]}" \
		query="${BASH_REMATCH[7]}" \
		fragment="${BASH_REMATCH[9]}"

	# 0=url 1=scheme 2=authority 3=path 4=query 5=fragment
	local i=1 c


@@ 232,10 254,12 @@ usplit() { # usplit NAME:ARRAY URL:STRING
		if [[ "${!c}" || "$c" == path ]]; then
			printf -v "$1[$i]" '%s' "${!c}"
		else
			# shellcheck disable=2059
			printf -v "$1[$i]" "$UC_BLANK"
		fi
		((i+=1))
		((i += 1))
	done
	# shellcheck disable=2059
	printf -v "$1[0]" "$(ujoin "$1")" # inefficient I'm sure
}



@@ 251,7 275,7 @@ ujoin() { # ujoin NAME:ARRAY
	fi

	printf -v U[0] "${U[0]}%s" "${U[3]}"
	

	if ucdef U[4]; then
		printf -v U[0] "${U[0]}?%s" "${U[4]}"
	fi


@@ 265,19 289,19 @@ ujoin() { # ujoin NAME:ARRAY

ucdef() { [[ "${!1}" != "$UC_BLANK" ]]; } # ucdef NAME
ucblank() { [[ -z "${!1}" ]]; }           # ucblank NAME
ucset() { # ucset NAME VALUE
ucset() {                                 # ucset NAME VALUE
	run eval "${1}='$2'"
	run ujoin "${1/\[*\]}"
	run ujoin "${1/\[*\]/}"
}

utransform() { # utransform TARGET:ARRAY BASE:STRING REFERENCE:STRING
	local -a B R # base, reference
utransform() {   # utransform TARGET:ARRAY BASE:STRING REFERENCE:STRING
	local -a B R    # base, reference
	local -n T="$1" # target
	usplit B "$2"
	usplit R "$3"

	# initialize T
	for ((i=1;i<=5;i++)); do
	for ((i = 1; i <= 5; i++)); do
		T[$i]="$UC_BLANK"
	done



@@ 393,7 417,7 @@ uencode() { # uencode URL:STRING
}

# https://github.com/dylanaraps/pure-bash-bible/
udecode() { # udecode URL:STRING 
udecode() { # udecode URL:STRING
	: "${1//+/ }"
	printf '%b\n' "${_//%/\\x}"
}


@@ 416,10 440,10 @@ gemini_request() { # gemini_request URL
	fi

	local ssl_cmd=(
		openssl s_client 
			-crlf -quiet -connect "${url[2]}:$port"
			-servername "${url[2]}" # SNI
			-no_ssl3 -no_tls1 -no_tls1_1 # disable old TLS/SSL versions
		openssl s_client
		-crlf -quiet -connect "${url[2]}:$port"
		-servername "${url[2]}"      # SNI
		-no_ssl3 -no_tls1 -no_tls1_1 # disable old TLS/SSL versions
	)

	run "${ssl_cmd[@]}" <<<"$url"


@@ 663,14 687,19 @@ display() { # display METADATA [TITLE]
	case "$mime" in
	text/*)
		set_title "$title${title:+ - }bollux"
		less_cmd=(less -R) # render ANSI color escapes
		# render ANSI color escapes and don't wrap pre-formatted blocks
		less_cmd=(less -RS)
		mklesskey "$BOLLUX_LESSKEY" && less_cmd+=(-k "$BOLLUX_LESSKEY")
		local helpline="o:open, g/G:goto, [:back, ]:forward, r:refresh"
		less_cmd+=(
			-Pm"$(less_prompt_escape "$BOLLUX_URL") - bollux$" # 'status'line
			-P="$(less_prompt_escape "$helpline")$" # helpline
			-m # start with statusline
			+k # float content to the top
			# 'status'line
			-Pm"$(less_prompt_escape "$BOLLUX_URL") - bollux$"
			# helpline
			-P="$(less_prompt_escape "$helpline")$"
			# start with statusline
			-m
			# float content to the top
			+k
		)

		local typeset


@@ 707,7 736,7 @@ less_prompt_escape() { # less_prompt_escape STRING

# generate a lesskey(1) file for custom keybinds
mklesskey() { # mklesskey FILENAME
	lesskey -o "$1" - <<-END
	lesskey -o "$1" - <<-\END
		#command
		o quit 0 # 48 open a link
		g quit 1 # 49 goto a url


@@ 715,8 744,9 @@ mklesskey() { # mklesskey FILENAME
		] quit 3 # 51 forward
		r quit 4 # 52 re-request / download
		G quit 5 # 53 goto a url (pre-filled)
		` quit 6 # 54 cycle T_PRE_DISPLAY and refresh
		# other keybinds
		\\40 forw-screen-force
		\40 forw-screen-force
		h left-scroll
		l right-scroll
		? status   # 'status' will show a little help thing.


@@ 754,15 784,26 @@ typeset_gemini() {

	log d "T_WIDTH=$T_WIDTH"
	log d "WIDTH=$WIDTH"
	log d "$T_PRE_DISPLAY"

	while IFS= read -r; do
		case "$REPLY" in
		'```'*)
			PRE_LINE_FORCE=false
			if $pre; then
				pre=false
			else
				pre=true
			fi
			case "${T_PRE_DISPLAY%%,*}" in
			pre)
				:
				;;
			alt | both)
				$pre && PRE_LINE_FORCE=true \
					gemini_pre "${REPLY#\`\`\`}"
				;;
			esac
			continue
			;;
		'=>'*)


@@ 799,8 840,10 @@ gemini_link() {
		fold_line -n -B "\e[${C_LINK_TITLE}m" -A "${C_RESET}" \
			-l "$((${#ln} + 3))" -m "${T_MARGIN}" \
			"$WIDTH" "$(trim_string "$t")"
		fold_line -B " \e[${C_LINK_URL}m" -A "${C_RESET}" \
			-l "$((${#ln} + 3 + ${#t}))" -m "$((T_MARGIN + ${#ln} + 2))" \
		fold_line -B " \e[${C_LINK_URL}m" \
			-A "${C_RESET}" \
			-l "$((${#ln} + 3 + ${#t}))" \
			-m "$((T_MARGIN + ${#ln} + 2))" \
			"$WIDTH" "$a"
	else
		gemini_pre "$1"


@@ 866,13 909,17 @@ gemini_text() {
}

gemini_pre() {
	printf "\e[${C_SIGIL}m%${S_MARGIN}s " '```'
	printf "\e[${C_PRE}m%s${C_RESET}\n" "$1"
	# Print preformatted text, dependent on $T_PRE_DISPLAY and
	# $PRE_LINE_FORCE
	if [[ alt != "${T_PRE_DISPLAY%%,*}" ]] || $PRE_LINE_FORCE; then
		printf "\e[${C_SIGIL}m%${S_MARGIN}s " '```'
		printf "\e[${C_PRE}m%s${C_RESET}\n" "$1"
	fi
}

# wrap lines on words to WIDTH
fold_line() {
	# fold_line [-n] [-m MARGIN] [-f MARGIN] [-l LENGTH] [-B BEFORE] [-A AFTER] WIDTH TEXT
fold_line() { # fold_line [OPTIONS...] WIDTH TEXT
	# see getopts, below, for options
	local newline=true
	local -i margin_all=0 margin_first=0 width ll=0 wl=0 wn=0
	local before="" after=""


@@ 961,7 1008,11 @@ handle_keypress() { # handle_keypress CODE
		run prompt -u GO
		run blastoff -u "$REPLY"
		;;
	*) # 54-57 -- still available for binding
	54) # ` - change alt-text visibility and refresh
		run cycle_list T_PRE_DISPLAY ,
		run blastoff "$BOLLUX_URL"
		;;
	55) # 55-57 -- still available for binding
		die "$?" "less(1) error"
		;;
	esac


@@ 988,8 1039,10 @@ select_url() { # select_url FILE
# extract the links from a text/gemini file
extract_links() {
	local url alt
	local re="^=>[[:space:]]*([^[:space:]]+)([[:space:]]+(.*))?$"
	while read -r; do
		if [[ "$REPLY" =~ ^=\>[[:space:]]*([^[:space:]]+)([[:space:]]+(.*))?$ ]]; then
		log d $re
		if [[ $REPLY =~ $re ]]; then
			url="${BASH_REMATCH[1]}"
			alt="${BASH_REMATCH[3]}"



@@ 1069,5 1122,6 @@ history_forward() {
}

if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
	${DEBUG:-false} && set -x
	run bollux "$@"
fi

M bollux.1 => bollux.1 +96 -93
@@ 1,93 1,96 @@
.TH bollux 1 0.4.0
.SH NAME
bollux \- gemini protocol browser written in
.BR bash (1)
.SH SYNOPSIS
.B bollux
.RI [ \-h ]
.TP
.B bollux
.RI [ \-q ]
.RI [ \-v ]
.\".RI [ \-c
.\".BR CONFIG ]
.RB [ URL ]
.SH DESCRIPTION
.BR bollux (1)
is a browser for the new Gemini protocol, which aims to be
"heavier than gopher, but lighter than the web."
It can follow links, collect user input, download files, and display text/* mimetype pages in geminispace.
.SH OPTIONS
.TP
.B \-h
Display an inline help screen and exit
.TP
.B \-q
Be quiet: don't show any messages, even fatal ones
.TP
.B \-v
Be verbose: show all messages, even debug ones
.\".TP
.\".B \-c CONFIG
.\"Use CONFIG file to configure
.\".BR bollux (1)
.\"instead of the default: $XDG_CONFIG_HOME/bollux/bollux.conf.
.TP
.B URL
The gemini URL to navigate to
.SH USAGE
If
.BR bollux (1)
is invoked with a URL, it will download or display that URL.
Otherwise, the user will be prompted for a URL to download or display.
If the URL points to a text/* document, it is paged with
.BR less (1)
with custom keybinds:
.TP
.B o
open a link on the current page
.TP
.B g
goto a new URL
.TP
.B G
goto a new URL - with current URL pre-filled
.TP
.B r
refresh the current page
.TP
.B [
goto the previous page in history
.TP
.B ]
goto the next page in history
.TP
.B q
quit bollux
.TP
.B \=
show a short help message
.PP
If a new URL is selected,
.BR bollux (1)
will repeat the download-and-display loop with the new URL.
.PP
If the mimetype is other than text/*,
.BR bollux (1)
will attempt to download the file to
.B $BOLLUX_DOWNDIR
(which defaults to '.').
.PP
.BR bollux (1)
also supports the gopher protocol,
which is browsed the same way as the gemini protocol
(except the URL starts with 'gopher://').
Gopher support is as of now rudimentary.
.SH ISSUES
Certificate handling needs to be much improved: TOFU needs to be implemented
and bollux should be able to generate client certificates.
.SH SEE ALSO
.BR bollux.conf (5)
.SH BUGS
The development repo is located at https://sr.ht/~acdw/bollux.
Please direct all bug reports, patches, or general complaints there.
.TH bollux 1 0.4.0
.SH NAME
bollux \- gemini protocol browser written in
.BR bash (1)
.SH SYNOPSIS
.B bollux
.RI [ \-h ]
.TP
.B bollux
.RI [ \-q ]
.RI [ \-v ]
.\".RI [ \-c
.\".BR CONFIG ]
.RB [ URL ]
.SH DESCRIPTION
.BR bollux (1)
is a browser for the new Gemini protocol, which aims to be
"heavier than gopher, but lighter than the web."
It can follow links, collect user input, download files, and display text/* mimetype pages in geminispace.
.SH OPTIONS
.TP
.B \-h
Display an inline help screen and exit
.TP
.B \-q
Be quiet: don't show any messages, even fatal ones
.TP
.B \-v
Be verbose: show all messages, even debug ones
.\".TP
.\".B \-c CONFIG
.\"Use CONFIG file to configure
.\".BR bollux (1)
.\"instead of the default: $XDG_CONFIG_HOME/bollux/bollux.conf.
.TP
.B URL
The gemini URL to navigate to
.SH USAGE
If
.BR bollux (1)
is invoked with a URL, it will download or display that URL.
Otherwise, the user will be prompted for a URL to download or display.
If the URL points to a text/* document, it is paged with
.BR less (1)
with custom keybinds:
.TP
.B o
open a link on the current page
.TP
.B g
goto a new URL
.TP
.B G
goto a new URL - with current URL pre-filled
.TP
.B r
refresh the current page
.TP
.B `
cycle preformatted text visibility and refresh the current page
.TP
.B [
goto the previous page in history
.TP
.B ]
goto the next page in history
.TP
.B q
quit bollux
.TP
.B \=
show a short help message
.PP
If a new URL is selected,
.BR bollux (1)
will repeat the download-and-display loop with the new URL.
.PP
If the mimetype is other than text/*,
.BR bollux (1)
will attempt to download the file to
.B $BOLLUX_DOWNDIR
(which defaults to '.').
.PP
.BR bollux (1)
also supports the gopher protocol,
which is browsed the same way as the gemini protocol
(except the URL starts with 'gopher://').
Gopher support is as of now rudimentary.
.SH ISSUES
Certificate handling needs to be much improved: TOFU needs to be implemented
and bollux should be able to generate client certificates.
.SH SEE ALSO
.BR bollux.conf (5)
.SH BUGS
The development repo is located at https://sr.ht/~acdw/bollux.
Please direct all bug reports, patches, or general complaints there.

M bollux.conf.5 => bollux.conf.5 +202 -191
@@ 1,191 1,202 @@
.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.
.TP
.BR T_PRE_DISPLAY
comma-separated list of items; default is pre,alt,both.
.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 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)