Compilation and installation notes for tin - 98-08-02 (still incomplete!)
-----------------------------------------------------

Note: The section 'News machine names' is now at the beginning as it
      seemed to be the most sought after section.

This following configure options and defines are documented in detail:
----------------------------------------------------------------------
  --enable-8bit-keys	     --with-inn-nntplib		HAVE_FASCIST_NEWSADMIN
  --enable-color	     --with-iso-to-ascii	HAVE_MMDF_MAILER
  --enable-curses	     --with-ispell              HAVE_LIBUU
  --enable-debug	     --with-libdir		INDEX_DAEMON
  --enable-etiquette	     --with-metamail		NNTP_INEWS
  --enable-forgery	     --with-ncurses		NNTP_SERVER_FILE
  --enable-locale	     --with-nntp-default-server NO_POSTING
  --enable-mh-mail-handling  --with-nov-dir		NO_SHELL_ESCAPE
  --enable-nntp		     --with-pgp			LOCAL-CHARSET
  --enable-nntp-only	     --with-spooldir		SMALL_MEMORY_MACHINE
  --with-domain-name	     DONT_HAVE_PIPING		USE_INVERSE_HACK
  --with-inews-dir	     --with-defaults-dir	--disable-xhdr-xref


News machine names
------------------

--with-domain-name
Defines the name of your news gateway machine. Useful if you don't want
your internal network visible to the outside world, or if your inews script
or NNTP server rewrites your address for you.
If the first letter of the string is a '/' the gateway name will be read from
the specified file.

Example 1: If you are on machine 'tragic' at network domain 'confusion.com',
Tin will assume your From: line should read "user@tragic.confusion.com".  If
your inews script instead rewrites your address as "user@confusion.com", you
will be unable to cancel your own postings.  To make your posts and cancels
work properly, define -DDOMAIN_NAME=\"confusion.com\"

General Notes on Building Tin
-----------------------------

Tin has been compiled on a wide range of Un*x machines with cc and gcc.
It has even been ported to other systems like the Amiga.
A list of these machines can be found at the end of this file.

This file is long (so was the yellow brick road) but please read it all
as it could save you problems later and we don't want an unhappy ending
do we ? :-)

Tin can be compiled to read news in any of the following ways:

  o  locally from your machines news spool dir (default /var/spool/news).

  o  locally and remotely via NNTP (rtin or tin -r option) (--enable-nntp).

  o  remotely via NNTP (--enable-nntp-only).

If the remote server supports NOV overview indexing, then tin will retrieve
overview data on the fly using the NNTP XOVER extension.
Otherwise tin will create its own NOV style index files on the local machine
for each user in $HOME/.tin/.index

Many machines require the name of the news gateway machine or the news
domain to be set via the --with-mail-gateway or the --with-mail-domain
configure options.  This is true of both NNTP and local news systems.


Building the Normal version:
----------------------------

1)  Type './configure --help' to see which options are needed for your
    local setup.
2)  Change conf-tin for your needs or run ./configure with all needed
    options.
3)  type 'make build' to build tin in the src/ directory.
    Alternatively goto the src subdirectory and type 'make'
4)  Type 'make install' to install.

Building the Index daemon version:
----------------------------------

(This feature is deprecated. Use it only if your server doesn't support
NOV overview files)

Note1: If you want to retrieve tin index files from your NNTP server,
       or if you don't run NNTP but want to install tin setuid and have
       a central index rather than each user keeping his/her own index
       and want tind to automatically keep the index up-to-date, then
       you will need the tind index file daemon; create it using the
       following steps:

   1)  Build and install the 'Normal version' of tin as specified by the
       above 4 points.
   2)  Run "make clean" to delete the *.o files from the normal version.
   3)  The tind index daemon needs to be installed on your NNTP server,
       or on your stand-alone news server if you're not using NNTP.
       More info. concerning my NNTP patches & the tin daemon can be
       found in the INSTALL.NNTP file.  If you don't use NNTP, just
       install tind on the machine that has the news spool directory.
   4)  Apply my NNTP patches to your nntpd server or this will not work
       with NNTP!!!. (If you want tind locally read Note3).
   5)  Edit the Makefile and add -DINDEX_DAEMON to your CPPOPTS entry and
       remove any -DNNTP_* defines. Also remove -lcurses, -ltermcap, and
       any other screen-handling libraries used, as tind does not need to
       be linked with curses and it will save a good 30-50K on the size of
       tind.
   6)  Type 'make <system type>' to compile tind daemon for your NNTP server
       or stand-alone news server.  This creates tind as the file "tin".
   7)  Rename the file "tin" to "tind" (i.e. mv tin tind).
   8)  Type 'make install_daemon' to install tind daemon on your NNTP server
       or stand-alone news server.
   9)  Add the following line to your system cron to run tind every 30 mins:
              00,30 * * * * su news -c '/usr/lib/news/tind'

