=begin COMMENT -*-mode: indented-text; auto-fill:t-*-

newfile-man.pod

Copyright (c) 2002 Alan Eldridge <alane@geeksrus.net>.
All rights reserved.


2002-12-13 Alan Eldridge <alane@geeksrus.net>

=end COMMENT

=head1 NAME

newfile - create new files from templates

=head1 SYNOPSIS

This man page documents newfile v. 1.0.13.

This is newfile v. 1.0.11.
Release: "Plastic leather, 13DDD"

Copyright (c) 2002-2003 Alan Eldridge <alane@geeksrus.net>.
All rights reserved.

usage:	newfile -h

	newfile -V

  	newfile [options] -s|--show

	newfile [options] -D<project>

	newfile [options] -d<template>

	newfile [options] -t<template> <file> ...

	newfile [options] -p<template>.<projectname> [<dir>]
		(note: <dir> defaults to <projectname> if omitted)

    -h, --help                       Show this help.
    -V, --version                    Show version and copyright.
    -v, --verbose                    Turn on verbose messages.
    -l, --license=LICENSE            Set license type.
    -t, --filetype=TEMPLATE          Set file TEMPLATE to use.
                                     Do *not* use with -p/--project.
    -p=TEMPLATE.PROJECTNAME          Set project TEMPLATE to use, and
                                     PROJECTNAME of project being built.
                                     Do *not* use with -t/--filetype.
        --project
    -s, --show                       Show installed file templates, project
                                     templates, and license types.
    -P, --pdoc=PROJECT               Show embedded docs for PROJECT.
    -T, --doc=TEMPLATE               Show embedded docs for TEMPLATE.
    -x, --exec-bit                   Make the resulting file executable.
                                     This option has no effect if a project
                                     template is selected.
    -a, --author=AUTHOR              Set name of author.
    -e, --email=EMAIL                Set author's email address.
    -o, --organization=ORGANIZATION  Set author's organization name.
    -c, --owner=COPYRIGHT_OWNER      Set copyright owner's name.
    -I, --include=DIR                Add DIR to search path.
    -D, --define=VAR[=value]         Define a variable. Value defaults to 1.

=head1 DESCRIPTION

B<newfile> is a program for creating starter files, or trees of files,
by processing templates with a C-preprocessor-like syntax.

=head2 Finding templates

=head3 Directory searching

Templates and projects (file tree templates) are found by looking in
the search path for a directory containing the template file(s).
For each directory in the search path, three subdirs are searched:
C<licenses>, C<projects>, and C<templates>.

The user can create a directory hierarchy $HOME/.newfile in which
to place new or modified templates and projects. This directory 
is searched before the system include directory. It should
have the appropriate subdirectories for C<licenses>, C<projects>, and/or
C<templates>, just like the system include directory. 

Other search directories can be added with the C<-I/--include> command line
option. They will be searched before either the user's include directory
or the system include directory, in the reverse order from that given on
the command line.

=head3 Naming template files

Unlike older versions of this program, template subdirectories are always
just 1 level deep. That is, e.g., the C<templates> subdirectory will not
have any subdirectories of its own. This simplifies the searching process
immensely; in return, files must be named according to specific rules.

For file templates, the name should be C<tmpl@FILETYPE>, where C<FILETYPE>
is the value given to the C<-t/--template> command line option. E.g., the
template for ruby files (C<-t rb>) is C<tmpl@rb>. These files are all located
in the C<templates> subdirectory of each directory on the search path.

For license templates, the name should be C<LTYPE@REALNAME>, where C<LTYPE>
is the value given to the C<-l/--license> command line option, and 
C<REALNAME> is the actual name of the file. These files are all located
(by convention) in the C<licenses> subdirectory of each directory on the
search path.

For project templates, the naming convention is similar to that for
licenses, with the added feature that a "!" in the filename indicates
a "/" in the final directory name. This is how subdirectories in the
project are specified. E.g., C<auto@src!Makefile.am> means the file
C<Makefile.am> in the C<src> subdirectory of the project directory. These
files are all located (by convention) in the C<projects> subdirectory
of each directory on the search path.

=head2 Variables

=head3 Builtins

Some variables are built into the system, and should always be defined.
Some will get default values if not defined.

=over

=item TEMPLATE

The name of the template used to construct the current project or file(s).

=item NAME

The name of the input file, minus any directory prefix.

=item NAMEID

An identifier based on NAME.

=item PROJECT

If a project template is being expanded, this is the name of the template.

=item PROJECTID

An identifier based on PROJ.

=item LICENSE

Defined by the command line option C<-l/--license>. Licenses are a special
case of project templates, and their files are mixed in with a project
template's file. In the case of a single file, the value of LICENSE
determines which directory to search for a file called "license" that is
included in the generated file.

=item AUTHOR

Defined by the command line option C<-a/--author>. The name of the author
of the code or document. If not given, taken from the user's full name in
the C</etc/passwd> file.

=item EMAIL

Defined by the command line option C<-e/--email>. If not given, constructed
from the user's login name and the hostname.

=item ORGANIZATION

The organization to which the author belongs, in the context of the code or
document being created. If not given, defaults to the value of AUTHOR.

