Hackers notes for tin - 25-05-94
--------------------------------

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 HOWTOGET 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
with the P_() macro surrounding the parameters (look at the file
and you'll see what I mean).

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 t_grp *active               /* array of groups in active file  */
        struct t_attrib attribute      /* group specific attributes       */ 

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

    struct t_filter *filter            /* global filters (select & kill)  */

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

    struct t_save *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  Functions common in functionality begin with a common identifer:
     Art  article
     Bit  bitmap
     Cfg  config
     Dbg  debug
     Fil  filter
     Grp  group
     Scr  screen
     Thd  thread
     Utl  utility
o  Comments should be copious and of the following form:
     /*
      * comment text
      */
o  A variable/function naming scheme is employed to aid in readability:
     Simple types:        Complex types:
       c  char              a  array
       d  double            p  pointer 
       h  handle            s  struct
       i  int               t  type
       l  long
       u  unsigned
       v  void

   Example:
     void
     vFuncName (iNumMax, pcStr)
         int    iNumMax;
         char   *pcStr;
     {
         char *pcPtr;
         FILE *hFp;
         int  iNum;

         pcPtr = pcStr;

         for (iNum = 0 ; iNum < iNumMax ; iNum++) {
             printf ("%s", pcPtr);
         }
     }

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

Hack on!

Iain
