-------------------------------------------------------------------------------
help for inccat                                                  (Roger Newson)
-------------------------------------------------------------------------------


Concatenate one or more input files to an output file inserting additional inpu
> t files

        inccat infilename_list , to(outfilename) [ replace
               prefix(prefix_string) postfix(postfix_string) hmax(#)

where infilename_list is a list of names of existing text files separated by
spaces.


Description

inccat ("include and concatenate") takes, as input, a list of one or more input
files, and concatenates them to an output file.  Optionally, one or more of the
input files may contain one or more lines beginning with a user-specified
prefix and continuing with a list of valid file names belonging to additional
input files, and each such line is replaced in the output file by the contents
of these files. These additional input files can contain prefixed lines with
lists of further additional input files, which are also included in the same
way.


Options

to() specifies an output file, to be created by inccat, containing the
    concatenation of the input files, including additional input files listed
    in prefixed lines.

replace specifies that, if a file exists with the name specified by to(), then
    that file is to be overwritten.

prefix(prefix_string) specifies a prefix string. If prefix() is specified, then
    lines in the input files beginning with prefix_string will be assumed to
    contain a list of one or more file names, and the line is replaced in the
    output file by the contents of these files.  The prefix string may contain
    spaces, but must be at the beginning of a line to be recognised.

postfix(postfix_string) specifies a postfix string. If prefix() and postfix()
    are both specified, then the postfix string acts as a terminator for file
    lists in lines beginning with the prefix string. The postfix string must be
    a valid Stata token, and therefore must be separated from the last file in
    the list by at least one space, and may not contain spaces, except if it
    begins and ends with quotes. If prefix() is not specified, then postfix()
    is ignored.

hmax(#) specifies the maximum height of a family tree where the nodes are input
    files, the root is one of the original list of input files in
    infilename_list, and the daughters of any input file are the input files
    named in prefixed lines in that file. In default, this maximum height is
    31. If an input file of generation hmax contains any prefixed lines, then
    these prefixed lines are copied to the output file, not replaced by the
    contents of the files listed in these prefixed lines. The option hmax
    exists to prevent {inccat} from attempting to create infinite files, as
    might happen if an input file contains a prefixed line listing itself.


Remarks

inccat is an extended version of copy. The file inclusion enabled by prefixed
lines is useful if the user wants to create HTML files containing tables with
rows created by listtex (downloadable from SSC) and updated from time to time.
inccat takes advantage of the fact that the Stata language is recursive (like C
or Pascal), so that a program can call itself.


Examples

                . inccat myfile1.txt myfile2.txt myfile3.txt myfile4.txt,
                    to(mynewfile1.txt) replace

                . inccat myfile1.txt myfile2.txt myfile3.txt myfile4.txt,
                    to(mynewfile2.txt) pre(!include) replace

The following advanced example uses prefixed lines to create an updatable HTML
file with a table containing some of the auto data. Suppose the user has a file
auto1_r.htm, containing HTML code for the heading (but not the rows) of a
simple table, as follows:

                <table border="1">
                <caption>Weight and mileage in US and non-US cars</caption>
                <tr><th>Make</th><th>Origin</th><th>Weight
                    (lbs.)</th><th>Mileage (mpg)</th></tr>
                <!--include rows1.htm -->
                </table>

Note that the fourth line (<!--include rows1.htm -->) is a comment in HTML.  If
the user has the listtex package, downloadable from SSC, then s/he might then
type, in Stata:

                . listtex make foreign weight mpg using rows1.htm, b(<tr><td>)
                    d(</td><td>) e(</td></tr>) replace
                . inccat auto1_r.htm, to(auto1.htm) prefix(<!--include)
                    postfix(-->) replace

The first line will use listtex to create a text file rows1.htm, containing the
table rows.  The second line will use inccat to copy auto1_r.htm to auto.htm,
replacing the line

                <!--include rows1.htm -->

with the table rows in rows1.htm. The file auto1.htm will then contain a simple
HTML table giving weight and mileage in US and non-US cars. The user can update
the table, if the auto data set is ever updated.

Similar things can be done with stata.toc files in a user's website, if the
user wishes to keep the lines beginning with p and listing packages in one file
(revised regularly by listtex) and the other lines in another file (revised
occasionally). See on-line help for net.


Author

Roger Newson, Imperial College London, UK.  Email: r.newson@imperial.ac.uk


Also see

 Manual:  [R] copy, [R] shell, [R] net
On-line:  help for copy, shell, net
          help for listtex if installed