tii/README

tii: a Tcl-based suite for working with ii/IDEC protocol
========================================================
This suite implements the client side of ii and (partially) IDEC protocols of
distributed, cross-platform, text-based communication (a FIDOnet successor, so
to speak). Protocol documentation can be found here for both ii and IDEC:
https://github.com/IDEC-net/new-docs/blob/master/protocol-en.md
(there will be an effort to write a more concise version of that doc)

The tii suite requires at least Tcl 8.6 to run. Running it inside starpacks is
possible but not recommended.

The tii repo consists of the following parts:

* tiifetch.tcl: the core ii/IDEC message fetching library and CLI utility
* tiipost.tcl: the core ii/IDEC message posting library and CLI utility
* tiiview.tcl: the CLI viewer of the fetched ii/IDEC messages and conferences
* tiidb: the (overridable) directory that contains all messages and echo lists
* stations.txt: the list of stations to be auto-fetched by tiifetch when none
  of its command-line parameters is passed
* auth.txt: the list of station/authstring mappings to be used by tiipost when
  posting messages to a particular station
* tiix.tcl: the GUI ii/IDEC viewer that also leverages tiifetch and tiipost to
  provide fetching and posting functionality

Readiness status
----------------
* tiifetch.tcl: ready/tested
* tiipost.tcl: planned
* tiiview.tcl: ready/tested
* tiidb (format): ready/tested
* stations.txt (format): ready/tested
* auth.txt (format): ready to be implemented
* tiix.tcl: planned
* Overall status: work in progress

Usage
-----
This section is a work in progress and will be updated as more components are
developed.

### Fetching the messages (tiifetch.tcl): ###

tclsh tiifetch.tcl [station_url] [echos] [dbdir]

This command will fetch all messages into the dbdir ("tiidb" in the script dir
by default) from the station_url (can be empty, see below) based on the echo
conference names (can be delimited with slash /, comma (,) or semicolon (;))
and create the corresponding file structure if it's missing.

Fetching is supported for the following station URL schemes and protocols:

* HTTP (http://)
* HTTPS (https://)
* Gopher (gopher://)
* Gopher over TLS (gophers://)
* Finger (finger://)
* Nex (nex://)
* Spartan (spartan://)
* Gemini (gemini://)

If the station_url parameter is empty or no parameters are passed at all,
tiifetch.tcl will look for a file called stations.txt that lists (each on a
new line) all the station URLs to sync from. Messages from all listed stations
will be merged into the same echo conference database.

### Viewing the messages from CLI (tiiview.tcl): ###

tclsh tiiview.tcl [echo_name] [filter_string] [line_width] [dbdir]

If the echo_name parameter is passed, this command will write all formatted
messages from the coresponding echo conference to the standard output.
You should pipe this message stream to your $PAGER terminal application, like
less or most. The messages will be formatted according to the filter_string
format (see below). If the filter string is empty or omitted, the messages
will appear in the exact order their IDs appear in the echo conference file.

If the echo_name parameter is empty or no parameters are passed at all, this
command will output the list of echo conferences registered in the dbdir.
The conference list will be alphabetically ordered and the filter_string will
have no effect at all if you pass it.

If the line_width parameter is omitted, the text reflows to 80 chars per line.

If the dbdir is ommitted, it defaults to "tiidb" in the script directory.

This component is fully offline and can only work with a compatible message
database that tiifetch.tcl can generate (see "Message database format").

The filter string can take one of the following basic forms:

* h[number]: only take [number] messages from the head (start) of the list
* t[number]: only take [number] messages from the tail (end) of the list
* rh[number]: same as h but output messages from newest to oldest in the list
* rt[number]: same as t but output messages from newest to oldest in the list

If [number] is 0 then it means no message limit.
The reverse operation is always done after limiting the results.

e.g. rt50 will output 50 newest messages in the conference, starting from the
most recent one. The default basic value is h0, so no filter applied will mean
outputting all messages from the oldest to the newest.

You can extend the basic form by appending a search regular expression to it,
like this: [form]/[regex]. Note that the regex always applies AFTER the basic
filtering has been done. Also note that the search is done within all fields
of the message. E.g. h100/retro will find the retro-themed messages among the
first 100 of them.

Message database format
-----------------------
The tiidb format is based upon the official ii/IDEC developer recommendations
and is fully plaintext-based, portable and very simple:

* Message contents are stored decoded in the "msg/" subdirectory. The file
  names are their plain 20-character hash IDs.
* Echo contents are stored in the "echo/" subdirectory. The file names are the
  conference names verbatim, containing newline-separated message IDs that
  belong to those conferences, in order they were published there.
  Every echo file ends with a blank line.

FAQ
---

- Does tii implement any IDEC extensions?

Only one: fetching list.txt from the station to get the entire list of echo
conferences served by this station. This is something that the original ii
spec did not support.


Credits
-------
Created by Luxferre in 2024, released into public domain with no warranties.