=item OWNER

Defined by the command line option C<-o/--owner>. The owner of the
copyright. May be an arbitrary string, or one of the special strings "org",
"organization", or "author". If not given, defaults to "author".

=item BODY

If defined, indicates to many templates to include extra boilerplate 
text to define a skeleton body for the file. See the individual templates
for details. The shell and ruby templates are especially good examples,
since these are the languages I've been using most and these templates
have received the most attention to detail.

=item c(omment)

The value of a leading string to be prefixed to text in a comment
block. This is handled entirely within the templates themselves.

=back

=head3 Getting a variable's value

The syntax <:VARIABLE> will be substituted with the value of the
variable.  If the variable does not exist, it will be replaced with the
string "*UNDEFINED*".

=head3 Checking if a variable is defined

The special function I<defined("VARIABLE")> can be used in preprocessor
conditionals (L<"Preprocessor directives">) to test if a variable is defined
or not. 

B<Note:> the quotes around the variable name are required.

=head2 Files

=head3 Checking if a file exists

The special function I<exists("filename")> can be used in preprocessor
conditionals (L<"Preprocessor directives">) to test if a variable is defined
or not. 

B<Note:> the quotes around the filename are required.

B<Note:> Relative paths are evaluated relative to the directory
from which B<newfile> was run. (B<newfile> does not change directory
in the course of execution.)

=head2 Line continuation

Lines used to control the preprocessor (L<"Preprocessor directives">) may
be continued by ending the line with the characters "%+". No spaces may
appear after these characters in order for the line to be continued.

=head2 Preprocessor directives

The pre-processor supports a set of directives very similar to the C
preprocessor. The leading character for all directives in "%", and must
occur in the first column of the line.

=over

=item %define VAR [VALUE]

Define or redefined a variable. One layer of quotes is stripped from the
optional value unless the open quote is preceded by a literal backslash
("\"). The default value is "1".

=item %undef VAR

Undefine a variable, if it is defined.

=item %license

Insert the contents of the currently defined license header.
This is a file called, e.g., C<LTYPE@license.inc>, where LTYPE is the
license type, such as BSD or GPL. 

=item %include <file>

Insert the contents of "file" at this point. The file is found by
searching the current search path. Variable substitution is performed
on "file", so C<%include E<lt>E<lt>:BODYE<gt>E<gt>> will include the
file whose name is in the variable C<BODY>.

=item %if COND-EXPRESSION

Test a conditional expression. Expressions are evaluated by the Ruby
interpreter after variable substitution. The text up to the next matching
C<%elif>, C<%else>, or C<%endif> is used if the expression is true.

=item %elif COND-EXPRESSION

Shorthand for C<%else>, followed by C<%if>, but saves an extra C<%endif>.

=item %else

The text up to the matching C<%endif> if used if the previously tested
condition(s) was/were false.

=item %endif

Ends a C<%if/%elif/%else> sequence.

=item %metastr STR

Sets the string used to start preprocessor directives to STR. It is
initially set to C<%>. This directive remains in effect only until the
end of the file in which it occurs. It cannot be used in an
included file to change the interpretation of the enclosing file.

B<Note:> If the template needs to include a license file, it would 
be a good idea to wait until after that is done before using this
directive.

B<Note:> This directive was added specifically to allow creation of
MagicPoint templates, which have a C<%if> statement. To avoid confusion,
try to avoid its use wherever possible.

=item %metapush STR

Sets the string used to start preprocessor directives to STR. It is
initially set to C<%>. This directive remains in effect only until the
C<?metapop> directive is encountered. All C<%metapush> directives are
undone at the end of the file in which they were found.

=item %metapop

Sets the string used to start preprocessor directives to what it was
before the most recent C<%metapush>.

=item %end

Causes the preprocessor to ignore the rest of the file. You can, e.g., put
documentation about the template after a C<%end>.

=back

All other lines are either copied with variable substitution, or ignored,
depending on the current conditional state.

=head1 DIAGNOSTICS

The preprocessor attempts to issue error messages that are as accurate
as possible. Each error message is formatted like B<gcc>'s error messages,
and shows the included files leading up to the point of the the error.

=head1 ENVIRONMENT

=over

=item NEWFILE

String containing default command line options. Normal shell quoting
conventions apply.

=back

=head1 FILES

=over

=item *

$HOME/.alane-newfile/*

=item *

$PREFIX/share/alane-newfile/*

=back

=head1 CAVEATS

=over 

=item *

Does not check before overwriting existing files.

=back

=head1 BUGS

=over

=item *

Doesn't always issue good error messages and exit gracefully if bad input is
given. Too much of the Ruby exception mechanism may be exposed to the user.

=back

=head1 RESTRICTIONS

See the BSD License in the file "LICENSE" in the source distribution.

=head1 NOTES

There's still room for improvement, but the basic engine is solid. What is
needed now are more templates, and getting all the templates documented.

A command line option to fetch template documentation after a %end would
be really nice, too.

=head1 AUTHOR

AlanE@geeksrus.net

=head1 HISTORY

This is the third rendition of this program, written first in shell, 
then in Python, and finally in ruby. In this case, I think ruby allows easier
transition from intent to code than Python.