Note2: tind must be run as user 'news' and the normal tin must have
       the correct permissions to read the central index files!
Note3: tind can also be used to update a copy of all index files

Testing Tin
-----------

Of course you _were_ going to test it before installing it for anyone else
to use, weren't you?  This is just a little reminder and some suggestions
on what to test first, and where to look first if it's broken.

Things to test:

1) Check that you can read news from several local and world-wide groups.
   If this fails, check that the NNTP define directives are correctly set,
   and for local news systems, that the News directory structure define
   directives are correctly set.  For NNTP versions, check that the server is
   actually running and can be connected to from your machine.  This should
   help you find and fix some of the most common problems.

   If reading news works fine, then:

2) Check that you can post a test message to a local distribution group,
   preferably a test-only group.  (Remember, the world does not care to
   know whether you are testing Tin.)  If it fails, check that the
   INEWSDIR define is correctly set, that NNTP_INEWS is correctly set, and
   that the News machine name define directives are correctly set.  If
   possible, check whether you can post via some other mechanism, such as
   Pnews.  This should help you isolate and fix the most common problems.

   If posting news works fine, then:

3) Check that you can cancel one of your test postings.  If not, it is
   almost certain that your News machine defines need to be set correctly,
   because Tin thinks your From: line is different from what has actually
   been posted.  See the section on News machine names below.

Further testing is desirable, but left to your individual conscience and
ingenuity.



Detailed list of configure options (beginning with '--') and compiler flags
(-D<name> directives)

News directory structure
------------------------

--with-libdir=PATH
Define if news software is not in /usr/lib/news.
(only needed if not running --enable-nntp-only)

--with-spooldir=PATH
Define if news articles are not in /var/spool/news.
(only needed if not running --enable-nntp-only)

--with-nov-dir=PATH
Define if news overview (NOV) files are not stored in SPOOLDIR.
(only needed if not running --enable-nntp-only)

--with-inews-dir=PATH
Define if bnews/cnews program 'inews' is not in NEWSLIBDIR.

NNTP - Reading & posting news
-----------------------------

--enable-nntp (default: on)
Define if you wish to read news locally and remotely via an NNTP server.

--enable-nntp-only (default: off)
Define if you [want to | can] ONLY read news remotely via an NNTP server.

--with-nntp-default-server (default: news.$DOMAIN_NAME)
Defines the name of the default NNTP server that tin should connect to.
Can be overridden by setting the environment variable NNTPSERVER.

NNTP_INEWS
Define if you want to use my built-in NNTP POST routine so that you no
longer have to rely on the mini-inews from NNTP to be installed on each
client machine. Also check that DOMAIN_NAME is correctly set to produce a
correct From: headers for your site. If defined then the ~/.tin/tinrc
variable "use_builtin_inews" default will be set to OFF rather than ON. The
tinrc file is created automatically for each user the first time they use
tin.

NNTP_SERVER_FILE
Only define if your NNTP-server file is other than /etc/nntpserver.

NETLIBS
Contains the networking libraries needed to link with nntplib.o file.

Daemon options
--------------

INDEX_DAEMON
Define to make an index file updating daemon version of tin. Note that
no -lcurses or screen libraries need to be linked with tin when this
#define is specified. If defined this will automatically undefine all
NNTP_* defines as the daemon has to be installed on the NNTP server.


Miscellaneous options
---------------------

--enable-debug
Define if you want tin to log debug info. to files in /tmp. Activated
by tin -Dn where n is 1 for NNTP only debug logging and n is 2 for
logging all debug info. Debug files written to /tmp are ARTS, ACTIVE,
BASE and NNTP.

--enable-forgery
Define if you want to be able to cancel postings you did not write
yourself.  The !cyberspam and cancel conventions are supported.  Be
careful with this feature, it should not be used in an free accessible
tin.  This feature does not work with INN using the INN-inews (when
using without NNTP), because INN-inews rejects these cancels.

--enable-8bit-keys
Define if your terminal generates 8-bit controls.  For Unix systems we
assume this may imply your arrow keys begin either with CSI (0x9b) or SS3
(0x8f).  Most ANSI terminals generate 7-bit controls (e.g., CSI is
"<esc>["), but some such as VT220 can be configured more efficiently to
generate 8-bit prefix codes, saving a byte per control sequence.  This
applies to cursor movement at the same time.  The actual codes are read
from termcap (this does not affect the curses configuration).

