diff --git a/wiki/source/tin.md b/wiki/source/tin.md index 92ce9fa..cfac41a 100644 --- a/wiki/source/tin.md +++ b/wiki/source/tin.md @@ -3,15 +3,6 @@ title: tin (Usenet client) category: software author: - ant -todo: - - describe the common entry prefixes on: - - groups - - threads - - articles - - arrange the principal keys in the way most convenient to the learner: - - with grouping by relative function - - with ordering by decreasing importance. - - abridge that list, leaving out the less important ones? --- [*tin*](http://www.tin.org/) @@ -19,9 +10,19 @@ is a text-mode threading NNTP and spool-based [Usenet](usenet-news.html) client for a variety of platforms. +We start with configuring a connection in *tin*. +That done and *tin* having started without errors, +jump over to +[Interface overview](#interface-overview) +lest you become lost and bewildered +in its apparently unwelcoming +blank screen of emptiness, +which only seems that way +to the uninitiated. + ## Local connection -`tin` is installed on `tilde.club` +*tin* is installed on `tilde.club` and preconfigured to access the local spool of the `news.tilde.club` server by default. @@ -29,23 +30,23 @@ You need only run `tin` without arguments: ``` $ tin ``` -There is also a local NNTP server +There is also a local NNTP port on the `tilde.club` premises, to which you can connect via: ``` $ tin -r [-g localhost[:119]] ``` -You can forward this port over SSH -to your own machine -and point your local *tin* -(as well as any newsreader) -to it. +`-r` stands for *remote*, +and `rtin` acts as an alias to `tin -r`. +`-g` specifies a server or its alias, +overriding the default, +and implies `-r`. ## Remote connection ### Server configuration -To connect `tin` to a remote news server over NNTP, +To connect *tin* to a remote news server over NNTP, a little bit of setup is required. By default, most of your *tin* configuration is located in the `.tin` directory in your home. @@ -62,7 +63,7 @@ with the following whitespace-separated fields: to store an index of downloaded articles. for each newsgroup. -3. optionally---but highly recommended---a +3. optionally--but highly recommended---a short alias for the server, to facilitate invocation of *tin*. @@ -75,63 +76,65 @@ news.gmane.io ~/.tin/newsrc.gmane gm * ~/.tin/newsrc.local ``` Now you can connect to any of the registered servers -via `rtin -g`. +via `tin -g`. For example, to read the `tilde.club` server configured above, enter: ``` -$ rtin -g tc +$ tin -g tc ``` -But you will not be able to post yet, -if the server requires authorisation, +But you will not be able to post yet +if the server requires authentication, as most servers do: -### Authorisation +### Authentication *tin* reads your credentials for each server from the file `.newsauth`, by default located in your home directory. -It also has a table structure similar to `.newsrc`, -with one line per server, -but this time the fields are: +It also has a table structure +similar to that of `newsrctable`, +with one line per server. +This time, the fields are: 1. server address, 2. password, 3. username. -For example, my line for tilde.club server -(with a dummy password, however) is: +For example, my line for the `tilde.club` server +(with a fake password, however) is: ``` news.tilde.club ant H1dd3nPa$$w0rd ``` Some servers -(*Eternal September* is +(*Eternal September* being [one of them](https://www.eternal-september.org/index.php?language=en&showpage=faq#Login-No-Auth)) -require that the client authorise +require that the client authenticate immediately upon connect, or they will not show you all newsgroups, if any. -To cause *tin* to authorise immediately, +To cause *tin* to authenticate early, pass the `-A` option, e.g: ``` -rtin -Ag es +tin -Ag es ``` If you are among the unlucky fellows who are guilty of using a password with space or -(I tremble to say) +(we are embarrassed to say) tab characters, you will need to enclose it in double quotes (`"`). Make sure your `.newsauth` is not readable by other users: ``` -$ chmod 600 ~/.newsauth +$ ls -ld ~/.newsauth # view permissions +$ chmod 600 ~/.newsauth # set permissions ``` ### Specifying the NNTPS protocol -By default, `rtin` connects over the unencrypted NNTP protocol. +By default, `tin` connects over the unencrypted NNTP protocol. These days, however, most servers support the more secure NNTPS. To cause *tin* to use it, it should be invoked with the `-T` option. @@ -140,144 +143,73 @@ with the necessary initial authorisation and the recommended encrypted connection, is: ``` -$ rtin -ATg es +$ tin -ATg es ``` -### Simplifying the invocation - -If remembering to supply -`-T` and `-A` -for servers that require them -annoys you, -consider storing -the complete invocation -in an alias in your shell's initialisation script -(`~/.shrc` for `sh`, -`~/.bashrc` for *Bash*), e.g.: +### Persisting server-specific commandline parameters + +To save the remembering whether +`-T` and `-A` are required for a server +and typing them at every invocation, +these options can be indicated in the +server-specific configuration file `serverrc`, +the default full path to which is: ``` -alias news_es='rtin -ATg es' +~/.tin//serverrc ``` -or use an the wrapper script below, -which will determine -whether `-T` and `-A` are needed -and supply them to *tin* for you: -
+where `` is the news server hostname +(as specified in `newsrctable`). +The `add_cmd_line_opts` parameter in that file +specifies additional commandline options +that *tin* is to assume while connecting +to that server. +For example, +to set `-A` and `-T` for *Eternal September*, +I added the following line: ``` -#! /bin/sh -# tinr--launch the tin(1) newsreader -# with a specified newsserver alias, -# automatically providing the options -# -A (authorisation) and -T (NNTP over TLS) -# if they are required, -# to save the user remembering -# the respective properties of each server. -# Invoke as: -# # $ tinr [params] -# supplying a server alias -# and optionally whatever parameters -# you want to pass to tin. -# -A is provided if the server is present in .newsauth, -# and -T--if newsrctable in its fourth field -# specifies any second alias for the server. -# # -# #Written by: Anton Shepelev -# #and released into the void under The Unlicense: -# # -#SPDX-License-Identifier: Unlicense -#URL: - -help()\ -{ sed -ne ' - 1d -# prefix-juggling to keep the script compatible -# after conversion of tabs to spaces, -# as Markdown processors will often do: - s/^#\([ ]\+\)/PREF/ - t cont; q - :cont - s/^PREF#// - p - ' $0 \ - | fmt -74 -p "PREF"\ - | sed -e 's/^PREF//' - exit 1 -} - -help_ref="See tinr -h for instructions." -while getopts h opt; do - case $opt in - h) help; exit 0;; - ?) [ ${OPTARG-x}=x ] && echo $help_ref && exit 1; - esac -done -shift $(($OPTIND - 1)) - -if [ $# -lt 1 ]; then - echo 1>&2 \ -A server alias is not specified. $help_ref - exit 1 -fi -alias=$1 - -nrct=${TIN_HOMEDIR:-"$HOME"}/.tin/newsrctable -naut=${TIN_HOMEDIR:-"$HOME"}/.newsauth - -get_serv() \ -{ - [ ! -r $nrct ] && return 1 - - script=$( - awk -e ' - /^[^#]/{ if( $3=="'${alias}'" ) - { print $1 - if( $4 ) - print("T") - exit - }}' \ - < $nrct - ) -# awk failed, exiting: - if [ $? -gt 0 ]; then exit 1; fi -# no server entry was found: - if [ ! -n "$script" ]; then return 1; fi -# a server entry was found: - while read s o; do - server=$s - opts=$o - done < -The script above will add `-A` -if the server is present in your `.newsauth` -and `-T` if a secondary alias is assigned to it -in the fourth column of `newsrctable`. -Invoke it with the primary alias of the desired server, -optionally followed by -whatever arguments you may want to pass to *tin*, e.g.: +to my +`~/.tin/news.eternal-september.org/serverrc` . + +Now I can connect with just: ``` -$ tinr es # connect to Eternal September -$ tinr tc -o # submit all postponed articles +$ tin -g es ``` +See +[tin(5)](http://www.tin.org/bin/man.cgi?section=5&topic=tin) +for a list parameters supported +in that configuration option. ## Interface overview +### Built-in help + +When *tin* starts for what it thinks is the first time, +it shows an introductory help screen, +which you are advised to peruse. +If you skipped it, +press `q` to quit *tin*, +delete your `~/.tin` directory, +(or rename it +if it already contains your customisations, +to reinstate it later) +and start *tin* again. + +After the intro, +you end up in the main interface, +where context-sensitive help is available in two forms: + +1. as a brief on-screen summary of most important keys, + toggled by `H` and shown by default, and +2. as a more (but not quite) + complete full-screen command reference + invoked by `h` + and sporting its own keys summary (`H`) + for navigation. + +### Basic operation + *tin* works at four nested levels with (more or less :-) uniform navigation @@ -295,7 +227,18 @@ thread articles T article single article A - -*tin* starts at the topmost level (selection). +*tin* starts at the topmost level (selection), +showing a list of subscribed newsgroups. +If you are running it for the first time, +the list will be empty. +Press `y` to yank in the available newsgroups, +then subscribe to the desired ones, +by selecting a group with either of +`j`/`k` for up/down, +`[0-9]+` for group number, or +`/` for textual search, +and subscribing to it with `s`. +Press `y` again to see only subscribed groups. Whereas the selection, group, and article levels @@ -317,19 +260,16 @@ often borrowed from [The Vi editor](vi.html) interface. The most important keys are: ----- ------ -------------------- -Key Level Action ----- ------ -------------------- -H SGTA toggle on-screen help, - useful for learning - -h SGTA list available commands +--- ------ -------------------- +Key Level Action +--- ------ -------------------- +H SGTA toggle panel with brief help -j/k SGT next/prev. group/thread/article +h SGTA view full-screen help -j/k A next/prev. line in text +j,k SGTA next/prev. group/thread/article/line -[0-9]+ SGR highlight by number +[1-9]+ SGR highlight by entry number Return SGT level-down (into highlighted element) @@ -343,22 +283,26 @@ l GA open thread view, mem. as *l*ist of articles y S toggle display of all/subscribed groups -s/u S subscribe/unsubscribe to/from selected group +s,u S subscribe/unsubscribe to/from selected group r SG switch between read/all -TAB SGTA to next unread article from anywhere +TAB,n S into next unread group -p/n GA prev/next +TAB GTA open next unread article -P/N A prev/next unread +N,P GA open prev/next unread article -w G make a new post +n,p GA open next/prev article + +N S select next unread group + +w G write a new post f A follow-up (reply) -c/C SGTA mark group (SG) or thread (TA) as read - and move to the next unread (C) one +c,C SGTA catch-up (mark read) group (SG) or thread (TA) + and move to the (`c`:next, `C`:next unread) one K GTA mark current thread (G) or article (TA) as read and move to the next unread one @@ -372,8 +316,70 @@ Y S load new posts from the server (if any) M SGTA open the menu - -For a complete UI reference and settings, -see the +## Solutions to typical problems + +### Posting fails for lack of an FQDN + +Well, *do* get yourself an FQDN, +becoming a first-class netizen. +While you are busy acquiring a domain, +obtaining a static IP from your ISP, +building yourself a server, +and configuring an +authoritative domain-name server on it, +set your `$HOSTNAME` environment variable +to a value resembling an FQDN, +by adding some such statement as +``` +export HOSTNAME=invalid.domain +``` +to your interactive shell's init script +(`~/.profile`, `~/bash_profile`, &c) +as a temporary solution[^1]. + +If such mockery is below your standards +or otherwise offends your taste, +add the line `disable_sender=ON` +to the `/etc/tin.defaults` file. +You will need root access to do that. +If you don't have it, +ask your +~~[BOFH](https://yourtilde.com/~u0x7f/bofh-archive)~~ +systems administrator to do it for you. + +[^1]: There is nothing more permanent than the temporary. + +### Tin takes too long to start + +Try starting it with the `-Q` option. + +## See also + [tin(1)](http://www.tin.org/bin/man.cgi?section=1&topic=tin) -manpage. +for a UI reference and +[tin(5)](http://www.tin.org/bin/man.cgi?section=5&topic=tin) +for a configuration reference. + +## Credits + +The following people have helped improve the article: + +- [lafe](https://tilde.club/~lafe/), +- [The Free Thinker](gopher://aussies.space/1/%7efreet/), +- Urs Janßen. + +## Debits + +- Shall I describe the common prefixes on + - groups, + - threads, and + - articles, + + or merely direct the reader to the manual? +- arrange the principal keys in the way most convenient to the learner: + - with grouping by relative function + - with ordering by decreasing importance. + - abridge that list, leaving out the less important ones? +Questions and improvement proposals are welcome +at the author's `@tilde.club` e-mail.