README
indent (development release)
by Aaron Hawley
$Id: README,v 1.2 2002/12/01 04:44:21 ashawley Exp $

INTRO

What works so far.

A system for handling command-line arguments has been put together,
including setting the default values, reading the arguments, setting these
command-line arguments, then printing out the command-line options that
this results in.  This system is very unstable and has serious memory
problems.  It appears to be the fault of the getopt.h library (or the
misuse of it).  Any debugging on this would be appreciated.

So far this command-line does not handle version, usage or help screens,
but shouldn't be hard to add.

The accuracy of this command-line also needs to be fully verified, in
terms of whether the input command-line arguments are the same as the
output ones.  This could be tested with streaming files with command line
arguments to the program and comparing its output (using `diff`?).  Also,
the accuracy of default settings also needs to be verified.  A weak
attempt was made to deduce the default settings by wading through the
sparse documentation file and obfiscated code of the current indent
(version 2.2.8).

Currently, the settings system structure contains a variable for every
setting specified on the command line.  Boolean variables are provided for
"on" or "off" type variables and integer variables for variables which
require a number.  It is unclear whether certain boolean variables
actually need to be set to "on", "off" and "neither" (or "ignore", or
"null").  It was unclear from the documentation whether failing to setting
an option results in neither the "on" or the "off" setting to actually be
used.  For example, if the user fails to specify --line-length, will
indent enforce a line length?  The default GNU style doesn't seem to
specify a --line-length.

The code also makes reference to "eei" (and its complement "neei"), extra
expression indent, what's its deal?  Also the code specifies a few more
options that aren't documented:

--berkely and --berkely-style (for -orig)
--c-plus-plus (for -c++)
--kernighan-and-ritchie-style and --kernighan-and-ritchie (for -kr)
--original-style (for -orig)
--no-Bill-Shannon and --no-blank-before-sizeof (for -nbs)
--no-blank-lines-after-procedure-declarations (for -nbapd)
--remove-preprocessor-space (for -nlps opposite of -lps)
--usage and --help (for -h)

These and probably others need to be dealt with and documented more
clearly.

The profile file system also needs to be added (".indent.pro").  There is
a strict manner in which indent needs to locate a profile file
(environment variable, current directories and home directories),
including being able to ignore profile files with the ---ignore-profile
(-npro).  The contents of these files just need be passed onto the command
argument parser and the option setting.

This should provide some of the foundations for indent to do the important
work which is reading source files and changing them.  Thus far the only
thing keeping from easy portability is the use of GNU's getopt_long and
getopt_long_only.  Otherwise it compile fine on a few Unices and even on
Windows.  The getopt situation should probably be remedied by something
else.  Although the current command line and indent settings are pretty
clean, a better solution could be fashioned for handling indent (insert
any application's name) for handling command line arguments (yes,
improving from getopt.h and argp).

An actual structure for handling all these inter-related options and
command line options should be made.  A structure should

-make relations between duplicate arguments
-makes associations between arguments and their settings variable
-associates settings variables to arguments strings
-associates or provides methods
	- store a string
	- convert string to integer and store
	- set as true or false
-associate options to usage information

Each of these features have been provided by getopt.h and argp.h.  
However, a final solution would incorporate the above features, but would
also incorporate this with documentation (man pages, makeinfo, web pages),
a necessity for long term applications. This could be solved by setting
this all up with an XML document type that specifies all the above
information of the structure, and can subsequently be used to create
documentation and source files.

MAKE

The makefile is meant for GNU make (version 3.79.1).

The code is targeted for GNU gcc, but the compiler and the compiler flags
can be set with CC and CFLAGS, respectively. For example:
	make CC=cc CFLAGS=-g indent

Here are some rules in the makefile that is included ("Makefile"):

make indent - Builds an indent binary and dependecies using main.c for 
              main().
make test - Builds the indent and its dependecies  test.c for main().
make clean - Remove (with ${RM} = rm) binaries, object files, core, tilde 
             (~) ending, and the release files (made by bz2, gz, zip and 
             tar rules).
make bz2 - Calls bzip2 and makes a bz2 file from the tar of source files 
           (keeps tar file).
make gz - Calls gzip and makes a gz file from the tar of source files 
          (removes the tar file).
make tar - Makes a tar file from the source files and other release files.
make zip - Calls zip and makes a zip file from the source files and other 
           release files.

LOG
$Log: README,v $
Revision 1.2  2002/12/01 04:44:21  ashawley
-Added nots on portability.
-Added notes on command line options.
-Added mention of need of beter structure for settings and command line
 options.
-Added proposal of an XML document for settings and command-line options.

Revision 1.1  2002/12/01 04:11:54  ashawley
Initial revision