--enable-color
Define if you want to have ANSI-color support.  This works on most
color displays and the color xterm.  The color mode can be switched
on/off in ~/.tin/tinrc (use_color) and can be toggled with option -a
or key '&'.

--with-defaults-dir=PATH

--with-ispell=PATH
Define if you have ispell (interactive spell-checker) installed and want the
option of checking your articles, mails before posting/mailing them.
If found in search path, this is used automatically.

--with-metamail=PATH
Define if you want metamail display your MIME messages.
If found in search path, this is used automatically.

--enable-mh-mail-handling
Define if you want to use the MH style mail handling & reading code in mail.c
It should be noted that mail handling is not well tested and not yet fully
implemented. You can expect errors if you use this define so let me know the
problems by sending me a bug report ('R' bug command from within tin).

--with-pgp=PATH
Define if you have PGP (Pretty Good Privacy encryption system)
installed and want the option of checking signatures, extract keys,
sign messages and add public key to messages.  This is bound to the
key 'g' or '^G'.
If found in search path, this is used automatically (pgp-5 is prefered
over pgp-2).

--with-inn-nntplib=PATH
Define if you want to use the INN library functions GetConfigValue()
& GetFQDN().  The INN_NNTPLIB variable in the Makefile must contain
the correct path to INN library.

--with-iso-to-ascii
Define if you want tin to do ISO-8859-1 Charset to ASCII conversations
by default for all groups. You must specify a value of "0-6" to get tin
to use one of the 7 conversion tables for different languages.
i.e., Adding -DUSE_ISO2ASC=\"2\" to the CPPOPTS line in the Makefile would
be useful in the german language newsgroups. For more detailed info
read the file ./doc/iso2asc.txt. Default value for USE_ISO2ASC is "-1".

LOCAL_CHARSET
Define LOCAL_CHARSET if you like charset conversertions.
set LOCAL-CHARSET to one of the following values:
	437	ibm437<->iso-8859-1 conversation
	850	ibm850<->iso-8859-1 conversation
	1	next<->iso-8859-1 conversation
	unset	no conversation (default)

--with-ncurses
Define this if you want to link with ncurses instead of termcap.

--enable-curses
Define this if you wish to use the curses screen optimizing rather than
termcap.  This has been tested well only with ncurses 4.1; it should work
(except for mouse support and screen resizing) with SVr4 curses (Solaris
2.5 is known to have a bug in libc which prevents use of curses, ncurses
works well on that platform).  To build with ncurses screen optimizing,
you must give both the --with-ncurses and --enable-curses options.

--enable-etiquette (default: on)
If enabled, prints netiquette before posting.

--enable-locale (default: on)
If enabled, tin uses multi language support, as described in
locale(7).  If you don't have locale support installed on your system,
try --disable-locale, otherwise you won't see any 8-bit-characters.

DONT_HAVE_PIPING
Define if your system does not support piping of articles to shell commands.

HAVE_FASCIST_NEWSADMIN
Define if you want users articles to be posted to groups that your site
receives.  This will change the warning that a group that the user is
posting to was not found in the sites active file to an error in the
article checking routine therefore causing the user to remove the group
from his/her posting or to abort the posting of the article.

HAVE_MMDF_MAILER
Define if your machine uses a MMDF type mailer instead of sendmail.
It is defined as default on SCO Unix machines. It can be dynamically
changed by setting the tinrc variable save_to_mmdf_mailbox to ON.

NO_POSTING
Do not allow posting/followup of articles.

NO_SHELL_ESCAPE
Do not allow shell escapes.

USE_INVERSE_HACK
Define if you want inverse video and highlighted bar disabled. Can be
toggled in tin by the 'I' command and highlight bar by 'M' command.

SMALL_MEMORY_MACHINE
Define if you are running a machine with little memory (<4MB). Tin will
run slightly slower but be more efficient in how memory is allocated and
reclaimed.

--disable-xhdr-xref
don't allow using XHDR XREF if XOVER dosn't work to mark crossposted
articles as read in all groups.


Compiled & installed on the following machines:
-----------------------------------------------

1)	i486 & Linux 0.99.14w with gcc 2.5.7
	i486 & Linux 1.2.13 with gcc 2.7.0
	i486 & Linux 2.0.34 with gcc 2.7.2.2
	i486 & Linux 2.0.33 with gcc 2.7.2.3 (glibc 2.0.7)
	i586 & Linux 2.0.27 with gcc 2.7.2.1
	DEC Alpha AXP & Linux 2.0.0 with gcc 2.7.1
	Amiga 4000/040 & Linux 2.0.29 with gcc 2.7.2
	Power Macintosh 7200/75 & Linux 2.0.30 with gcc 2.7.2.1

