v0.35.2 lwconf, doc and deploy update

deploy/package/completion/_lw

@@ -94,31 +94,31 @@ preset:*)
 	(( CURRENT -= 2 ))
 	case ${words[1]} in
 	pipe) _arguments -S \
-		'--format=[raw|txt|json: entry format]:value:_default' \
+		'--format=[raw|txt|json: raw writes each message as it came, txt a line with time and level, json one object an entry]:value:_default' \
 		'(-h --help)'{-h,--help}'[print the flags]' ;;
 	tail) _arguments -S \
-		'--format=[raw|txt|json: entry format]:value:_default' \
+		'--format=[raw|txt|json: raw writes each message as it came, txt a line with time and level, json one object an entry]:value:_default' \
 		'--from=[start|end: where reading a file starts]:value:_default' \
-		'--path=[file, directory (its files) or glob to follow]:value:_default' \
+		'--path=[a file, a directory (its files) or a glob such as /var/log/*.log, to follow]:value:_default' \
 		'(-h --help)'{-h,--help}'[print the flags]' ;;
 	serve) _arguments -S \
 		'--allow=[addresses or CIDRs that may connect, of listen'\''s family (either behind proxy=); default: all; '\'','\'' between them]:value:_default' \
 		'--cert=[certificate file, for tls=files]:value:_default' \
 		'--deny=[addresses or CIDRs refused, allow or not; '\'','\'' between them]:value:_default' \
-		'--format=[raw|txt|json: entry format]:value:_default' \
+		'--format=[raw|txt|json: raw writes each message as it came, txt a line with time and level, json one object an entry]:value:_default' \
 		'--from=[start|end: where reading a file starts]:value:_default' \
 		'--hosts=[names and addresses, beyond this host'\''s, of a self or issuer certificate; '\'','\'' between them]:value:_default' \
 		'--issuer_cert=[CA certificate file (lw tls ca), for tls=issuer]:value:_default' \
 		'--issuer_key=[CA key file, for tls=issuer]:value:_default' \
 		'--key=[key file, for tls=files]:value:_default' \
-		'--listen=[HOST:PORT; [IPV6\]:PORT]:value:_default' \
+		'--listen=[HOST:PORT to listen on: 127.0.0.1:8080 this machine only, 0.0.0.0:8080 every IPv4 interface, [::\]:8080 every IPv6 interface]:value:_default' \
 		'--password_file=[file holding user'\''s password; /dev/fd/N or a pipe is read once; default: /dev/tty, which asks]:value:_default' \
-		'--path=[file, directory (its files) or glob to follow; default: standard input]:value:_default' \
+		'--path=[a file, a directory (its files) or a glob such as /var/log/*.log, to follow; default: standard input]:value:_default' \
 		'--proxy=[addresses or CIDRs of the TLS-terminating proxies browsers come through; '\'','\'' between them]:value:_default' \
 		'--tls=[off|self|issuer|files: plain text, a certificate made at startup (self-signed, or from issuer_*), or files]:value:_default' \
-		'(-u --user)'{-u=,--user=}'[SCRAM user: an edge'\''s login, or a listener'\''s only user in place of users]:value:_default' \
+		'(-u --user)'{-u=,--user=}'[the one SCRAM user readers log in as, in place of users]:value:_default' \
 		'--users=[credentials file (lw auth add-user): readers log in with SCRAM]:value:_default' \
-		'--viewer=[true|false: the login page and viewer, behind proxy; without user or users the viewer is always on]:value:_default' \
+		'--viewer=[true|false: a login page, then the viewer, for browsers behind proxy; without user or users the viewer is on anyway]:value:_default' \
 		'(-h --help)'{-h,--help}'[print the flags]' ;;
 	edge) _arguments -S \
 		'--ca=[CA file that verifies the aggregator; default: system roots]:value:_default' \
@@ -127,29 +127,29 @@ preset:*)
 		'--key=[client key file]:value:_default' \
 		'--node=[origin label; default: this host'\''s name]:value:_default' \
 		'--password_file=[file holding user'\''s password; /dev/fd/N or a pipe is read once; default: /dev/tty, which asks]:value:_default' \
-		'--path=[file, directory (its files) or glob to follow; default: standard input]:value:_default' \
+		'--path=[a file, a directory (its files) or a glob such as /var/log/*.log, to follow; default: standard input]:value:_default' \
 		'--pin=[sha256//BASE64 of the aggregator'\''s key, which it logs with tls=self]:value:_default' \
 		'--server_name=[name the aggregator'\''s certificate carries; default: to'\''s host]:value:_default' \
-		'--to=[the aggregator'\''s HOST:PORT; [IPV6\]:PORT]:value:_default' \
-		'--transport=[tcp|http: tcp_chain or http_chain]:value:_default' \
-		'(-u --user)'{-u=,--user=}'[SCRAM user: an edge'\''s login, or a listener'\''s only user in place of users]:value:_default' \
+		'--to=[the aggregator'\''s HOST:PORT, an IPv6 address in brackets: logs.example.net:9000, [2001:db8::1\]:9000]:value:_default' \
+		'--transport=[tcp|http: tcp sends over one lasting connection (tcp_chain), http posts batches (http_chain)]:value:_default' \
+		'(-u --user)'{-u=,--user=}'[SCRAM user this edge logs in to the aggregator as]:value:_default' \
 		'(-h --help)'{-h,--help}'[print the flags]' ;;
 	aggregator) _arguments -S \
 		'--allow=[addresses or CIDRs that may connect, of listen'\''s family (either behind proxy=); default: all; '\'','\'' between them]:value:_default' \
 		'--cert=[certificate file, for tls=files]:value:_default' \
 		'--client_ca=[CA file that verifies edge certificates (mTLS)]:value:_default' \
 		'--deny=[addresses or CIDRs refused, allow or not; '\'','\'' between them]:value:_default' \
-		'--format=[raw|txt|json: entry format]:value:_default' \
+		'--format=[raw|txt|json: raw writes each message as it came, txt a line with time and level, json one object an entry]:value:_default' \
 		'--hosts=[names and addresses, beyond this host'\''s, of a self or issuer certificate; '\'','\'' between them]:value:_default' \
 		'--issuer_cert=[CA certificate file (lw tls ca), for tls=issuer]:value:_default' \
 		'--issuer_key=[CA key file, for tls=issuer]:value:_default' \
 		'--key=[key file, for tls=files]:value:_default' \
-		'--listen=[HOST:PORT; [IPV6\]:PORT; [::\] for IPv6 only]:value:_default' \
+		'--listen=[HOST:PORT to listen on: 0.0.0.0:9000 every IPv4 interface, [::\]:9000 every IPv6 interface, 127.0.0.1:9000 this machine only]:value:_default' \
 		'--out=[directory for the received entries; default: standard output]:value:_default' \
 		'--password_file=[file holding user'\''s password; /dev/fd/N or a pipe is read once; default: /dev/tty, which asks]:value:_default' \
 		'--tls=[self|issuer|files: a certificate made at startup (self-signed, or from issuer_*), or files]:value:_default' \
-		'--transport=[tcp|http: tcp_chain or http_chain]:value:_default' \
-		'(-u --user)'{-u=,--user=}'[SCRAM user: an edge'\''s login, or a listener'\''s only user in place of users]:value:_default' \
+		'--transport=[tcp|http: tcp sends over one lasting connection (tcp_chain), http posts batches (http_chain)]:value:_default' \
+		'(-u --user)'{-u=,--user=}'[the one SCRAM user edges log in as, in place of users]:value:_default' \
 		'--users=[credentials file (lw auth add-user): edges log in with SCRAM]:value:_default' \
 		'(-h --help)'{-h,--help}'[print the flags]' ;;
 	esac

deploy/package/completion/lw.fish

@@ -96,29 +96,29 @@ complete -c lw -n '__lw_in preset; and test (count (commandline -opc)) -eq 2' -a
 complete -c lw -n '__lw_in preset; and test (count (commandline -opc)) -eq 2' -a serve -d 'Serve files or standard input live: a browser viewer at /, SSE at /stream'
 complete -c lw -n '__lw_in preset; and test (count (commandline -opc)) -eq 2' -a edge -d 'Forward files or standard input to an aggregator over TLS, authenticated'
 complete -c lw -n '__lw_in preset; and test (count (commandline -opc)) -eq 2' -a aggregator -d 'Receive from edges over TLS, authenticated, to files or standard output'
-complete -c lw -n '__lw_in preset pipe' -l format -r -F -d 'raw|txt|json: entry format'
+complete -c lw -n '__lw_in preset pipe' -l format -r -F -d 'raw|txt|json: raw writes each message as it came, txt a line with time and level, json one object an entry'
 complete -c lw -n '__lw_in preset pipe' -l help -o h -d 'print the flags'
-complete -c lw -n '__lw_in preset tail' -l format -r -F -d 'raw|txt|json: entry format'
+complete -c lw -n '__lw_in preset tail' -l format -r -F -d 'raw|txt|json: raw writes each message as it came, txt a line with time and level, json one object an entry'
 complete -c lw -n '__lw_in preset tail' -l from -r -F -d 'start|end: where reading a file starts'
-complete -c lw -n '__lw_in preset tail' -l path -r -F -d 'file, directory (its files) or glob to follow'
+complete -c lw -n '__lw_in preset tail' -l path -r -F -d 'a file, a directory (its files) or a glob such as /var/log/*.log, to follow'
 complete -c lw -n '__lw_in preset tail' -l help -o h -d 'print the flags'
 complete -c lw -n '__lw_in preset serve' -l allow -r -F -d 'addresses or CIDRs that may connect, of listen\'s family (either behind proxy=); default: all; \',\' between them'
 complete -c lw -n '__lw_in preset serve' -l cert -r -F -d 'certificate file, for tls=files'
 complete -c lw -n '__lw_in preset serve' -l deny -r -F -d 'addresses or CIDRs refused, allow or not; \',\' between them'
-complete -c lw -n '__lw_in preset serve' -l format -r -F -d 'raw|txt|json: entry format'
+complete -c lw -n '__lw_in preset serve' -l format -r -F -d 'raw|txt|json: raw writes each message as it came, txt a line with time and level, json one object an entry'
 complete -c lw -n '__lw_in preset serve' -l from -r -F -d 'start|end: where reading a file starts'
 complete -c lw -n '__lw_in preset serve' -l hosts -r -F -d 'names and addresses, beyond this host\'s, of a self or issuer certificate; \',\' between them'
 complete -c lw -n '__lw_in preset serve' -l issuer_cert -r -F -d 'CA certificate file (lw tls ca), for tls=issuer'
 complete -c lw -n '__lw_in preset serve' -l issuer_key -r -F -d 'CA key file, for tls=issuer'
 complete -c lw -n '__lw_in preset serve' -l key -r -F -d 'key file, for tls=files'
-complete -c lw -n '__lw_in preset serve' -l listen -r -F -d 'HOST:PORT; [IPV6]:PORT'
+complete -c lw -n '__lw_in preset serve' -l listen -r -F -d 'HOST:PORT to listen on: 127.0.0.1:8080 this machine only, 0.0.0.0:8080 every IPv4 interface, [::]:8080 every IPv6 interface'
 complete -c lw -n '__lw_in preset serve' -l password_file -r -F -d 'file holding user\'s password; /dev/fd/N or a pipe is read once; default: /dev/tty, which asks'
-complete -c lw -n '__lw_in preset serve' -l path -r -F -d 'file, directory (its files) or glob to follow; default: standard input'
+complete -c lw -n '__lw_in preset serve' -l path -r -F -d 'a file, a directory (its files) or a glob such as /var/log/*.log, to follow; default: standard input'
 complete -c lw -n '__lw_in preset serve' -l proxy -r -F -d 'addresses or CIDRs of the TLS-terminating proxies browsers come through; \',\' between them'
 complete -c lw -n '__lw_in preset serve' -l tls -r -F -d 'off|self|issuer|files: plain text, a certificate made at startup (self-signed, or from issuer_*), or files'
-complete -c lw -n '__lw_in preset serve' -l user -o u -r -F -d 'SCRAM user: an edge\'s login, or a listener\'s only user in place of users'
+complete -c lw -n '__lw_in preset serve' -l user -o u -r -F -d 'the one SCRAM user readers log in as, in place of users'
 complete -c lw -n '__lw_in preset serve' -l users -r -F -d 'credentials file (lw auth add-user): readers log in with SCRAM'
-complete -c lw -n '__lw_in preset serve' -l viewer -r -F -d 'true|false: the login page and viewer, behind proxy; without user or users the viewer is always on'
+complete -c lw -n '__lw_in preset serve' -l viewer -r -F -d 'true|false: a login page, then the viewer, for browsers behind proxy; without user or users the viewer is on anyway'
 complete -c lw -n '__lw_in preset serve' -l help -o h -d 'print the flags'
 complete -c lw -n '__lw_in preset edge' -l ca -r -F -d 'CA file that verifies the aggregator; default: system roots'
 complete -c lw -n '__lw_in preset edge' -l cert -r -F -d 'client certificate file, for an aggregator with client_ca'
@@ -126,28 +126,28 @@ complete -c lw -n '__lw_in preset edge' -l from -r -F -d 'start|end: where readi
 complete -c lw -n '__lw_in preset edge' -l key -r -F -d 'client key file'
 complete -c lw -n '__lw_in preset edge' -l node -r -F -d 'origin label; default: this host\'s name'
 complete -c lw -n '__lw_in preset edge' -l password_file -r -F -d 'file holding user\'s password; /dev/fd/N or a pipe is read once; default: /dev/tty, which asks'
-complete -c lw -n '__lw_in preset edge' -l path -r -F -d 'file, directory (its files) or glob to follow; default: standard input'
+complete -c lw -n '__lw_in preset edge' -l path -r -F -d 'a file, a directory (its files) or a glob such as /var/log/*.log, to follow; default: standard input'
 complete -c lw -n '__lw_in preset edge' -l pin -r -F -d 'sha256//BASE64 of the aggregator\'s key, which it logs with tls=self'
 complete -c lw -n '__lw_in preset edge' -l server_name -r -F -d 'name the aggregator\'s certificate carries; default: to\'s host'
-complete -c lw -n '__lw_in preset edge' -l to -r -F -d 'the aggregator\'s HOST:PORT; [IPV6]:PORT'
-complete -c lw -n '__lw_in preset edge' -l transport -r -F -d 'tcp|http: tcp_chain or http_chain'
-complete -c lw -n '__lw_in preset edge' -l user -o u -r -F -d 'SCRAM user: an edge\'s login, or a listener\'s only user in place of users'
+complete -c lw -n '__lw_in preset edge' -l to -r -F -d 'the aggregator\'s HOST:PORT, an IPv6 address in brackets: logs.example.net:9000, [2001:db8::1]:9000'
+complete -c lw -n '__lw_in preset edge' -l transport -r -F -d 'tcp|http: tcp sends over one lasting connection (tcp_chain), http posts batches (http_chain)'
+complete -c lw -n '__lw_in preset edge' -l user -o u -r -F -d 'SCRAM user this edge logs in to the aggregator as'
 complete -c lw -n '__lw_in preset edge' -l help -o h -d 'print the flags'
 complete -c lw -n '__lw_in preset aggregator' -l allow -r -F -d 'addresses or CIDRs that may connect, of listen\'s family (either behind proxy=); default: all; \',\' between them'
 complete -c lw -n '__lw_in preset aggregator' -l cert -r -F -d 'certificate file, for tls=files'
 complete -c lw -n '__lw_in preset aggregator' -l client_ca -r -F -d 'CA file that verifies edge certificates (mTLS)'
 complete -c lw -n '__lw_in preset aggregator' -l deny -r -F -d 'addresses or CIDRs refused, allow or not; \',\' between them'
-complete -c lw -n '__lw_in preset aggregator' -l format -r -F -d 'raw|txt|json: entry format'
+complete -c lw -n '__lw_in preset aggregator' -l format -r -F -d 'raw|txt|json: raw writes each message as it came, txt a line with time and level, json one object an entry'
 complete -c lw -n '__lw_in preset aggregator' -l hosts -r -F -d 'names and addresses, beyond this host\'s, of a self or issuer certificate; \',\' between them'
 complete -c lw -n '__lw_in preset aggregator' -l issuer_cert -r -F -d 'CA certificate file (lw tls ca), for tls=issuer'
 complete -c lw -n '__lw_in preset aggregator' -l issuer_key -r -F -d 'CA key file, for tls=issuer'
 complete -c lw -n '__lw_in preset aggregator' -l key -r -F -d 'key file, for tls=files'
-complete -c lw -n '__lw_in preset aggregator' -l listen -r -F -d 'HOST:PORT; [IPV6]:PORT; [::] for IPv6 only'
+complete -c lw -n '__lw_in preset aggregator' -l listen -r -F -d 'HOST:PORT to listen on: 0.0.0.0:9000 every IPv4 interface, [::]:9000 every IPv6 interface, 127.0.0.1:9000 this machine only'
 complete -c lw -n '__lw_in preset aggregator' -l out -r -F -d 'directory for the received entries; default: standard output'
 complete -c lw -n '__lw_in preset aggregator' -l password_file -r -F -d 'file holding user\'s password; /dev/fd/N or a pipe is read once; default: /dev/tty, which asks'
 complete -c lw -n '__lw_in preset aggregator' -l tls -r -F -d 'self|issuer|files: a certificate made at startup (self-signed, or from issuer_*), or files'
-complete -c lw -n '__lw_in preset aggregator' -l transport -r -F -d 'tcp|http: tcp_chain or http_chain'
-complete -c lw -n '__lw_in preset aggregator' -l user -o u -r -F -d 'SCRAM user: an edge\'s login, or a listener\'s only user in place of users'
+complete -c lw -n '__lw_in preset aggregator' -l transport -r -F -d 'tcp|http: tcp sends over one lasting connection (tcp_chain), http posts batches (http_chain)'
+complete -c lw -n '__lw_in preset aggregator' -l user -o u -r -F -d 'the one SCRAM user edges log in as, in place of users'
 complete -c lw -n '__lw_in preset aggregator' -l users -r -F -d 'credentials file (lw auth add-user): edges log in with SCRAM'
 complete -c lw -n '__lw_in preset aggregator' -l help -o h -d 'print the flags'