README

=========================================================
General Instructions

The "ietf" program lets you access IETF-related files from the command line.
It creates a local copy of these files on your computer using rsync, and gives
a friendly way to access them. You can give commands from your normal shell,
or you can run an interactive shell that is part of the program.

These instructions assume that you are using a Unix-based system (including
MacOS), and are already comfortable with the command-line interfaces of your
shell. There are instructions for Windows users later in this document.

The "ietf" program requires Python 3. It also requires "rsync" to be installed
and available to the default shell.

The program consists of two files: "ietf" (the executable) and "ietf.config"
(mandatory configuration settings). The latter file must be either in one of
the following directories: ~/bin/, /usr/local/bin/, or ~/.ietf/. The
executable can be anywhere, but is probably best kept with the configuration
file.

You can make aliases in your shell for the program if you normally run it from
the shell command line to save keystrokes. For example, if you use the bash
shell, you might make an alias of:
   alias charter='ietf charter '

Edit the ietf.config with an editor. There is a description of the values at
the top of that file.  It is likely you will want to change the value of
DisplayTextCommand to be your favorite text editor and the value of the
DisplayWebCommand to be the executable for your favorite web browser.

=========================================================
Running the Program

There are two ways to run the "ietf" program: in its own command line
processor, or from your normal shell. For the former, just give the command
"ietf", and you will see the "ietf: " prompt. For the latter, give all the
arugments necessary after the "ietf" command itself. For example, to see the
charter of the TLS Working Group:

- In the command line processor, give the command "charter tls" at the
"ietf:" prompt

- From your shell, give the command "ietf charter tls"

There are many commands available; see the help text for a complete list and
description.

The first run of the program, you need to fill the local mirror with the
"mirror" command in the command line processor or "ietf mirror" from your
shell. This can take quite a while, particularly on a low-end broadband
connection.

=========================================================
Instructions for Windows Users

These instructions assume that you are already comfortable with command-line
interfaces, both Windows-style and Unix-style.

These instructions assume that you have WSL 2 on Windows 10. See
https://docs.microsoft.com/en-us/windows/wsl/install-win10
for instructions on how to install WSL. These instructions work for
the Debian installation under WSL, but should likely work with
any of the Linux distributions. In your distribution, be sure that
python3 is installed.