includefile(release.yo)

htmlbodyopt(text)(#27408B)
htmlbodyopt(bgcolor)(#FFFAF0)
whenhtml(mailto(Frank B. Brokken: f.b.brokken@rug.nl))

DEFINEMACRO(sop)(3)(\
    it() bf(-ARG1) ARG2 nl()ARG3\
)

DEFINEMACRO(itt)(1)(\
    it()tt(ARG1)\
)

DEFINEMACRO(itb)(1)(\
    it()bf(ARG1)nl()\
)

DELETEMACRO(tt)
DEFINEMACRO(tt)(1)(em(ARG1))

COMMENT( man-request, section, date, distribution file, general name)
manpage(icmstart)(1)(_CurYrs_)(icmake._CurVers_.tar.gz)
        (starts icmbuild program maintenance)

COMMENT( man-request, larger title )
manpagename(icmstart)(A startup script for icmbuild program maintenance)

COMMENT( all other: add after () )
manpagesynopsis()
       bf(icmstart) tt([Options]) top-dir [program|library]

manpagedescription()

The bf(icmstart) script is a generic script that can be used to start program
maintenance using bf(icmake)(1) and bf(icmbuild)(1). bf(Icmstart) creates
an initial directory tt(top-dir) and installs the files tt(CLASSES,
VERSION) and tt(icmconf) below tt(top-dir). A second argument  `tt(program)'
or `tt(library)' may be specified as the default mode of operation of the
bf(icmbuild)(1) script. 

Skeleton files for the main directory and subdirectories, by default listed in
the file tt(/etc/icmake/icmstart.rc), may be installed as well
(cf. bf(icmstart.rc)(7)).

After changing to the directory created by bf(icmstart) the bf(icmbuild)(1)
script may be used for program maintenance.

manpageoptions()

    tt(Icmstart) may be called with the following options, which (if specified)
    must be the first arguments of tt(icmstart):
    itemization(
    itt(-c confpath)nl() Use the configuration files (tt(icmstart.rc, AUTHOR,
        YEARS) and tt(VERSION)) if found in `confpath' rather than in
        tt(~/.icmake) and/or tt(/etc/icmake/). Once a file is found it is used
        allowing partial overrides of the default files provided by
        bf(icmake)(1).
    itt(-d)nl()
       Do not execute any commands, but show the commands that would have been
        executed on the standard output.
    itt(-I)nl()
       Do not install files. 
    itt(-r) 
       Unconditionally replace existing files. If tt(-r) is not
        provided bf(icmstart) will ask the user to confirm that an existing
        file must
        be overwritten. If a skeleton specification refers to a directory, the
        full directory and its subdirectories will be replaced.
    itt(-s skeleton-path) nl() 
       By default skeleton files are listed in the skeleton resource file
        tt(/usr/share/icmake/icmstart.rc). Alternatively, the skeleton
        resource file may be specified by the tt(ICM) environment variable,
        which -in turn- may be overruled by the path specified with the tt(-s)
        option. The skeleton path may be specified as a full file-path or as a
        directory, in which case the skeleton resource file is assumed to be
        tt(icmstart.rc) (see below at bf(SKELETON FILES)).
    )
    Since bf(icmstart) uses tt(cp) to install files, tt(cp) must be
available when bf(icmstart) should install skeleton files.

manpagesection(SKELETON FILES)

Skeleton resource files may contain comment (empty lines and lines beginning
with the hash-mark (tt(#))) which is ignored, and should otherwise contain
specifications of resource file(s) to install.

The default resource file is tt(/etc/icmake/icmstart.rc), contains
        verb(
    CLASSES
    P main.cc 
    P main.ih 
    P usage.cc
    P version.cc
    P ? scanner 
    P ? parser  
        )
    This file is overruled by tt(~/.icmake/icmstart.rc). See
bf(icmstart.rc)(7) for details about the format of the tt(icmstart.rc) file.

manpagesection(CONFIGURATION FILES)

    The configuration files tt(icmstart.rc, AUTHOR, YEARS) and tt(VERSION) are
recognized and processed by tt(icmstart). 

If the tt(-c) option was specified configuration files found in the path
specified at this option are used. If not specified or if a file isn't
found then the path tt(~/icmake) is inspected. If a configuration file isn't
found in tt(~/icmake) either, configuration files in tt(/etc/icmake) are used.

Configuration files are not required for the proper operation of tt(icmstart).
When absent tt(icmstart) performs the following  default actions:

    itemization(
    it() If the file tt(AUTHOR) does not exist tt(icmstart) uses tt(#define
AUTHOR ""). 

    When the file tt(AUTHOR) is defined in a configuration path it should have
one line, defining the author of the program. E.g.,
        verb(
    #define AUTHOR "Frank B. Brokken <f.b.brokken@rug.nl>"
        )

    it() If the file tt(VERSION) does not exist tt(icmstart) uses tt(#define
VERSION "0.00.00"). 

    When the file tt(VERSION) is defined in a configuration path it should
have one line, defining the program's initial version. E.g.,
        verb(
    #define VERSION "1.00.00"
        )


    it() If the file tt(YEAR) does not exist tt(icmstart) uses tt(#define
YEARS "yyyy") where tt(yyyy) is the current year. 

    When the file tt(YEAR) is defined in a configuration path it should have
one line, defining the program's initial release year. E.g.,
        verb(
    #define YEARS "2012"
        )
    Plural is used here since a release year usually becomes a range of years
after some time, as with Icmake's years specification:
        verb(
    #define YEARS "1992-2012"
        )
    )

    it() If the file tt(icmstart.rc) does not exist (or is empty) tt(icmstart)
will not install any of the files normally found in tt(icmstart.rc), but the
initial project directory, tt(icmconf) and tt(VERSION) are installed.
    )

manpagefiles()
    The mentioned paths are sugestive only and may be installation dependent:
    itemization(
    it() bf(/usr/share/icmake/icmconf)
        Example of a bf(icmbuild) configuration file;
    it() bf(/usr/share/icmake/CLASSES)
        Example of a bf(icmbuild) tt(CLASSES) file.
    it() bf(/usr/share/icmake/icmstart.rc)
        Default skeleton resource file.
    )

manpageseealso()
    bf(icmake)(1), bf(icmbuild)(1), bf(icmconf)(7), bf(icmstart.rc)(7).

manpagebugs()
    None reported

includefile(trailer.inc)
