Hackers notes for tin v1.2 - 22-09-93
-------------------------------------

This document is a brief internal overview of tin. This is probably only 
going to be useful to the guys & gals who want to *modify* tin's source.

The most  important  thing to do before  modifying tin  is to check the
version & patchlevel in patchlev.h.  Its not much  use fixing something 
in an older version when I or someone else have already fixed it in the 
current one.

The second most important thing to do before starting to modify tin is 
to check with me that your idea or problem is not already being worked
on by me or somebody else. 

The latest version can be found at the FTP sites listed in the FTP file.

All special defines (ie. machine/OS specific) should be put in config.h
so that all the other source files can be less OS specific. Example:

    /* file.c */
    #ifdef sun  /* OS specific */    
        ...
    #endif

  Would be more portable if it was broken down as follows:

    /* config.h */
    #if defined(sun) || defined(__hpux)
    #   define HAVE_LONG_FILENAMES
    #endif

    /* file.c */
    #ifdef HAVE_LONG_FILENAMES
        ...
    #endif 

General defines and struct definitions should be put in tin.h

All function prototypes (K&R and Ansi) should be put in proto.h

All extern's (external declarations) should be put in extern.h

All global variables should be put in init.c

All global variables should if possible be set to a reasonable default
when starting. The function init_selfinfo() in init.c should be used.

Language text strings (ones that will be displayed to the user) should
be put in lang.c and the accompanying extern declaration in extern.h
This allows easier translation of tin to a foreign language. Example:

    /* extern.h */
    extern char txt_hello_world[];

    /* lang.c */
    char txt_hello_world[] = "hello world";

    /* file.c */
    ...
    printf (txt_hello_world);
    ...

Many parts of tin can be dynamically controlled by  variables whose
values are read in from the config file ~/.tin/tinrc when starting.
The reading and writing of the tinrc file is accomplished by the
functions read_rcfile() and write_rcfile() in rcfile.c

The main internal structures that riddle the code are:

    struct group_t *active                /* array of groups in active file  */
        struct attribute_t attribute      /* group specific attributes       */ 

    struct arts_t *arts                   /* array of all arts in group      */

    struct kill_t *kill                   /* global filters (select & kill)  */

    struct screen_t *screen               /* array of cols & rows of screen  */  

    struct save_t *save                   /* array of articles to be saved   */

Documentation
New/modified commands should be described in the manual page tin.1
Additions/modifications should be technically described in CHANGES
#defines that change tin's behaviour should be described in INSTALL

New/modified source code should be written to meet the following criteria:
o  Easy to read (i.e., nothing cryptic as I will be the future maintainer).
o  Efficient upto the point of not being cryptic.
o  Block structured with accompanying descriptive comments.
o  Consolidation of similiar actions into function()'s or the same file.
o  K&R Function headers (due to older systems that only have K&R C compiler)
     int func (par)  /* OK */    int func (int par)  /* NOT OK */
       int par;
   Function headers should also be written in the following style:
     int
     func (par1, par2)
         int par1;
         int par2;
o  #define's should be used in place of hard coded values. 
o  Tabstops of 4 characters.
o  Comments should be copious and of the following form:
     /*
      * comment text
      */

Patches should only be sent to me as a context diff against a virgin
release of tin. I personally use 'diff -rcs olddir newdir'.

Hack on!

Iain