2)	HP 9000/835 & HP-UX 8.00 with cc
	HP 9000/825 & HP-UX 8.00 with gcc 2.7.2
	HP 9000/735 & HP-UX 9.02 with gcc 2.6.3
	HP 9000/720 & HP-UX 9.05 with cc
	HP 9000/720 & HP-UX 9.05 with gcc 2.7.2
	HP 9000/715 & HP-UX 9.07 with cc
	HP 9000/715 & HP-UX 9.07 with gcc 2.7.2
	HP 9000/375 & HP-UX 9.10 with gcc 2.7.2.3
	HP 9000/819 & HP-UX 10.10 with cc
	HP 9000/819 & HP-UX 10.10 with gcc 2.7.2
	HP 9000/829 & HP-UX 10.20 with cc
	HP 9000/829 & HP-UX 10.20 with gcc 2.8.1

3)	VAX 8350 & Ultrix 4.0 with gcc 1.4.0
	VAX 8350 & Ultrix 4.0 with gcc 2.7.2
	DEC Station ??? & Ultrix 4.3 with gcc 2.6.3

4)	AlphaStation 3000 & Digital UNIX 3.2c with gcc 2.7.2
	AlphaStation 600 5/266 & Digital UNIX 3.2 with cc

5)	AlphaStation ??? & OSF/1 v3.2 with cc
	AlphaStation ??? & OSF/1 v3.2 with gcc 2.7.2

6)	Sun SPARCstation 10 & SunOS 5.5 with cc 3.0.1
	Sun UltraSPARC Enterprise 2 & SunOS 5.5.1 with gcc 2.7.2
	Sun SPARCserver 1000 & SunOS 5.5 with cc 3.0
	Sun SPARCsystem 10/30 & SunOS 5.4 with gcc 2.6.3
	Sun 3/60 & SunOS 4.1.1_U1 with gcc 2.7.2.2
	sparc-sun-solaris2.5.1 with Sun Sparcworks compiler (v 4.2)

7)	Intergraph Clipper & CLIX 7.5 with gcc 2.7.1

8)	i486 & BSDI 2.0 with gcc 1.42
	i486 & BSDI 2.0 with gcc 2.6.3

9)	i486 & NetBSD 1.1 with gcc 2.4.5
	i486 & NetBSD 1.2 with gcc 2.7.2
	Amiga 4000 & NetBSD 1.2 with gcc 2.7.2
	Sun 3/60 & NetBSD 1.2G with gcc 2.7.2.2

10)	i386 & FreeBSD 2.1.0 with gcc 2.7.2
	i586 & FreeBSD 2.2.7 with tcc 4.0 (TenDRA-4.1.2)
	i486 & FreeBSD 2.2.7 with gcc 2.7.2.1
	i586 & FreeBSD 3.0-SNAP-971208 with gcc 2.7.2.1

11)	IBM PowerPC RS6000/40p & AIX 4.1.5.0 with gcc 2.8.1
	IBM RS6000/990 & AIX 4.1.5 with xlc
	IBM 7012/320H & AIX 3.2 with gcc 2.3.3

12)	i586 & SCO OpenServer Enterprise System (ver 5.0.0b)
	with SCO OpenServer Development System (ver 5.0.0a)
	i386 & SCO System V Rel 3.2v4.2 with SCO Development System and
	International Supplement (in other words, regular system cc)

13)	i386 & XENIX 2.3.3 with gcc 1.37.1

14)	NeXT Computer & NeXTSTEP 3.3 with gcc 2.5.8

15)	SGI SC900 Power Challenge & IRIX 6.2 with gcc 2.7.2
	SGI SC900 Power Challenge & IRIX 6.2 with cc -32
	SGI Indigo2 & IRIX 5.3 with gcc 2.7.2
	SGI 4D/35 & IRIX 5.2 with IDO 5.2
	SGI 4D/35 & IRIX 5.2 with gcc 2.8.1

16)	m88k mc88110 & UNIX_System_V 4.0 R40V4.4
	with Motorola Configurable C Compilation System (CCCS) 1.0

17)	Amiga 4000 & AmigaOS 3.0 with SAS/C 6.57

18)	OpenVMS/Alpha 6.2, DEC C V5.0-003,                  SOCKETSHR_TCP
	OpenVMS/Vax   5.3, GCC 2.7.2 (Pat Ranking edition), SOCKETSHR_TCP